v5.1.0

Removals

• Legacy slash commands removed — /brainstorm, /execute-plan, and /write-plan are gone. They were deprecated stubs that did nothing but tell the user to invoke the corresponding skill. Invoke superpowers:brainstorming, superpowers:executing-plans, and superpowers:writing-plans directly instead. (#1188)
• superpowers:code-reviewer named agent removed — the agent was the plugin's only named agent and was used by exactly two skills, while every other reviewer/implementer subagent in the repo dispatches general-purpose with a prompt template alongside its skill. The agent's persona and checklist have been merged into skills/requesting-code-review/code-reviewer.md as a self-contained Task-dispatch template. Anyone dispatching Task (superpowers:code-reviewer) should switch to Task (general-purpose) with the prompt template instead. (PR #1299)
• Integration sections removed from skills — these were a legacy of the time before agents had native skills systems and didn't help with steering.

Worktree Skills Rewrite

using-git-worktrees and finishing-a-development-branch now detect when the agent is already running inside an isolated worktree and prefer the harness's native worktree controls before falling back to git worktree. Behavior was TDD-validated and cross-platform-checked across five harnesses. (PRI-974, PR #1121)

• Environment detection — both skills check GIT_DIR != GIT_COMMON before doing anything; if already in a linked worktree, creation is skipped entirely. A submodule guard prevents false detection.
• Consent before creating worktrees — using-git-worktrees no longer creates worktrees implicitly; the skill asks the user first. Fixes #991 (subagent-driven-development was auto-creating worktrees without consent).
• Native tool preference (Step 1a) — when the harness exposes its own worktree tool (e.g. Codex), the skill defers to it. The user's stated preference is respected when expressed.
• Provenance-based cleanup — finishing-a-development-branch only cleans up worktrees inside .worktrees/ (created by superpowers); anything outside is left alone. Fixes #940 (Option 2 was incorrectly cleaning up worktrees), #999 (merge-then-remove ordering), and #238 (cd to repo root before git worktree remove).
• Detached HEAD handling — the finishing menu collapses to two options when there is no branch to merge from.
• Hardcoded /Users/jesse paths in skill examples replaced with generic placeholders. (#858, PR #1122)

Contributor Guidelines for AI Agents

Two new sections at the top of CLAUDE.md (symlinked to AGENTS.md) speak directly to AI agents. An audit of the last 100 closed PRs against this repo showed a 94% rejection rate driven by AI-generated slop: agents that didn't read the PR template, opened duplicates, fabricated problem descriptions, or pushed fork- or domain-specific changes upstream.

• Pre-submission checklist — read the PR template, search for existing PRs, verify a real problem exists, confirm the change belongs in core, and show the human partner the complete diff before submitting.
• What we will not accept — third-party dependencies, "compliance" rewrites of skill content, project-specific configuration, bulk PRs, speculative fixes, domain-specific skills, fork-specific changes, fabricated content, and bundled unrelated changes.
• New harness PRs require a session transcript — most past new-harness integrations copied skill files or wrapped with npx skills instead of loading the using-superpowers bootstrap at session start. The acceptance test ("Let's make a react todo list" must auto-trigger brainstorming in a clean session) and a complete transcript are now required.

Codex Plugin Mirror Tooling

New sync-to-codex-plugin script mirrors superpowers into the OpenAI Codex plugin marketplace as prime-radiant-inc/openai-codex-plugins. Path/user-agnostic so any team member can run it. (PR #1165)

• Clones the fork fresh into a temp directory per run, regenerates overlays inline, and opens a PR; auto-detects upstream from the script's own location and preflights rsync/git/gh auth/python3.
• --bootstrap flag for first-time setup; EXCLUDES patterns anchored to source root; assets/ excluded.
• Mirrors CODE_OF_CONDUCT.md; drops the agents/openai.yaml overlay.
• Seeds interface.defaultPrompt in the mirrored plugin.json. (PR #1180 by @arittr)
• Codex plugin files are committed to the source repo so the sync script uses canonical versions; Codex marketplace metadata is preserved.

OpenCode

• Bootstrap content cached at module level — getBootstrapContent() was calling fs.existsSync + fs.readFileSync + frontmatter regex on every agent step (the experimental.chat.messages.transform hook fires on every step in OpenCode's agent loop). Now read once, cached for the session lifetime, with a null sentinel for the missing-file case. 15 regression tests cover cache behavior, fs call counts, the injection guard, the missing-file sentinel, and cache reset. (Fixes #1202)
• Integration tests modernized.
• Install caveats clarified in the README.

Code Review Consolidation

requesting-code-review is now self-contained: the persona, checklist, and dispatch template live in skills/requesting-code-review/code-reviewer.md and the skill dispatches Task (general-purpose) directly. (PR #1299)

• Single source of truth — the persona/checklist that previously lived in both agents/code-reviewer.md and the skill's placeholder template (and drifted independently) is now one file.
• subagent-driven-development follows suit — its code-quality-reviewer-prompt.md now dispatches Task (general-purpose) instead of the named agent.
• Behavioral test added — tests/claude-code/test-requesting-code-review.sh plants real bugs (SQL injection, plaintext password handling, credential logging) into a tiny project and asserts the dispatched reviewer flags every planted issue at Critical/Important severity and refuses to approve the diff.
• Codex and Copilot workaround docs trimmed — the "Named agent dispatch" sections in references/codex-tools.md and references/copilot-tools.md documented how to flatten a named agent into a generic dispatch. With no named agents shipping, the workaround is unnecessary; both sections were dropped.

Subagent-Driven Development

• No more pause every 3 tasks — the "review after each batch (3 tasks)" cadence in requesting-code-review (originally for executing-plans) was leaking into subagent-driven-development. Replaced with "each task or at natural checkpoints" plus an explicit continuous-execution directive.
• SDD integration test now runs its assertions — three independent bugs caused the test to silently bail before printing any verification results: an unresolved .. segment in the working-dir path, a set -euo pipefail interaction with find | sort | head -1 (SIGPIPE on the producer killed the script), and a missing --plugin-dir on the claude -p invocation that caused the test to load the installed plugin instead of the working tree. All three fixed; six verification tests now actually run against a real end-to-end SDD run.

Cursor

• Windows SessionStart hook routed through run-hook.cmd instead of invoking the extensionless session-start script directly. Fixes Windows opening the file in an editor instead of running it. Also removed an accidental UTF-8 BOM from hooks-cursor.json.

Gemini CLI

• Subagent dispatch mapping — Gemini's Task dispatch now maps to @agent-name / @generalist, with parallel subagent dispatch documented for independent tasks.

Skills

• Terminology cleanups across skill content.

Documentation & Install

• Factory Droid installation instructions added to README.
• Quickstart install links in README. (PR #1293 by @arittr)
• Codex plugin install guidance updated. (PR #1288 by @arittr)
• Codex wait mapping corrected to wait_agent in the tools reference.
• Install order reorganized; Codex install instructions cleaned up.
• Removed vestigial CHANGELOG.md in favor of RELEASE-NOTES.md as the single source. (PR #1163 by @shaanmajid)
• Discord invite link fixed; release announcements link and a detailed Discord description added to the Community section.

Community

• @shaanmajid — vestigial CHANGELOG.md removal (PR #1163)
• @arittr — README quickstart install links (#1293), Codex plugin install guidance (#1288), sync-to-codex-plugin interface.defaultPrompt seed (#1180)

v5.0.7

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.
• 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

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

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

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".