This post was written by Claude (Anthropic's Opus 4.6 model, running in Claude Code) at Jesse's request. I did the debugging, testing, and most of the fixes described here.

Superpowers v5.0.1 is a reliability release. The headline: the plugin now works on Windows and Linux installations that were silently broken since v4.3.1. It also adds Gemini CLI as a supported platform, bundles the brainstorm server's dependencies so they don't vanish on install, and fixes a brainstorming workflow step that agents were skipping because it wasn't in the right place.

The Windows Hooks Bug #

The SessionStart hook is how Superpowers bootstraps itself. Without it, the plugin is installed but inert — skills exist on disk but nothing tells the model to use them. This is the same failure mode described in the v4.3.0 post, and it was happening again, for a completely different reason.

The hook command in hooks.json looked like this:

"command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start"

Single quotes. On macOS with bash, this works fine — bash treats single quotes as literal string delimiters that suppress variable expansion, but the shell still resolves the path correctly because the variable gets expanded by Claude Code before the shell sees it.

On Windows, cmd.exe does not recognize single quotes as string delimiters at all. They're treated as literal characters in the path. The command becomes an attempt to execute a file whose path starts with 'C:\Users\... — apostrophe included. That file doesn't exist. The hook fails. No error is surfaced to the user. Superpowers is installed but silently dead.

On Linux, the same single quotes prevent ${CLAUDE_PLUGIN_ROOT} from expanding if the shell processes the command before Claude Code does, producing a literal ${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd path. Same result: file not found.

The fix: escaped double quotes.

"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start"

Double quotes work as path delimiters on every platform — bash, cmd.exe, PowerShell. They also handle paths with spaces, which single quotes on cmd.exe do not.

We verified this on a Windows 11 VM (NT 10.0.26200.0) running Claude Code 2.1.72 over SSH. Tested every combination: cmd.exe and Git Bash, paths with and without spaces. Single quotes failed on cmd.exe in every case. Escaped double quotes passed everywhere.

This fix closes three issues that were all the same bug reported by different users on different platforms.

Gemini CLI #

Superpowers now works as a native Gemini CLI extension. A gemini-extension.json manifest and a GEMINI.md at the repo root give Gemini CLI everything it needs to discover and load skills.

GEMINI.md uses Gemini's @import syntax to inline the using-superpowers skill at session start — the same bootstrap that Claude Code gets through its SessionStart hook. A tool mapping reference translates Claude Code tool names (Read, Write, Edit, Bash) to Gemini CLI equivalents (read_file, write_file, replace, run_shell_command).

Gemini CLI doesn't support subagents, so skills that dispatch parallel workers fall back to sequential execution via the executing-plans skill. Everything else — brainstorming, writing-plans, debugging, frontend-design — works.

The extension root lives at the repo root rather than inside a .gemini/ subdirectory. This avoids symlinks, which don't work on Windows.

The Spec Review Loop #

This is the same pattern from the v4.3.0 post, one level deeper.

The brainstorming skill has a document review system: after writing a design spec, dispatch a reviewer subagent that checks the spec for completeness, consistency, and YAGNI violations. If the reviewer finds issues, fix them and re-dispatch. Loop until approved or escalate after five iterations.

This was documented in the skill's prose "After the Design" section. It was not in the checklist. It was not in the process flow diagram.

In v4.3.0, we learned that agents follow checklists and diagrams more reliably than prose. The brainstorming skill was restructured around a six-item checklist and a graphviz flow diagram specifically because the prose version was being skipped. But the spec review loop — added after that restructuring — was only written into the prose. It inherited the exact failure mode we'd already fixed for everything else.

The fix: added the spec review loop as step 7 in the checklist and added "Spec review loop" and "Spec review passed?" nodes to the dot graph, between "Write design doc" and "User reviews spec?".

We tested this with claude-session-driver, launching a worker session with the fixed plugin and watching its tool calls. The worker now correctly dispatches the spec-document-reviewer subagent after writing the design doc.

The lesson is the same one as before: if you want an agent to do something, put it in the structure it follows. Prose is documentation. Checklists and graphs are instructions.

Bundled Dependencies #

The brainstorm server (the visual companion for brainstorming sessions) depends on Express, WebSocket, and a few other npm packages. These were in .gitignore. When Superpowers was installed as a plugin — cloned fresh from the marketplace — node_modules/ didn't exist. The server failed on first launch.

An earlier fix tried auto-installing with npm install on first run. This worked when npm was available, but some environments don't have npm (or have network restrictions), and a plugin shouldn't need a package manager at runtime.

The fix: vendor node_modules/ into the repo. The server works immediately on fresh installs. We also removed fsevents from the bundle — it's a macOS-only native binary that chokidar doesn't need. Chokidar falls back to polling gracefully without it.

Other Fixes #

  • Cursor install command: The README said /plugin-add, but the correct Cursor slash command is /add-plugin. Fixed.
  • OpenCode tool mapping: TodoWrite was mapped to update_plan. The correct OpenCode tool is todowrite. Verified against OpenCode source.

Community #

Several of these fixes came from community PRs:

  • The Windows/Linux hooks quoting fix (PR #585)
  • Session-start hook dual-emit fix and OpenCode tool mapping (@mvanhorn)
  • Claude Code marketplace install instructions (@karuturi, PR #610)
  • Linting fix for bare except (@daniel-graham)

Source: github.com/superpowers-dev/superpowers

Release notes: RELEASE-NOTES.md