OpenCode officially documents ~/.config/opencode/plugins/ (plural) as the
plugin directory. Our docs previously used plugin/ (singular), which also
works but caused confusion.
Changes:
- Renamed .opencode/plugin/ to .opencode/plugins/ in repo structure
- Updated INSTALL.md to use plugins/ everywhere
- Updated README.opencode.md (all platforms: Linux, macOS, Windows CMD,
PowerShell, Git Bash) to use plugins/
- Updated test scripts to match
Tested: Both singular and plural forms work, but we now match official docs.
Fixes#343
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Breaking changes:
- OpenCode: Switched to native skills system (migration required)
Fixes:
- OpenCode: Fixed agent reset on session start (#226)
- OpenCode: Fixed Windows installation (#232)
- Claude Code: Fixed Windows hook execution for 2.1.x
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: convert shell scripts from CRLF to LF line endings
Add .gitattributes to enforce LF line endings for shell scripts,
preventing bash errors like "/usr/bin/bash: line 1: : command not found"
when scripts are checked out on Windows with CRLF.
Fixes#317 (SessionStart hook fails due to CRLF line endings)
Files converted:
- hooks/session-start.sh
- lib/brainstorm-server/start-server.sh
- lib/brainstorm-server/stop-server.sh
- lib/brainstorm-server/wait-for-feedback.sh
- skills/systematic-debugging/find-polluter.sh
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: update Windows hook execution for Claude Code 2.1.x
Claude Code 2.1.x changed the Windows execution model: it now auto-detects
.sh files in hook commands and prepends "bash " automatically. This broke
the polyglot wrapper because:
Before: "run-hook.cmd" session-start.sh (wrapper executes)
After: bash "run-hook.cmd" session-start.sh (bash can't run .cmd)
Changes:
- hooks.json now calls session-start.sh directly (Claude Code handles bash)
- Added deprecation comment to run-hook.cmd explaining the change
- Updated RELEASE-NOTES.md
Fixes#317, #313, #275, #292
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* fix use_skill agent context (#290)
* fix: respect OPENCODE_CONFIG_DIR for personal skills lookup (#297)
* fix: respect OPENCODE_CONFIG_DIR for personal skills lookup
The plugin was hardcoded to look for personal skills in ~/.config/opencode/skills,
ignoring users who set OPENCODE_CONFIG_DIR to a custom path (e.g., for dotfiles management).
Now uses OPENCODE_CONFIG_DIR if set, falling back to the default path.
* fix: update help text to use dynamic paths
Use configDir and personalSkillsDir variables in help text so paths
are accurate when OPENCODE_CONFIG_DIR is set.
* fix: normalize OPENCODE_CONFIG_DIR before use
Handle edge cases where the env var might be:
- Empty or whitespace-only
- Using ~ for home directory (common in .env files)
- A relative path
Now trims, expands ~, and resolves to absolute path.
* feat(opencode): use native skills and fix agent reset bug (#226)
- Replace custom use_skill/find_skills tools with OpenCode's native skill tool
- Use experimental.chat.system.transform hook instead of session.prompt
(fixes#226 agent reset on first message)
- Symlink skills directory into ~/.config/opencode/skills/superpowers/
- Update installation docs with comprehensive Windows support:
- Command Prompt, PowerShell, and Git Bash instructions
- Proper symlink vs junction handling
- Reinstall safety with cleanup steps
- Verification commands for each shell
* Add OpenCode native skills changes to release notes
Documents:
- Breaking change: switch to native skill tool
- Fix for agent reset bug (#226)
- Fix for Windows installation (#232)
---------
Co-authored-by: Vinicius da Motta <viniciusmotta8@gmail.com>
Co-authored-by: oribi <oribarilan@gmail.com>
Addresses failure mode where Claude skips skill invocation even when
user explicitly requests it by name (e.g., "subagent-driven-development,
please").
Skill changes:
- "Check for skills" → "Invoke relevant or requested skills"
- "BEFORE ANY RESPONSE" → "BEFORE any response or action"
- Added reassurance that wrong skill invocations are okay
- New red flag: "I know what that means"
Tests:
- New test suite for explicit skill requests
- Single-turn and multi-turn scenarios with --continue
- Tests with haiku model and user CLAUDE.md
- Added disable-model-invocation to /brainstorm, /execute-plan, /write-plan
- Commands now restricted to manual user invocation only
- Underlying skills remain available for autonomous invocation
Added disable-model-invocation: true to /brainstorm, /execute-plan, and
/write-plan commands. Claude can still invoke the underlying skills
directly, but the slash commands are now restricted to manual user
invocation only.
Fixes pattern where Claude would invoke a skill then try to Read the
file separately. The Skill tool already provides the content.
- Add "How to Access Skills" section to using-superpowers
- Change "read the skill" → "invoke the skill"
- Commands now use fully qualified names (superpowers:brainstorming etc)
- Rewrite release notes centering new features (two-stage review,
debugging tools, test infrastructure)
- Bump version to 4.0.0 in plugin.json and marketplace.json
- Remove .claude/settings.local.json from tracking
- Add .claude/ to .gitignore
Testing revealed that descriptions summarizing workflow cause Claude to
follow the description instead of reading the skill body. Changed all
descriptions to "when to use" triggers only:
- dispatching-parallel-agents: 2+ independent tasks without shared state
- executing-plans: have a written plan to execute with review checkpoints
- requesting-code-review: completing tasks, features, or before merging
- systematic-debugging: encountering bugs before proposing fixes
- test-driven-development: implementing features before writing code
- writing-plans: have spec/requirements for multi-step task before coding
- writing-skills: updated with "description trap" documentation
The description trap: workflow summaries in descriptions create shortcuts
Claude takes, skipping the skill body entirely.
Testing revealed that skill descriptions summarizing workflow cause
Claude to follow the description instead of reading the skill body.
- A description saying "code review between tasks" caused ONE review
- The flowchart clearly showed TWO reviews (spec compliance + quality)
- Minimal description ("Use when...") correctly deferred to flowchart
Updated writing-skills with:
- "Description = When to Use, NOT What the Skill Does" section
- Cautionary tale about this actual failure
- Examples of good (triggers only) vs bad (workflow summary) descriptions
Updated subagent-driven-development:
- Removed workflow summary from description
- Now just: "Use when executing implementation plans..."
Updated test runner:
- Added --dangerously-skip-permissions for automated testing
Two test projects for validating the skill with full end-to-end runs:
- go-fractals: 10 tasks, CLI tool with Sierpinski and Mandelbrot
- svelte-todo: 12 tasks, CRUD app with localStorage and Playwright
Each test has design.md, plan.md, and scaffold.sh. Run with:
./tests/subagent-driven-dev/run-test.sh go-fractals
Move condition-based-waiting, defense-in-depth, and root-cause-tracing
into systematic-debugging as progressive disclosure supporting files.
These techniques are now available as reference material within the
systematic-debugging skill directory, reducing skill count while keeping
content accessible when needed.
Note: Claude Code's SLASH_COMMAND_TOOL_CHAR_BUDGET env variable silently
limits skill discovery, which drove this consolidation to ensure core
skills remain visible.
- Update brainstorming description to use imperative "You MUST use this"
- Clarify trigger: "before any creative work - creating features, building
components, adding functionality, or modifying behavior"
- Add Skill Priority section to using-superpowers to ensure process skills
(brainstorming, debugging) are invoked before implementation skills
- Moved testing-skills-with-subagents to writing-skills/testing-skills-with-subagents.md
- Moved examples/ directory to writing-skills/examples/
- Updated writing-skills to reference via @testing-skills-with-subagents.md
- Updated README to reflect consolidation
- Removed standalone skill (now a supporting reference)
- Moved testing-anti-patterns to test-driven-development/testing-anti-patterns.md
- Added reference in TDD skill for progressive disclosure
- Updated README to reflect consolidation
- Removed standalone skill (now a supporting reference)
The contribution workflow is now via standard GitHub PR process,
not a dedicated skill. The skill was documenting an old workflow
that no longer applies.
Tested against claude -p with multiple scenarios. Key fixes:
- Clarify skill check comes BEFORE ANY response including clarifications
- Add rationalizations: "I need more context first", "Let me explore first", "This feels productive"
- Flowchart entry point now "User message received" → clearer blocking gate
- Shorter, more scannable format (flowchart + table)
Verified: "Fix login bug" now triggers systematic-debugging first
Documents:
- How to run integration tests
- subagent-driven-development test details
- Token analysis tool usage
- Troubleshooting common issues
- Writing new integration tests
- Session transcript format
- Rewrote analyze-token-usage.py to parse main session file correctly
- Extracts usage from toolUseResult fields for each subagent
- Shows breakdown by agent with descriptions
- Integrated into test-subagent-driven-development-integration.sh
- Displays token usage automatically after each test run
The skill instructions are internal and don't appear in user-facing
output. Updated verification to parse the session JSONL transcript
and check for actual tool usage:
- Skill tool invocation
- Task tool (subagents)
- TodoWrite (tracking)
- Implementation results
The superpowers-dev marketplace makes skills available only when running
from the plugin directory. Updated test to run claude from superpowers
directory while working on the test project.
Claude Code headless mode requires --allowed-tools flag to actually
execute tool calls. Without it, Claude only responds as if it's doing
things but doesn't actually use tools.
Changes:
- Updated run_claude helper to accept allowed_tools parameter
- Updated integration test to use --allowed-tools=all
- This enables actual tool execution (Write, Task, Bash, etc.)
Now the integration test should actually execute the workflow instead
of just talking about it.
Simplified command substitution to avoid shell parsing issues.
Instead of nested heredoc in command substitution, write prompt
to file first then read it.
Created full end-to-end integration test that executes a real plan
and verifies the new workflow improvements actually work.
New test: test-subagent-driven-development-integration.sh
- Creates real Node.js test project
- Generates implementation plan (2 tasks)
- Executes using subagent-driven-development skill
- Verifies 8 key behaviors:
1. Plan read once at beginning (not per task)
2. Full task text provided to subagents (not file reading)
3. Subagents perform self-review
4. Spec compliance review before code quality
5. Spec reviewer reads code independently
6. Working implementation produced
7. Tests pass
8. No extra features added (spec compliance)
Integration tests are opt-in (--integration flag) due to 10-30 min runtime.
Updated run-skill-tests.sh:
- Added --integration flag
- Separates fast tests from integration tests
- Shows note when integration tests skipped
Updated README with integration test documentation.
Run with:
./run-skill-tests.sh # Fast tests only
./run-skill-tests.sh --integration # Include integration tests
Created automated test suite for testing superpowers skills using
Claude Code CLI in headless mode.
New files:
- tests/claude-code/run-skill-tests.sh - Main test runner
- tests/claude-code/test-helpers.sh - Helper functions for testing
- tests/claude-code/test-subagent-driven-development.sh - First test
- tests/claude-code/README.md - Documentation
Test framework features:
- Run Claude Code with prompts and capture output
- Assertion helpers (contains, not_contains, count, order)
- Test project creation helpers
- Timeout support (default 5 minutes)
- Verbose mode for debugging
- Specific test selection
First test verifies subagent-driven-development skill:
- Skill loading
- Workflow ordering (spec compliance before code quality)
- Self-review requirements
- Plan reading efficiency (read once)
- Spec compliance reviewer skepticism
- Review loops
- Task context provision
Run with: cd tests/claude-code && ./run-skill-tests.sh
Made sequencing explicit:
- Spec compliance review loop must fully complete (✅) before code quality
- Added "Do NOT proceed to code quality review until spec compliance is ✅"
- Code Quality Review section starts with "Only run after spec compliance review is complete"
- Red Flags: Added "Start code quality review before spec compliance is ✅ (wrong order)"
This ensures we don't waste time reviewing code quality of the wrong
implementation. Verify they built the right thing first, then verify
they built it well.
The spec compliance reviewer now:
- Does NOT trust implementer's report
- Is warned implementer finished suspiciously quickly
- MUST verify everything by reading actual code
- Compares implementation to requirements line by line
- Reports issues with file:line references
Key additions:
- "Do Not Trust the Report" section
- Explicit DO NOT / DO lists
- "Verify by reading code, not by trusting report"
- Changed "What Was Implemented" to "What Implementer Claims They Built"
This prevents rubber-stamping and ensures independent verification
of spec compliance against actual codebase.
Key improvements based on feedback:
1. Read plan once, not per task
- Extract all tasks in Step 1
- Reference extracted tasks in Step 2
- Eliminates redundant file reading
2. Enable questions during work
- Not just before, but also while working
- "It's always OK to ask questions"
- Don't guess or make assumptions
3. Add self-review before reporting
- Completeness: implemented everything?
- Quality: best work, clear names?
- Discipline: avoided overbuilding?
- Testing: comprehensive, real behavior?
- Catches issues before handoff
4. Add spec compliance review
- Separate reviewer checks: built the right thing?
- Flags missing requirements
- Flags extra/unneeded work
- Flags misunderstandings
- Runs BEFORE code quality review
5. Make reviews loops, not one-shot
- Reviewer finds issues
- Implementer fixes
- Reviewer reviews again
- Repeat until approved
- Applies to both spec and code quality
Two-stage review process:
- Stage 1: Spec compliance (right thing?)
- Stage 2: Code quality (built well?)
This enables subagents to do their best work with clear requirements,
opportunities to clarify, self-critique, and thorough review loops.
Changed workflow so controller provides complete task context directly
rather than making subagent read plan file.
Key changes:
- Controller reads plan and extracts full task text
- Controller provides scene-setting context (dependencies, architecture)
- Subagent receives complete information in prompt (no file reading)
- Subagent can ask clarifying questions before beginning work
- Controller handles questions/concerns before subagent proceeds
Benefits:
- No file reading overhead for subagent
- Controller curates exactly what context is needed
- Questions surfaced before work begins (not after)
- Subagent has complete information to do best work
This enables subagents to start with clarity rather than ambiguity.
Analyzed feedback from two Claude instances using superpowers in real
development scenarios. Identified 8 core problems and proposed improvements
organized by impact and risk.
Key problems:
- Configuration change verification gap (verify success not intent)
- Background process accumulation across subagents
- Context bloat in subagent prompts
- Missing self-reflection before handoff
- Mock-interface drift
- Code reviewer file access issues
- Skills not being read/enforced
- Fix workflow latency
Proposed improvements organized in 3 phases:
- Phase 1: High-impact, low-risk (do first)
- Phase 2: Moderate changes (test carefully)
- Phase 3: Optimization (validate first)
See plan for detailed analysis and open questions.
Fixed POSIX compatibility issue in hooks/run-hook.cmd that caused
"Bad substitution" errors on Ubuntu/Debian systems where /bin/sh is dash.
Changes:
- Replaced bash-specific ${BASH_SOURCE[0]:-$0} with POSIX-compliant $0
- Tested with both bash and sh (POSIX mode) on macOS
- Updated version to 3.6.2 in all required files
Fixes#141
New features:
- Cross-platform polyglot wrapper (run-hook.cmd) for Windows/Unix
- Pure bash JSON escaping for Windows compatibility
- Documentation for polyglot hooks setup
* feat: Add Windows support for session-start hook
- Create polyglot session-start.cmd that works in both CMD and bash
- Update hooks.json to use the .cmd polyglot launcher
- Replace sed/awk with pure bash for JSON escaping (Windows compatibility)
The polyglot script uses a heredoc trick:
- CMD sees the @echo off block and runs bash.exe with cygpath conversion
- Bash sees a heredoc and skips to the Unix section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Add execute permission to session-start.cmd for Unix
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: Add comprehensive polyglot hooks documentation
- Add docs/windows/polyglot-hooks.md explaining the cross-platform technique
- Add reusable run-hook.cmd wrapper for parameterized hook execution
- Document how the polyglot works in CMD vs bash
- Include troubleshooting section and related GitHub issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* test: Add polyglot hook test script for macOS/Linux
Run ./test-polyglot.sh from repo root to verify:
- Required files exist with execute permissions
- Simple wrapper (session-start.cmd) produces valid JSON
- Parameterized wrapper (run-hook.cmd) works
- Heredoc correctly skips CMD block on Unix
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Use direct pipe to jq in test to avoid variable escaping issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Use single reusable run-hook.cmd for all hooks
- Remove session-start.cmd in favor of run-hook.cmd
- Update hooks.json to use: run-hook.cmd session-start.sh
- Simplify test script to only test run-hook.cmd
This makes it easy to add more hooks - just create the .sh file
and add a line to hooks.json pointing to run-hook.cmd with the script name.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Simplify run-hook.cmd CMD block
Pass path directly to bash instead of using cygpath in a subshell.
The complex quoting was causing issues on Windows.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: Remove test-polyglot.sh
Testing complete - polyglot hooks work on Windows and macOS.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Switch from chat.message hook to session.created event for injecting
the using-superpowers skill content. The new approach:
- Injects at session creation via session.prompt() with noReply: true
- Explicitly tells model the skill is already loaded to prevent
redundant use_skill calls
- Consolidates bootstrap generation into getBootstrapContent() helper
- Removes fallback pattern in favor of single implementation
Tested with 10 consecutive test runs and manual skill trigger validation.
Create comprehensive tests in tests/opencode/ that verify the plugin
works correctly in an isolated test environment:
- setup.sh: Creates temp HOME and installs plugin with proper symlinks
- test-plugin-loading.sh: Verifies plugin structure and JavaScript syntax
- test-skills-core.sh: Unit tests for skills-core.js library functions
- test-tools.sh: Integration tests for use_skill/find_skills (requires OpenCode)
- test-priority.sh: Tests project > personal > superpowers priority
- run-tests.sh: Main test runner with options for integration tests
Run basic tests: ./tests/opencode/run-tests.sh
Run all tests: ./tests/opencode/run-tests.sh --integration
- Add project-local skills directory (.opencode/skills/) with highest priority
- Use client.session.prompt() with noReply for skill loading to persist across compaction
- Add session.compacted event handler to re-inject bootstrap after context compaction
- Update find_skills to list skills from project > personal > superpowers directories
- Support project: prefix for explicit project skill loading
- Keep chat.message hook as fallback for initial context injection
- Delete .opencode/prompts/superpowers.txt (no longer needed)
- Simplify INSTALL.md to remove prompt file copying and agent configuration steps
- Installation now relies on plugin's chat.message hook for automatic context injection
- Cleaner, simpler setup process with fewer manual configuration steps
OpenCode doesn't support injecting context through event hooks. Instead,
the plugin now generates a prompt file that agents can reference via
{file:./prompts/superpowers.txt} in their configuration.
- Replace CommonJS require() with ES import statements
- Use createRequire() for loading CommonJS skills-core module
- Export plugin as 'SuperpowersPlugin' named export
- Maintains compatibility with existing skills-core.js CommonJS module
