Superpowers Release Notes

v5.0.7 (2026-03-31)

GitHub Copilot CLI Support

• SessionStart context injection — Copilot CLI v1.0.11 added support for additionalContext in sessionStart hook output. The session-start hook now detects the COPILOT_CLI environment variable and emits the SDK-standard { "additionalContext": "..." } format, giving Copilot CLI users the full superpowers bootstrap at session start. (Original fix by @culinablaz in PR #910)
• Tool mapping — added references/copilot-tools.md with the full Claude Code to Copilot CLI tool equivalence table
• Skill and README updates — added Copilot CLI to the using-superpowers skill's platform instructions and README installation section

OpenCode Fixes

• Skills path consistency — the bootstrap text no longer advertises a misleading configDir/skills/superpowers/ path that didn't match the runtime path. The agent should use the native skill tool, not navigate to files by path. Tests now use consistent paths derived from a single source of truth. (#847, #916)
• Bootstrap as user message — moved bootstrap injection from experimental.chat.system.transform to experimental.chat.messages.transform, prepending to the first user message instead of adding a system message. Avoids token bloat from system messages repeated every turn (#750) and fixes compatibility with Qwen and other models that break on multiple system messages (#894).

v5.0.6 (2026-03-24)

Inline Self-Review Replaces Subagent Review Loops

The subagent review loop (dispatching a fresh agent to review plans/specs) doubled execution time (~25 min overhead) without measurably improving plan quality. Regression testing across 5 versions with 5 trials each showed identical quality scores regardless of whether the review loop ran.

• brainstorming — replaced Spec Review Loop (subagent dispatch + 3-iteration cap) with inline Spec Self-Review checklist: placeholder scan, internal consistency, scope check, ambiguity check
• writing-plans — replaced Plan Review Loop (subagent dispatch + 3-iteration cap) with inline Self-Review checklist: spec coverage, placeholder scan, type consistency
• writing-plans — added explicit "No Placeholders" section defining plan failures (TBD, vague descriptions, undefined references, "similar to Task N")
• Self-review catches 3-5 real bugs per run in ~30s instead of ~25 min, with comparable defect rates to the subagent approach

Brainstorm Server

• Session directory restructured — the brainstorm server session directory now contains two peer subdirectories: content/ (HTML files served to the browser) and state/ (events, server-info, pid, log). Previously, server state and user interaction data were stored alongside served content, making them accessible over HTTP. The screen_dir and state_dir paths are both included in the server-started JSON. (Reported by 吉田仁)

Bug Fixes

• Owner-PID lifecycle fixes — the brainstorm server's owner-PID monitoring had two bugs causing false shutdowns within 60 seconds: (1) EPERM from cross-user PIDs (Tailscale SSH, etc.) was treated as "process dead", and (2) on WSL the grandparent PID resolves to a short-lived subprocess that exits before the first lifecycle check. Fixed by treating EPERM as "alive" and validating the owner PID at startup — if it's already dead, monitoring is disabled and the server relies on the 30-minute idle timeout. This also removes the Windows/MSYS2-specific carve-out from start-server.sh since the server now handles it generically. (#879)
• writing-skills — corrected false claim that SKILL.md frontmatter supports "only two fields"; now says "two required fields" and links to the agentskills.io specification for all supported fields (PR #882 by @arittr)

Codex App Compatibility

• codex-tools — added named agent dispatch mapping documenting how to translate Claude Code's named agent types to Codex's spawn_agent with worker roles (PR #647 by @arittr)
• codex-tools — added environment detection and Codex App finishing sections for worktree-aware skills (by @arittr)
• Design spec — added Codex App compatibility design spec (PRI-823) covering read-only environment detection, worktree-safe skill behavior, and sandbox fallback patterns (by @arittr)

v5.0.5 (2026-03-17)

Bug Fixes

• Brainstorm server ESM fix — renamed server.js → server.cjs so the brainstorming server starts correctly on Node.js 22+ where the root package.json "type": "module" caused require() to fail. (PR #784 by @sarbojitrana, fixes #774, #780, #783)
• Brainstorm owner-PID on Windows — skip PID lifecycle monitoring on Windows/MSYS2 where the PID namespace is invisible to Node.js, preventing the server from self-terminating after 60 seconds. (#770, docs from PR #768 by @lucasyhzlu-debug)
• stop-server.sh reliability — verify the server process actually died before reporting success. SIGTERM + 2s wait + SIGKILL fallback. (#723)

Changed

• Execution handoff — restore user choice between subagent-driven and inline execution after plan writing. Subagent-driven is recommended but no longer mandatory.

v5.0.4 (2026-03-16)

Review Loop Refinements

Dramatically reduces token usage and speeds up spec and plan reviews by eliminating unnecessary review passes and tightening reviewer focus.

• Single whole-plan review — plan reviewer now reviews the complete plan in one pass instead of chunk-by-chunk. Removed all chunk-related concepts (## Chunk N: headings, 1000-line chunk limits, per-chunk dispatch).
• Raised the bar for blocking issues — both spec and plan reviewer prompts now include a "Calibration" section: only flag issues that would cause real problems during implementation. Minor wording, stylistic preferences, and formatting quibbles should not block approval.
• Reduced max review iterations — from 5 to 3 for both spec and plan review loops. If the reviewer is calibrated correctly, 3 rounds is plenty.
• Streamlined reviewer checklists — spec reviewer trimmed from 7 categories to 5; plan reviewer from 7 to 4. Removed formatting-focused checks (task syntax, chunk size) in favor of substance (buildability, spec alignment).

OpenCode

• One-line plugin install — OpenCode plugin now auto-registers the skills directory via a config hook. No symlinks or skills.paths config needed. Install is just adding one line to opencode.json. (PR #753)
• Added package.json so OpenCode can install superpowers as an npm package from git.

Bug Fixes

• Verify server actually stopped — stop-server.sh now confirms the process is dead before reporting success. SIGTERM + 2s wait + SIGKILL fallback. Reports failure if the process survives. (PR #751)
• Generic agent language — brainstorm companion waiting page now says "the agent" instead of "Claude".

v5.0.3 (2026-03-15)

Cursor Support

• Cursor hooks — added hooks/hooks-cursor.json with Cursor's camelCase format (sessionStart, version: 1) and updated .cursor-plugin/plugin.json to reference it. Fixed platform detection in session-start to check CURSOR_PLUGIN_ROOT first (Cursor may also set CLAUDE_PLUGIN_ROOT). (Based on PR #709)

Bug Fixes

• Stop firing SessionStart hook on --resume — the startup hook was re-injecting context on resumed sessions, which already have the context in their conversation history. The hook now fires only on startup, clear, and compact.
• Bash 5.3+ hook hang — replaced heredoc (cat <<EOF) with printf in hooks/session-start. Fixes indefinite hang on macOS with Homebrew bash 5.3+ caused by a bash regression with large variable expansion in heredocs. (#572, #571)
• POSIX-safe hook script — replaced ${BASH_SOURCE[0]:-$0} with $0 in hooks/session-start. Fixes "Bad substitution" error on Ubuntu/Debian where /bin/sh is dash. (#553)
• Portable shebangs — replaced #!/bin/bash with #!/usr/bin/env bash in all shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where /bin/bash is outdated or missing. (#700)
• Brainstorm server on Windows — auto-detect Windows/Git Bash (OSTYPE=msys*, MSYSTEM) and switch to foreground mode, fixing silent server failure caused by nohup/disown process reaping. (#737)
• Codex docs fix — replaced deprecated collab flag with multi_agent in Codex documentation. (PR #749)

v5.0.2 (2026-03-11)

Zero-Dependency Brainstorm Server

Removed all vendored node_modules — server.js is now fully self-contained

• Replaced Express/Chokidar/WebSocket dependencies with zero-dependency Node.js server using built-in http, fs, and crypto modules
• Removed ~1,200 lines of vendored node_modules/, package.json, and package-lock.json
• Custom WebSocket protocol implementation (RFC 6455 framing, ping/pong, proper close handshake)
• Native fs.watch() file watching replaces Chokidar
• Full test suite: HTTP serving, WebSocket protocol, file watching, and integration tests

Brainstorm Server Reliability

• Auto-exit after 30 minutes idle — server shuts down when no clients are connected, preventing orphaned processes
• Owner process tracking — server monitors the parent harness PID and exits when the owning session dies
• Liveness check — skill verifies server is responsive before reusing an existing instance
• Encoding fix — proper <meta charset="utf-8"> on served HTML pages

Subagent Context Isolation

• All delegation skills (brainstorming, dispatching-parallel-agents, requesting-code-review, subagent-driven-development, writing-plans) now include context isolation principle
• Subagents receive only the context they need, preventing context window pollution

v5.0.1 (2026-03-10)

Agentskills Compliance

Brainstorm-server moved into skill directory

• Moved lib/brainstorm-server/ → skills/brainstorming/scripts/ per the agentskills.io specification
• All ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/ references replaced with relative scripts/ paths
• Skills are now fully portable across platforms — no platform-specific env vars needed to locate scripts
• lib/ directory removed (was the last remaining content)

New Features

Gemini CLI extension

• Native Gemini CLI extension support via gemini-extension.json and GEMINI.md at repo root
• GEMINI.md @imports using-superpowers skill and tool mapping table at session start
• Gemini CLI tool mapping reference (skills/using-superpowers/references/gemini-tools.md) — translates Claude Code tool names (Read, Write, Edit, Bash, etc.) to Gemini CLI equivalents (read_file, write_file, replace, etc.)
• Documents Gemini CLI limitations: no subagent support, skills fall back to executing-plans
• Extension root at repo root for cross-platform compatibility (avoids Windows symlink issues)
• Install instructions added to README

Improvements

Multi-platform brainstorm server launch

• Per-platform launch instructions in visual-companion.md: Claude Code (default mode), Codex (auto-foreground via CODEX_CI), Gemini CLI (--foreground with is_background), and fallback for other environments
• Server now writes startup JSON to $SCREEN_DIR/.server-info so agents can find the URL and port even when stdout is hidden by background execution

Brainstorm server dependencies bundled

• node_modules vendored into the repo so the brainstorm server works immediately on fresh plugin installs without requiring npm at runtime
• Removed fsevents from bundled deps (macOS-only native binary; chokidar falls back gracefully without it)
• Fallback auto-install via npm install if node_modules is missing

OpenCode tool mapping fix

• TodoWrite → todowrite (was incorrectly mapped to update_plan); verified against OpenCode source

Bug Fixes

Windows/Linux: single quotes break SessionStart hook (#577, #529, #644, PR #585)

• Single quotes around ${CLAUDE_PLUGIN_ROOT} in hooks.json fail on Windows (cmd.exe doesn't recognize single quotes as path delimiters) and on Linux (single quotes prevent variable expansion)
• Fix: replaced single quotes with escaped double quotes — works across macOS bash, Windows cmd.exe, Windows Git Bash, and Linux, with and without spaces in paths
• Verified on Windows 11 (NT 10.0.26200.0) with Claude Code 2.1.72 and Git for Windows

Brainstorming spec review loop skipped (#677)

• The spec review loop (dispatch spec-document-reviewer subagent, iterate until approved) existed in the prose "After the Design" section but was missing from the checklist and 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 corresponding nodes to the dot graph
• Tested with claude --plugin-dir and claude-session-driver: worker now correctly dispatches the reviewer

Cursor install command (PR #676)

• Fixed Cursor install command in README: /plugin-add → /add-plugin (confirmed via Cursor 2.5 release announcement)

User review gate in brainstorming (#565)

• Added explicit user review step between spec completion and writing-plans handoff
• User must approve the spec before implementation planning begins
• Checklist, process flow, and prose updated with the new gate

Session-start hook emits context only once per platform

• Hook now detects whether it's running in Claude Code or another platform
• Emits hookSpecificOutput for Claude Code, additional_context for others — prevents double context injection

Linting fix in token analysis script

• except: → except Exception: in tests/claude-code/analyze-token-usage.py

Maintenance

Removed dead code

• Deleted lib/skills-core.js and its test (tests/opencode/test-skills-core.js) — unused since February 2026
• Removed skills-core existence check from tests/opencode/test-plugin-loading.sh

Community

• @karuturi — Claude Code official marketplace install instructions (PR #610)
• @mvanhorn — session-start hook dual-emit fix, OpenCode tool mapping fix
• @daniel-graham — linting fix for bare except
• PR #585 author — Windows/Linux hooks quoting fix

---

v5.0.0 (2026-03-09)

Breaking Changes

Specs and plans directory restructured

• Specs (brainstorming output) now save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
• Plans (writing-plans output) now save to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
• User preferences for spec/plan locations override these defaults
• All internal skill references, test files, and example paths updated to match
• Migration: move existing files from docs/plans/ to new locations if desired

Subagent-driven development mandatory on capable harnesses

Writing-plans no longer offers a choice between subagent-driven and execut