Four templates: bug report (with environment table and platform-vs-plugin
gate), feature request (with problem statement and core-appropriateness
question), IDE/platform support request, and a config that disables
blank issues and redirects questions to Discord.
Requires contributors to articulate the problem they're solving,
confirm human review, document eval methodology, and check for
duplicate PRs. Informed by patterns in ~90 closed-without-merge PRs.
- Remove chunk-based plan review in favor of single whole-plan review
- Add Calibration sections to both reviewer prompts so only serious
issues block approval
- Reduce max review iterations from 5 to 3
- Streamline reviewer checklists (spec: 7→5, plan: 7→4 categories)
Subagent Context Isolation:
All delegation skills (brainstorming, parallel agents, code review,
subagent-driven development, writing plans) now explicitly instruct the
dispatching agent to construct review context from scratch — never
forward session history to subagents.
This fixes a problem observed with Codex, where subagents inherited the
full parent session context including the dispatcher's internal
reasoning, prior conversation, and user-facing tone. Reviewers that
inherited this context behaved as if they were the lead developer rather
than a reviewer — they'd reject reasonable code for not matching
unstated preferences, demand rewrites beyond scope, and treat advisory
feedback as blocking. The fix is simple: the dispatcher crafts precisely
what each subagent needs (the spec, the code, the review criteria) and
nothing else. This keeps reviewers focused on the work product, not the
thought process that produced it, and also preserves the dispatcher's
own context window for coordination.
Zero-Dependency Brainstorm Server:
The brainstorm visual companion server has been rewritten from scratch
as a single zero-dependency Node.js file. The previous implementation
vendored Express, ws, chokidar, and 714 npm packages (84,000+ lines of
third-party code) — a supply chain surface area that was
disproportionate to what the server actually does.
The new server.js (~340 lines) implements everything with Node built-ins
only: RFC 6455 WebSocket protocol, HTTP server with template wrapping,
fs.watch with debounce, and lifecycle management.
731 files changed, 1,700 insertions, 85,000 deletions. The entire
vendored node_modules/ directory is gone.
Server Lifecycle Management:
The brainstorm server now automatically shuts down when no longer
needed, preventing orphaned processes. Owner process tracking captures
the harness PID at startup and checks every 60 seconds. 30-minute idle
timeout as fallback. The visual companion guide now instructs agents to
check .server-info before each write and restart if .server-stopped
exists.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Subagents should never inherit the parent session's context or history.
The dispatcher constructs exactly what each subagent needs, keeping
both sides focused: the subagent on its task, the controller on
coordination.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
$PPID inside start-server.sh is the ephemeral shell the harness spawns
to run the script — it dies immediately when the script exits, causing
the server to shut down after ~60s. Now resolves grandparent PID via
`ps -o ppid= -p $PPID` to get the actual harness process (e.g. claude).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
start-server.sh passes $PPID as BRAINSTORM_OWNER_PID to the server.
The server checks every 60s if the owner process is still alive
(kill -0). If it's gone, the server shuts down immediately —
deletes .server-info, writes .server-stopped, exits cleanly.
Works across all harnesses (CC, Codex, Gemini CLI) since it
tracks the shell process that launched the script, which dies
when the harness dies.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Server tracks activity (HTTP requests, WebSocket messages, file
changes) and exits after 30 minutes of inactivity. On exit, deletes
.server-info and writes .server-stopped with reason. Visual companion
guide now instructs agents to check .server-info before each screen
push and restart if needed. Works on all harnesses, not just CC.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete 717 files: index.js, package.json, package-lock.json, and
the entire node_modules directory (express, ws, chokidar + deps).
Update start-server.sh to use server.js. Remove gitignore exception.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete zero-dep brainstorm server. Uses knownFiles set to
distinguish new screens from updates (macOS fs.watch reports
'rename' for both). All 56 tests pass (31 unit + 25 integration).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implements RFC 6455 handshake, frame encoding/decoding for text
frames. All 31 unit tests pass.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace vendored node_modules (714 files) with a single server.js
using only Node built-ins. Spec covers WebSocket protocol, HTTP
serving, file watching, and static file serving. Tests written
before implementation (TDD).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The spec review loop (dispatch spec-document-reviewer subagent, iterate
until approved) existed in the prose "After the Design" section but was
missing from both the checklist and the process flow diagram. Since agents
follow the diagram and checklist more reliably than prose, the spec review
step was being skipped entirely.
Added step 7 (spec review loop) to the checklist and a corresponding
"Spec review loop" → "Spec review passed?" node pair to the dot graph.
Tested with claude --plugin-dir and claude-session-driver: worker now
correctly dispatches the spec-document-reviewer subagent after writing
the design doc and before presenting to the user for review.
Fixes#677.
Use escaped double quotes instead of single quotes around
${CLAUDE_PLUGIN_ROOT} path in hooks.json.
Single quotes fail on Windows (cmd.exe doesn't recognize them as path
delimiters) and on Linux when the shell doesn't expand the variable.
Verified the fix works across all combinations:
- macOS bash, path without spaces: pass
- macOS bash, path with spaces: pass
- Windows cmd.exe, path without spaces: FAILED with single quotes, PASS with double quotes
- Windows cmd.exe, path with spaces: FAILED with single quotes, PASS with double quotes
- Windows Git Bash: pass (both quote styles work here)
Testing was done on a Windows 11 (NT 10.0.26200.0) dev box with
Claude Code 2.1.72 and Git for Windows. The single-quote bug only
manifests when cmd.exe is the executing shell (no Git Bash fallback),
which explains why some users hit it and others don't.
Closes#577, closes#644.
start-server.sh now runs npm install if node_modules is missing.
Fixes broken server when superpowers is installed as a plugin (node_modules
are in .gitignore and not included in the clone).
The server now writes its startup JSON to $SCREEN_DIR/.server-info.
Agents that launch the server via background execution (where stdout is
hidden) can read this file to get the URL, port, and screen_dir.
The visual companion docs now give concrete launch commands per platform:
Claude Code (default mode), Codex (auto-foreground via CODEX_CI), Gemini CLI
(--foreground with is_background), and a fallback for other environments.
Moves lib/brainstorm-server/ → skills/brainstorming/scripts/ so the
brainstorming skill uses relative paths (scripts/start-server.sh) instead
of ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/. This follows the
agentskills.io specification for portable, cross-platform skills.
Updates visual-companion.md references and test paths. All tests pass.
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>
Jesse Vincent