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
Testing showed the model skipped scope assessment when it was a
separate step after "Understanding the idea." Inlining it as the
first thing in understanding ensures it fires before detailed questions.
Brainstorming now assesses whether a project is too large for a single
spec and helps decompose into sub-projects. Spec reviewer checks scope.
Writing-plans has a backstop if brainstorming missed it.
Spec reviewer now checks for unit decomposition with clear boundaries.
Plan reviewer now checks file structure and whether files will grow
too large to reason about.
SKILL.md is now minimal: process, principles, and a prompt that notes
the visual companion is new/token-intensive/slow. All visual companion
details move to visual-companion.md as a progressive disclosure document
read only when the user opts in.
Delete CLAUDE-INSTRUCTIONS.md (content folded into visual-companion.md).
Document fragment vs full-document behavior and --project-dir persistence.
start-server.sh now accepts --project-dir to store session files under
.superpowers/brainstorm/ instead of /tmp. stop-server.sh only deletes
ephemeral /tmp sessions, keeping persistent ones for later review.
Fix test race condition with polling-based server startup wait.
Move toggleSelect/send/selectedChoice from frame-template.html inline
script to helper.js so they're auto-injected. Server now detects bare
HTML fragments (no DOCTYPE/html tag) and wraps them in the frame
template automatically. Full documents pass through as before.
Fix dark mode in sendToClaude confirmation (was using hardcoded colors).
Fix test env var bug (BRAINSTORM_SCREEN -> BRAINSTORM_DIR).
Add tests for fragment wrapping, full doc passthrough, and helper.js.
- Creates test project with spec containing intentional errors
- Runs Claude to actually review using spec-document-reviewer template
- Verifies reviewer catches TODO and "specified later" deferrals
- Checks review format and verdict
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The `- [ ] ### Task N:` syntax was unusual and might not render
correctly in all markdown parsers. Now only steps have checkboxes.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- 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>
- Make writing-plans REQUIRED after design approval
- Explicitly forbid platform planning features (EnterPlanMode, etc.)
- Forbid direct implementation without writing-plans skill
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>
* 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>
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.
Server now watches directory for new .html files instead of a single
screen file. Claude writes to semantically named files like
platform.html, style.html, layout.html - each screen is a new file.
Benefits:
- No need to read before write (files are always new)
- Semantic filenames describe what's on screen
- History preserved in directory for debugging
- Server serves newest file by mtime automatically
Updated: index.js, start-server.sh, and all documentation.
- Never use cat/heredoc for HTML (dumps noise into terminal)
- Read screen_file first before Write tool to avoid errors
- Remind user of URL on every step, not just first
- Give text summary of what's on screen before they look
Scripts:
- Rename show-and-wait.sh -> wait-for-feedback.sh (just waits, no HTML piping)
- Remove wait-for-event.sh (used hanging tail -f)
- Workflow now: Write tool for HTML, wait-for-feedback.sh to block
Documentation rewrite:
- Broader "when to use" (UI, architecture, complex choices, spatial)
- Always ask user first before starting
- Scale fidelity to the question being asked
- Explain the question on each page
- Iterate before moving on - validate changes address feedback
- Use real content (Unsplash images) when it matters
- New show-and-wait.sh combines write + wait into one command
- Uses polling instead of tail -f (which hangs on macOS)
- Docs updated: start watcher BEFORE writing screen to avoid race
- Reduces terminal noise by consolidating operations
- Each session gets unique temp directory (/tmp/brainstorm-{pid}-{timestamp})
- Server outputs screen_dir and screen_file in startup JSON
- stop-server.sh takes screen_dir arg and cleans up session directory
- Document blocking TaskOutput pattern: 10-min timeouts, retry up to 3x,
then prompt user "let me know when you want to continue"
Adds browser-based mockup display to replace ASCII art during
brainstorming sessions. Key components:
- Frame template with OS-aware light/dark theming
- CSS helpers for options, cards, mockups, split views
- Server lifecycle scripts (start/stop with random high port)
- Event watcher using tail+grep for feedback loop
- Claude instructions for using the visual companion
The skill now asks users if they want browser mockups and only
runs in Claude Code environments.
Create the initial server for the visual brainstorming companion:
- Express server with WebSocket support for browser communication
- File watcher (chokidar) to detect screen.html changes
- Auto-injects helper.js into served HTML for event capture
- Binds to localhost only (127.0.0.1) for security
- Outputs JSON events to stdout for Claude consumption
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.
Jesse Vincent