The tool mapping table is now @referenced directly in GEMINI.md so Gemini
CLI always has it in context when processing skills, rather than requiring
Gemini to find and read a reference file from within the skill.
Maps all Claude Code tool names to Gemini CLI equivalents (read_file,
write_file, replace, run_shell_command, grep_search, glob, write_todos,
activate_skill, etc.). Notes that Gemini CLI has no subagent support.
Updates using-superpowers to reference GEMINI.md in instruction priority
and link to the new gemini-tools.md reference alongside codex-tools.md.
Symlinks inside .gemini/ don't work on Windows. Moving
gemini-extension.json and GEMINI.md to the repo root means
the extension root IS the repo root, so skills/ is found
naturally without symlinks.
Symlinks .gemini/skills -> ../skills so the extension bundles
all Superpowers skills. Without this, skills are only found when
running from the repo workspace, not when installed as an extension.
Remove the custom MCP server (find_skills/use_skill tools) and
force-invoke GEMINI.md. Gemini CLI natively supports the Agent Skills
format — our skills/ directory works as-is.
GEMINI.md now uses @import to inline using-superpowers content at
session start. Needs testing to verify @import resolves relative
to the extension root.
Add experimental Gemini CLI extension with MCP server that exposes
skills as individual tools. Infrastructure works but auto-triggering
skills is blocked by Gemini CLI treating context files as advisory
rather than executable instructions.
See issue #128 for detailed findings.
- gemini-extension.json manifest
- MCP server with individual skill tools
- GEMINI.md bootstrap attempts (don't work)
- Installation documentation
After the spec review loop passes, the skill now asks the user to review
the written spec file before invoking writing-plans. This prevents the
agent from racing ahead to implementation planning without giving the
user a chance to read and adjust the written document.
Fixes#565
Last consumer (Codex bootstrap CLI) was removed on 2026-02-05.
Removes the library, its dedicated test file, and references
in test-plugin-loading.sh and run-tests.sh.
h/t @RomarQ (PR #525) for flagging this.
Executing-plans no longer pauses every 3 tasks for review. Also adds
a note encouraging users to use a subagent-capable platform for better
quality results.
Brainstorming now assesses whether a project is too large for a single
spec and helps decompose into sub-projects. Scope check is inline in
the understanding phase (testing showed it was skipped as a separate step).
Spec reviewer also checks scope. Writing-plans has a backstop.
Add design-for-isolation and working-in-existing-codebases guidance to
brainstorming. Add file size awareness and escalation prompts to SDD
implementer and code quality reviewer. Writing-plans gets architecture
section sizing guidance. Spec and plan reviewers get architecture and
file size checks.
- Subagent-driven-development is now mandatory when harness supports it
- No longer offer choice between subagent-driven and executing-plans
- Executing-plans reserved for harnesses without subagent capability
- Update plan header to reference both execution paths
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Specs (brainstorming output) now go to docs/superpowers/specs/
- Plans (writing-plans output) now go to docs/superpowers/plans/
- User preferences for locations override these defaults
- Update all skill references and test files
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implementation plan for the visual brainstorming companion, plus spec
and plan for the subsequent browser-displays refactor.
Co-Authored-By: Drew Ritter <drew@ritter.dev>
Brainstorming skill now offers an optional browser-based visual companion
for questions involving visual decisions (mockups, layouts, diagrams).
The companion is a tool, not a mode — each question is evaluated for
whether browser or terminal is more appropriate.
Includes visual-companion.md progressive disclosure guide with server
workflow, screen authoring patterns, and feedback collection.
Co-Authored-By: Drew Ritter <drew@ritter.dev>
WebSocket server for real-time browser communication during brainstorming
sessions. Includes browser helper library for event capture, shell scripts
for server lifecycle management with session isolation and persistent
mockup storage, and integration tests.
Co-Authored-By: Drew Ritter <drew@ritter.dev>
Clarifies that user instructions (CLAUDE.md, direct requests) always
take precedence over Superpowers skills, which in turn override
default system prompt behavior. Ensures users remain in control.
Also updates RELEASE-NOTES.md with unreleased changes including
the visual companion feature.
- Quote ${CLAUDE_PLUGIN_ROOT} in hooks.json to handle paths with spaces
(e.g. "C:\Users\Robert Zimmermann\...")
- Replace bash-only ${BASH_SOURCE[0]:-$0} with POSIX-safe $0 in
run-hook.cmd so the Unix path doesn't break on dash (/bin/sh)
Addresses: #518 (spaces in path), Ubuntu/Debian compatibility
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code spawns hook commands with shell:true + windowsHide:true,
but on Windows the execution chain cmd.exe -> bash.exe causes Git
Bash (MSYS2) to allocate its own console window, bypassing the hide
flag. This creates visible terminal windows that steal focus on every
SessionStart event (startup, resume, clear, compact).
The fix:
- Rename session-start.sh to session-start (no extension) so Claude
Code's .sh auto-detection regex doesn't fire and prepend "bash"
- Restore run-hook.cmd polyglot wrapper to control bash invocation
on Windows (tries known Git Bash paths, then PATH, then exits
silently if no bash found)
- On Unix, the polyglot's shell portion runs the script directly
This avoids Claude Code's broken .sh auto-prepend, gives us control
over how bash is invoked on Windows, and gracefully handles missing
bash instead of erroring.
Addresses: #440, #414, #354, #417, #293
Upstream: anthropics/claude-code#14828
When async is true, the hook may not complete before the model starts
responding, meaning the using-superpowers skill instructions aren't
in context for the first message.
The brainstorming skill described a process but didn't enforce it. Models
would skip the design phase and jump straight to implementation skills
like frontend-design, or collapse the entire brainstorming process into
a single text block.
Changes to brainstorming skill:
- Add HARD-GATE: no implementation until design is approved
- Add explicit checklist that maps to task items
- Add graphviz process flow with writing-plans as terminal state
- Add anti-pattern callout for "too simple to need a design"
- Scale design sections by section complexity, not project complexity
- Make writing-plans the only valid next skill after brainstorming
Changes to using-superpowers skill:
- Add EnterPlanMode intercept to workflow graph
- Route plan mode attempts through brainstorming skill instead
Tested with claude -p --plugin-dir across three variants (no skill,
original skill, updated skill) to verify behavioral compliance.
The character-by-character loop using ${input:$i:1} was O(n^2) in
bash due to substring copy overhead. On Windows Git Bash this took
60+ seconds, freezing terminal input even with async hooks.
Replaced with bash parameter substitution (${s//old/new}) which runs
each pattern as a single C-level pass. 7x faster on macOS, expected
to be dramatically faster on Windows Git Bash where the original
caused the worst hangs.
Relates to #404, #413
The synchronous SessionStart hook blocked the TUI from entering raw
mode on Windows, freezing all keyboard input. The pure-bash
escape_for_json function is O(n^2) on Git Bash, taking 60+ seconds.
Running the hook async prevents the freeze while still injecting
superpowers context. Multiple users confirmed this workaround.
Fixes#404, #413, #414, #419
* 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>
Remove /help command check and specific slash command list. Skills are
primarily invoked by describing what you want to do, not by running
specific commands.
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
Jesse Vincent