Jesse Vincent Release Notes

We rebuilt brainstorming from scratch so it does a much better job of what it was always for: helping you work out what you actually want and put it into words before anything gets built. The new skill asks you to describe what you're after and why, plays back what it heard so you can correct it, and keeps asking good questions until the picture is clear. Then it matches the process to the work, from just doing it to writing a full design.

This release also adds a native plugin manifest for the Antigravity Marketplace and fixes Windows hook discovery, Git Bash paths, Hermes skill descriptions, and several smaller bugs.

Brainstorming

Brainstorming draws out what you want before it proposes anything. Its first message offers to skip the questions and asks one open question about a real moment or a concrete picture. It offers a menu only when you're stuck. Along the way, it offers to look at prior art, your project, or the web. As it understands each part, it plays that part back in a few hundred words and marks its guesses as guesses. (#2463)

It sizes the work after it understands what you want, and says so in plain words. It does a quick, clear task right away, agrees a small change with you in chat, and writes a design document for a project. You can override its call, and it steps up a size if the work grows. (#2463)

A builder check replaces the spec-document reviewer. A fresh subagent reads the design as the person who'll build it and lists what they'd still need to ask. Brainstorming answers what it can, makes the minor calls itself and marks them as its own, and brings you the questions that change what gets built, in one round. (#2463)

It finds out which choices about how the thing gets made you want to own. Platform, language, libraries, medium: if you have strong views, it talks them through; if you hand them over, it picks sensible defaults and tells you what it picked. It does this even when you skip the questions. We made this change after a session designed an iOS app, never asked about platform, and built a web app. (#2482, #2483)

It offers the visual companion whenever seeing would help more than reading: screens, layouts, flows, options that look different, diagrams. The offer drops its token-cost warning. (#2463)

The visual companion now shows screens containing $', $&, and similar sequences intact. The server inserted content with String.replace, which treats those sequences as replacement patterns. It now inserts content literally. Thanks @andrew-yian for the report and @luochen211 for the fix. (#2362, #2364)

Antigravity

agy plugin install https://github.com/obra/superpowers now installs Superpowers as a native Antigravity plugin. We added .antigravity-plugin/plugin.json with the Marketplace display name, logo, and suggested prompts. Previously, agy fell back to importing the repo as a Gemini CLI extension, then rejected the copied Claude-format hooks file on every session with invalid hook "hooks": command hook must specify 'command'. The install command stays the same. (#2479)

Superpowers bootstraps on Antigravity through skill discovery. Antigravity has no session-start hook event, but it shows the model each installed skill's description, and using-superpowers' "Use when starting any conversation" prompts the model to load it. We verified this on agy 1.3.1 across 12 runs: "Let's make a react todo list" and "add a settings page" triggered brainstorming before any code, and a failing test triggered systematic-debugging before any edit. We also corrected the README and porting guide, which described a session-start hook and install script that never existed. (#2479)

Hooks

SessionStart now works when the harness launches it with a broken PATH. The hooks no longer look up dirname, cat, or bash on PATH, so a startup PATH that can't resolve them (anthropics/claude-code#43127) no longer drops the bootstrap. Thanks @kannan983 for the report and Ada Sen for the fix. (#2310, #2349)

Windows: run-hook.cmd finds per-user Git for Windows installs and skips WSL launchers. It now checks %LOCALAPPDATA%\Programs\Git, and when it searches PATH, it skips the WSL bash.exe launchers, which fail without a Linux distro. Thanks @jp5247 for the report, and @citizen204 (#1864) and @KaiyiQuan (#2365) for the fixes we combined here. (#1863, #2393)

Windows: run-hook.cmd ignores bash and where in the current directory. Previously, a repository could plant bash.cmd or where.bat and have it run at session start. (#2393)

Windows: run-hook.cmd now passes hook exit codes to the harness. It used to report success even when the hook failed. (#2393)

Subagent-Driven Development

sdd-workspace leaves a repo's own .superpowers/sdd/.gitignore alone. It used to overwrite the file with * on every run, reverting any version a repo committed (for example, to track progress.md ledgers). It now writes the default only when no file exists. Thanks @aruizcu1989 for the fix. (#2161, #2399)

Plan markers stay repo-relative on Windows. On Git Bash, sdd-workspace compared git rev-parse's C:/… root with the plan's /c/… path, so every workspace marker recorded an absolute, machine-specific path. It now resolves the root the same way as the plan path. We found this while landing @t0domanh's Windows test fixes (#2149).

Executing Plans

task-done now records tasks whose test command passes silently. When a passing command printed nothing, task-done exited 1 without writing the ledger line, so a finished task looked unfinished. It now records → (no output). Thanks @KenM-BT for the report and Ada Sen for the fix. (#2385, #2388)

Requesting Code Review

The example's base-SHA command survives skill arguments. Claude Code replaces $1 in a skill body with the second argument word, so invoking the skill with arguments turned awk '{print $1}' into awk '{print }'. The example now uses cut -d' ' -f1, which contains no $. Thanks @errmakov for the report and @klemens-floege for the fix. (#2311, #2361)

Systematic Debugging

The multi-layer diagnostic example no longer prints the secret it checks for. ${IDENTITY:+SET}${IDENTITY:-UNSET} and env | grep IDENTITY both echoed the signing identity's value into logs. The example now reports only whether the variable is set. Thanks @kennyg-g for the report and @m2dumpling for the fix. (#2375, #2380)

Hermes Agent

Hermes' skill list now shows Superpowers skill descriptions. Hermes lists each plugin skill with the description passed to register_skill, which defaults to empty. The plugin passed only a name and path, so every skill appeared blank and the model had nothing to choose from. The plugin now passes each skill's frontmatter description. Thanks @pepijn-blom for the fix. (#2284)

Writing Plans

writing-plans produces leaner plans, faster. Plans now record the decisions an implementer needs (signatures, test assertions, the spec's values) instead of writing out the code. Some frontier models, including Opus 5.5, could get overzealous during plan writing and, with certain prompting, would sometimes try to implement the entire project while designing the plan. The new skill keeps planning focused on the plan. When we reproduced the original report, the scratch builds went away, and plans took a quarter of the time and about a third of the tokens. Thanks to Harper Reed for the report and session bundle. (#2333)

A plan records decisions. It's not a transcript of the code. "What a Step Contains" replaces the "No Placeholders" section. A test step names the test and its assertions. A code step gives the exact signature, the file, and the spec's values, and includes a body only for an algorithm those don't determine. A verification step gives the command and its passing output. A reference to another task goes through that task's Interfaces block. Placeholders are still called out as the opposite failure. (#2333)

Self-review checks proportion. The plan compares its own length to the spec's. A plan several times longer than the spec is a transcript, and when code blocks dominate, bodies get replaced with signatures and test assertions. (#2333)

The plan's reader is described as capable: an engineer who writes idiomatic code once they know the exact interface and test. This replaces "zero context, questionable taste." Steps are now sized as "one action with a checkable result" instead of "2-5 minutes." (#2333)

Every plan written by the new skill executed 9/9 against planted-defect probes on Sonnet 5, the same result as full-code plans. (#2333)

Removed plan-document-reviewer-prompt.md. Nothing referenced it. (#2333)

Documentation

Removed CLAUDE.md. Claude Code now reads AGENTS.md directly, but only when no CLAUDE.md exists, so keeping the one-line pointer would have hidden the real guidelines.

New Skills

v6.4.0 was never shipped. v6.4.1 is the first release with these changes. It holds back the new proving-it-works-with-a-movie skill, which is getting cleanup and robustness work and will return in a later release.

The new diagnosing-superpowers skill figures out what went wrong in a session. executing-plans is rebuilt as Native execution, a cheaper alternative to subagent-driven development. This release also adds support for three new harnesses: OpenCode 2.0, Muse, and Qwen Code.

diagnosing-superpowers

when a session goes wrong (repeated work, an ignored plan, a skill that didn't fire, a surprising bill), ask your agent to "figure out what went wrong with superpowers in this session." It pins down the problem with you, reads the transcripts on disk, and reports what happened with path:line evidence for every finding. On request it builds a scrubbed bundle or drafts a GitHub issue for your approval, with the cited evidence left intact. Works on the current session or a past one. (#2236, #2287)

Executing Plans

Heads up: executing-plans no longer stops every few tasks to check in with you. It runs the whole plan, then gets one review at the end.

Native (inline) execution is now a real mode. executing-plans was a 64-line stub that measured the same as running with no plugin at all. It is rebuilt: the session implements every task itself under the same workspace, ledger, and stopping rules as subagent-driven development, then dispatches one fresh whole-branch review on the most capable model. task-start and task-done helpers keep the ledger and test log honest. It is the cheapest way to run a plan and runs well on a mid-tier session model. (#2318)

The plan handoff offers two approaches, Subagent-driven and Native, says what each costs, and recommends one for this plan with a reason drawn from the plan. If you already chose one, it keeps your choice. (#2258, #2318)

Writing Plans

You review the saved plan before anything runs. Approving an idea or a scope no longer counts as approving a plan you haven't seen. (#2258)

Plans carry a Review Focus section: up to five inputs or failure modes the spec implies but no task's tests exercise, each pinned by a test in the task that owns the code. In evals, every implementer shipped the same crash on an input the spec implied but never named; this section exists to catch that. (#2319)

Brainstorming

Brainstorming finds out why you want the thing before proposing features, reflects your intent back for correction, and ties your approval to the actual design and planning stages. The motivating session took "that scope is ok" as permission to scaffold. (#2258)

Code Review

Reviewers judge behavior the spec doesn't mention by what a reasonable user would expect, so a crash on an unnamed input no longer slides through as Minor. A "Declined to judge" list shows what the reviewer skipped, and the session running the plan decides each one. (#2319)

The multi-commit BASE_SHA alternative is now git merge-base origin/main HEAD. A bare origin/main showed main's newer files as phantom deletions once main moved past the branch point. (#2133, #2118)

Test-Driven Development

The project's suite defines green, not just your test file. When a task named one test file, sessions ran only that file in 11 of 12 probe runs, so a broken test next door went unseen. The skill now says to run the project's test command and report every failure by name, including ones you didn't cause. (#2110)

Subagent-Driven Development

Plans with the same basename no longer share a workspace. docs/alpha/plan.md and docs/beta/plan.md resolved to one directory and task-brief silently overwrote the other plan's brief. Each workspace now records its owning plan; a collision gets its own directory. Existing workspaces are adopted in place. (#2138, #2045)

review-package rejects empty or non-descendant BASE..HEAD ranges (exit 3), so an implementer that committed to the wrong branch can't produce a "clean" review of nothing. (#2136, #2050)

On Claude Code, the controller can run one layer down, as a nested subagent on a mid-tier model. It measured about half the cost and wall clock. It's opt-in: ask for it, or tell your agent your session model is too expensive to spend on coordination. (#2320)

New Harness Support

OpenCode 2.0.4+ is supported alongside V1. Skills register through V2's native API, and the bootstrap survives continuation, restart, forks, and compaction. Delegated child sessions no longer receive the controller's bootstrap. (#2106, #2306)

Muse: native plugin manifest and SessionStart hook. muse plugins install ./ then muse plugins approve superpowers. (#2317)

Qwen Code added to the install docs: qwen extensions install obra/superpowers. (#2132)

Fixes

Skills work when a packager strips executable bits. The Codex marketplace and MiniMax Code's repackage both shipped our scripts non-executable, so every documented command failed with Permission denied. Skill prose now invokes bundled scripts through their interpreter (bash scripts/foo.sh, node render-graphs.js), and the SDD helpers call each other the same way. (#2301, #2134, #2040)

The platform-support issue template applies a label that exists (new-harness). (#2250)

Documentation

docs/testing.md describes the Quorum eval lab, replacing stale Drill references and commands. (#2135)

README: a "When Something Goes Wrong" section pointing at diagnosing-superpowers.

AGENTS.md is now the canonical contributor guidelines. CLAUDE.md is a one-line reference to it. AGENTS.md used to be a symlink to CLAUDE.md, which Muse's installer rejects. (#2317)

Adopted the Prime Radiant Community Code of Conduct. (#2122)

Harness Support

Devin CLI: devin plugins install obra/superpowers now works, and skills auto-trigger at session start. (#1995)

Hermes Agent: install from a git clone; skills register with Hermes' native loader and the bootstrap loads on the first turn. (#1922, #2025)

Grok Build CLI added to the install docs. (#1919)

Brainstorming

Ceremony now scales to the task. Requests are classified as spike, bounded, or architectural; small tasks skip the two-document ritual. Every path still stops for your approval before implementation. (#2063)

Subagent-Driven Development

Controllers no longer stall on plan conflicts. Non-catastrophic conflicts and ambiguities get a recorded ruling and work continues; only destructive or irreversible actions still stop for a human. One donated session had sat blocked for almost nine hours on a question the controller could have decided. (#2077)

The pre-dispatch conflict scan records its checks in the ledger instead of just asserting the plan is clean. (#2080)

Small same-shape tasks batch into one dispatch, cutting subagent cost sharply on micro-task plans; batch reviews verify every file in the brief made it into the diff. (#2078)

Implementers and reviewers may not spawn their own subagents, which was producing duplicate reviews. (#2059)

Plans carry a Spec: pointer and SDD reads the spec at setup, so plan conflicts get resolved against the design instead of guessed at. (#2086)

Reviewers re-read evidence they find illegible instead of re-running the test suite (#2089), and circuit-breaker rulings now show up in the Finish report.

Codex

Subagent waits are event-driven instead of poll-heavy, spawns pin model and reasoning effort explicitly, and the multi-agent reference is corrected against Codex source. (#2060, #2061, #2062)

Finishing a Development Branch

Worktree removal no longer destroys untracked files. When git worktree remove refuses because the tree holds uncommitted work, the skill stops, names the files, and asks — instead of reaching for --force. (#2016, #1223, #2024)

Fixes

render-graphs.js in writing-skills works on Windows.

Corrected Copilot CLI backgrounding guidance for Windows. (#1929, #2006)

bump-version.sh covers the Hermes manifest.

Documentation

README: added a table of contents and reorganized Getting Started.

v6.2.0 (2026-07-23)

Subagent-Driven Development

Two structural changes to how SDD tracks progress and closes out review findings, both developed against live eval campaigns.

The workspace is now plan-scoped. .superpowers/sdd/ had no plan identity and no end-of-life: a follow-up plan in the same working tree could read the previous plan's ledger as its own progress (observed in the wild, with multiple contamination rounds and ad-hoc workarounds). sdd-workspace now requires the plan file and resolves a per-plan directory, .superpowers/sdd/<plan-basename>/; task-brief and review-package write into their plan's directory (review-package gains the plan file as its first argument); the ledger names its plan on its first line; and the workspace is deleted once the final review is clean — git history is the durable record. Baseline evals showed controllers already refused foreign ledgers, but at a cost of 6–13 tool calls of cross-plan git forensics per resume; plan-scoping makes the answer structural instead. (25/25 baseline and GREEN eval runs documented in docs/specs/ and docs/plans/.)

The review-fix loop resumes the implementer. The lifecycle restructure gives fix rounds resume-the-implementer semantics instead of fresh dispatches, adds a scoped re-review prompt (re-review-prompt.md) so the re-reviewer checks the fixes rather than re-reading the whole task, and installs a five-round circuit breaker with controller adjudication when it trips. SKILL.md reorganizes by lifecycle, and its Red Flags convert to the house rationalization-table form.

Skills

A branch-wide compression campaign: recap sections, social proof, and benefits-selling prose aimed at a reader who has already invoked the skill are gone, with every load-bearing argument folded into a rationalization-table row or moved to its point of use. Each cut was micro-tested with subagent probes, and the one cut that measurably degraded behavior was reworked rather than shipped.

testing-anti-patterns.md is now writing-good-tests.md. The TDD reference doc is rebuilt as a positive catalog — six rules that lead with the GOOD example — and absorbs a falsifiability discipline: name the production change that would fail the test, derive expectations independently of the code under test, and a closing mutation check. It closes two holes by name: the string-presence trap (grep-style tests on scripts, skills, and prompts counterfeit falsifiability — the observable is behavior, never text) and the change-detector trap (a constant assertion can fail and still protect nothing), each with a hard stop in the gate function. Trivial code and human prose earn no test; the trigger broadens from "adding mocks" to any test writing.

TDD's "Why Order Matters" rebuttals survive as rationalization rows. Deleting the section outright measurably degraded test-first behavior under "just write it, tests after" pressure (control 8/10 → treatment 5/10, corroborated on Claude and Codex), so each prose rebuttal now lives in its Common Rationalizations row — the section is gone but the arguments fire where an agent hits them mid-rationalization.

finishing-a-development-branch no longer offers to discard your work. The completion menu dates from when throwing away branches was routine; "Discard this work" next to "Merge" advertised destroying finished, passing work. Discard survives as an explicit-request-only path with the same typed-confirmation ritual. The same pass made PR creation forge-agnostic (your forge's CLI or the URL printed on push, not a blessed list of tools) and fixed a real bug: the worktree path was recomputed after cleanup had already changed directory, so provenance checks never matched and cleanup silently no-oped.

Recap and persuasion prose removed across the library. brainstorming, systematic-debugging, dispatching-parallel-agents, verification-before-completion, executing-plans, subagent-driven-development, requesting-code-review, receiving-code-review, using-git-worktrees, writing-plans, and writing-skills all drop their Bottom Line / Key Principles / Real-World Impact / Advantages sections; using-git-worktrees and finishing-a-development-branch convert their guard sections to the house Excuse/Reality rationalization table.

Windows

The SessionStart hook now dispatches via Git Bash. The hook's command string starts with a quoted path, which broke both shells Claude Code might hand it to: PowerShell parsed the quoted string as an expression and died with a parser error (#1751), and cmd.exe's quote-stripping rule truncated the command when the profile path contained a metacharacter like ( (#1918) — either way the bootstrap silently never loaded. The hook now declares shell: "bash", which Claude Code ≥ 2.1.81 resolves to Git for Windows directly, and which surfaces an actionable install prompt when Git Bash is missing. Older Claude Code versions ignore the unknown key and behave as before. Verified end-to-end on Linux, Windows 11 with Git Bash under a hostile path, and Windows 11 without Git Bash.

Harness Support

Gemini CLI support is restored. The v6.1.0 removal (on the news that Google had EOLed the Gemini CLI) was premature; the install docs and the gemini-tools.md tool-mapping reference are back while permanent removal gets a proper evaluation. (#1959)

Fixes

find-polluter.sh actually finds test files now. find . emits ./-prefixed paths, so the documented -path "src/**/*.test.ts" pattern matched nothing — and wc -l on empty input then reported "Found 1". Fixed the prefix mismatch (#2008, #2011), plus two follow-ups: a caller-supplied ./-prefixed pattern no longer double-prefixes into a never-matching form, and / is also matched collapsed so tests directly under the base directory (src/top.test.ts vs src//*.test.ts) aren't silently skipped. The script gains a deterministic test suite.

The Codex package script works beyond macOS. Deterministic-metadata tar flags were bsdtar-only spellings, staged file modes depended on two umasks canceling out, and the test's timestamp assertion parsed bsdtar's column layout in a US timezone. GNU tar now gets equivalent flags producing byte-identical headers, modes are pinned canonical, and the test asserts mtime via tarfile.

SDD's skill test no longer flakes. The file's worst case exceeded the runner's per-file ceiling (raised to 900s), and the assert helpers matched free-form model prose case-sensitively; matching is now case-insensitive and assert_order dumps output on failure so the next flake is diagnosable.

Docs and test cleanup after the v6.1.0 reference pruning. Dead links to the deleted claude-code-tools.md/copilot-tools.md are replaced with the current architecture (#1969), a dangling #subagent-support anchor in the Antigravity reference is dropped (#2010), and the Antigravity/Pi mapping tests assert only the surviving harness-specific mappings — scoped to the table so they fail again if it's deleted.

Codex

Codex no longer re-registers the Claude SessionStart hook. v6.1.0 removed the Codex hook config and its manifest hooks pointer, meaning to stop Codex from installing a SessionStart hook — but with no hooks field, Codex fell back to auto-discovering hooks/hooks.json, the Claude Code SessionStart hook that the marketplace ships from the repo root, and re-registered it along with its install-time trust prompt. The Codex manifest now declares an explicit empty hooks object (hooks: {}), which Codex reads as "no hooks" instead of reaching the auto-discovery fallback. An absent field, [], and an empty inline list all collapse back to the fallback, so the value has to be exactly {}.

Removed orphaned Codex session-start dead code. hooks/session-start-codex had no caller once the Codex hook config was deleted, so it and its redundant test cases are gone. The worked shell-hook example in docs/porting-to-a-new-harness.md moves from Codex — now native skill discovery with no session-start hook — to Cursor, a live shell-hook harness, and the stale hooks-codex.json pointer in docs/windows/polyglot-hooks.md is corrected. The Codex plugin category is also fixed to "Developer Tools".

Packaging

New package-codex-plugin.sh for building the Codex portal package. A maintainer script produces a deterministic Codex "portal" archive — .zip by default, tar.gz on request — that normalizes entry timestamps, preserves executable modes, verifies every packaged skill ships its OpenAI metadata, includes the app and composer icons, and refuses to run against a dirty worktree. The packaged manifest keeps the source hooks: {} object so a portal-installed plugin avoids the same SessionStart auto-discovery, and the script can rebuild a byte-identical archive from a saved metadata source. Covered by a new test suite.

Lower Per-Session Token Cost

The using-superpowers bootstrap is injected into every session, so its size is paid for constantly. This release trims it and the per-harness references it points to, without dropping behavior-shaping content.

Compressed the using-superpowers bootstrap. Replaced the graphviz skill-flow diagram with the prose it encoded, folded the standalone Instruction-Priority section into User Instructions, dropped the per-platform "How to Access Skills" walkthrough, and trimmed the Platform Adaptation pointer to the harnesses that still ship a reference file. The full Red Flags rationalization table and the user-instruction precedence rules are unchanged.

Pruned the per-harness tool-mapping references. The verbose action-to-tool tables restated guidance modern agents already follow. Each reference file is trimmed to the harness-specific notes that still carry weight — subagent dispatch, task tracking, instructions-file paths — and claude-code-tools.md and copilot-tools.md, which had nothing harness-specific left, are deleted.

Codex

Codex can install from the marketplace. Codex marketplace sources expect a .agents/plugins/marketplace.json at the marketplace root; the repo only shipped the Claude marketplace file, so Codex could name the marketplace but found no installable plugin entries. A repo-local Codex marketplace manifest now points at the same repository root, so the plugin is installable from Codex.

Codex no longer ships a SessionStart hook. Codex reliably triggers skills on its own, and the bootstrap hook made the UX worse rather than better. The Codex hook config (hooks-codex.json) and its manifest registration are removed.

Harness Support

Gemini CLI support removed. Google EOLed the Gemini CLI on 2026-06-18; the extension can no longer be installed or updated. Gemini is gone from the install docs, the subagent-capable platform lists, and the eval-harness description, and its tool-mapping reference is deleted.

Subagent-Driven Development

SDD scratch files moved out of .git/. Claude Code treats .git/ as a protected path and denies agent writes there, so an implementer subagent writing its report into .git/sdd/ got blocked mid-run. Task briefs, implementer reports, review diffs, and the progress ledger now live in a self-ignoring .superpowers/sdd/ directory in the working tree — kept out of git status and out of commits, and resolved per worktree by a shared sdd-workspace helper. One caveat: because the workspace is git-ignored working-tree scratch, git clean -fdx will delete the progress ledger; recover from git log if that happens. (#1780)

v6.0.0 (2026-06-16)

Superpowers 6.0 is a big release. The headline is a rewrite of how subagent-driven-development reviews each task — cheaper, stricter, and harder to game.

While these numbers won't hold on every harness and for every workload, in our evals, Claude Code and Codex produce similar high-quality results roughly twice as fast and while spending almost 50% fewer tokens.

It also adds three new harnesses (Kimi Code, Pi, and Antigravity), gives the brainstorming visual companion a better security model, and rewrites a number of skills' tool calls to be significantly more vendor-neutral.

Visible Changes

The two per-task reviewer prompts became one. spec-reviewer-prompt.md and code-quality-reviewer-prompt.md are gone, replaced by a single task-reviewer-prompt.md. If you dispatch the old files directly, switch to the new one.

The legacy global worktree directory is gone. using-git-worktrees and finishing-a-development-branch no longer use ~/.config/superpowers/worktrees/. Worktrees now land in the project — an existing .worktrees/ or worktrees/ if you have one, otherwise a fresh .worktrees/ — unless you say otherwise.

New Harness Support

Superpowers now runs on three more harnesses. Each ships its own bootstrap, a tool-mapping reference, and tests, and each gets its own install section in the README.

• Kimi Code — a plugin manifest, install docs, and manifest tests; install from Kimi's marketplace or straight from the repo. (initial manifest by @qer)
• Pi — a session-start extension that registers the skills and injects the using-superpowers bootstrap. Pi has native skills, so it needs no compatibility shim.
• Antigravity (agy) — installs the plugin directly and bootstraps from the first message; verified end-to-end against the standard "make a react todo list" acceptance test.

Subagent-Driven Development

A long run of cost-and-quality experiments on real projects reshaped how the controller reviews each task. The old flow ran two reviewers per task and leaned on the controller's judgment for model choice and severity, and both turned out to be expensive and easy to game. The new flow runs one reviewer per task, hands work off as files instead of pasted text, and takes several judgment calls away from the controller.

• One reviewer per task, two verdicts. A single task-reviewer-prompt.md reads the task's diff once and returns both a spec-compliance verdict and a quality verdict, so one fix pass clears both. A new "can't verify from the diff" verdict flags requirements that live in untouched code, for the controller to check itself. (#1538, #1543)
• One broad review at the end. The run finishes with a single whole-branch review on the most capable model, instead of re-reviewing everything task by task.
• Plans get a pre-flight read. Before the first task, the controller checks the plan for internal conflicts — and for anything the plan asks for that a reviewer would flag as a defect — and raises it all at once, rather than stumbling into it mid-run.
• Diffs and task text move as files. A pasted diff parks itself permanently in the most expensive context, and a reviewer without one rebuilds it by hand — the single biggest reviewer cost. Two new scripts, task-brief and review-package, write the task text and the review diff to files for the subagent to read.
• Every dispatch states its model. Left to choose, controllers stopped naming a model at all — and an unnamed model quietly inherits the session's most expensive one, so one run put all 26 of its reviewers on the top tier. The templates now require a model, with guidance that reaches for cheaper tiers when the work allows.
• The controller can't tell a reviewer what to ignore. Real runs caught controllers coaching reviewers to skip a finding or call it "Minor at most," and the flaw shipped. Suppressing findings and pre-rating severity are now banned outright, and a defect the plan itself mandates gets reported for you to decide on rather than waved through.
• Reviewers are read-only and skeptical of rationales. Review no longer touches the working tree or branch — a reviewer running git checkout had been orphaning later commits — and an implementer's "I left this unabstracted on purpose" no longer talks a reviewer out of a real finding.
• Stronger evidence and reporting. Reviewers back each answer with a file and line, the implementer's report moves to a file and carries red/green evidence when TDD applies, and a progress ledger lets a controller that loses its context resume instead of redoing finished work. (#994)

Writing Plans

Plans now carry the structure the controller and reviewers used to re-derive on every dispatch.

• A Global Constraints block lists the rules that bind every task — version floors, dependency limits, naming and copy, exact values — copied in verbatim, so they actually reach the implementers and reviewers downstream.
• A per-task Interfaces block names exactly what each task consumes and produces, so an implementer who sees only its own task still knows its neighbors' contracts.
• Right-sizing guidance keeps a task at the size that earns its own test cycle and a reviewer's pass, folding setup, config, and docs into the task that needs them. In testing, a plan written this way needed one round of fixes where the control needed two to four — and the control shipped a real bug.

Brainstorming Visual Companion

The visual companion is a small web server the agent opens alongside the conversation. It had no authentication at all, so on a shared or remote machine anyone who could reach the port could read your brainstorm — or inject events the agent treats as your input. This release gives it a real security model and makes it survive restarts and dropped connections.

• A per-session key now guards everything. The agent's URL carries a one-time key, the browser tucks it into a tab-scoped cookie, and every request and WebSocket connection has to present it. This closes the door to stray local tabs and routable remote hosts alike, including the DNS-rebinding case an origin allowlist can't catch. (Closes #1014)
• The file server stays in its sandbox. It refuses symlinks, dotfiles, and any path that climbs out of the content directory, ignores macOS resource-fork files, and sends the usual no-store and deny-framing headers. Files that hold the session key are written owner-only.
• The companion is offered only when it helps. The skill raises it the first time a question would read better shown than told, as its own message, and lets a decline stand. Accepting opens your browser to the first screen. (Closes #755)
• It survives restarts and flaky connections. Given a project directory, the server keeps the same port and key across restarts, so an open tab simply reconnects. The page reconnects on its own, shows a live status pill, and raises a "paused" overlay while the server is down.
• Longer idle life, safer shutdown. The idle timeout went from 30 minutes to 4 hours, and stop-server.sh now confirms it owns the right process before signaling, so it never kills an unrelated node after a reboot. (#1703)
• Windows launch hardening — consolidated shell detection, and Windows now relies on the idle timeout for shutdown, since Node can't track POSIX process ownership across MSYS2.

Existing Harness Updates

• Codex now bootstraps through its own SessionStart hook rather than shared wiring, and the Codex App gained an install section and fuller tool docs (web search, AGENTS.md, personal skills). (#1540)
• OpenCode got an action-based tool mapping across its plugin, install doc, and README, plus a bootstrap-caching test.
• Cursor's manifest dropped its agents and commands entries, since those directories no longer exist.

One Set of Skills, Every Harness

The skills used to speak Claude Code's dialect — "use the Task tool," "put it in CLAUDE.md." This release rewrites that vocabulary in terms of what you're actually doing ("dispatch a subagent," "your instructions file") and adds a per-harness reference that maps each action to the right tool, checked against each runtime. Prose that named "Claude" now says "your agent."

• A tool reference per harness at skills/using-superpowers/references/, covering Claude Code, Codex, Copilot, Gemini, Pi, and Antigravity.
• finishing-a-development-branch went forge-neutral — it no longer hardcodes gh pr create, so agents push with whatever forge tooling they have. (#1609)
• One rename: "Claude Search Optimization" is now "Skill Discovery Optimization," since the technique isn't Claude-specific.

Writing Skills

Two additions for skill authors.

• Match the Form to the Failure — a short table for picking the right kind of guidance. A flat "don't do X" works for discipline slips but backfires when the problem is the shape of an output, where a worked example does better. The table, and a tighter scope on the existing rationalization section, steer authors to the form that actually helps.
• Micro-Test Wording — a cheap way to check a phrasing before committing to it: sample it a handful of times against a no-guidance control and read every result by hand, treating run-to-run variance as a warning sign.

Testing

Skill-behavior testing moved out of tests/ into a new evals/ submodule built on "drill," which runs real Claude Code, Codex, and Gemini sessions and judges them with an LLM. Several in-tree bash suites retired once a stricter drill scenario covered them; the few with no equivalent stayed. From here on, tests/ holds plugin-code tests and evals/ holds skill-behavior tests, and docs/testing.md explains the split. New backends reach Antigravity, Pi, and more models, and new shell-lint and pre-commit checks guard the harness. (#1541)

Bug Fixes

• systematic-debugging no longer forces every session into extended thinking. One bullet held the exact keyword Claude Code scans for, quietly tripping the switch on every session that loaded the skill. A hyphen breaks the keyword; the text still reads. (#1283, by @nick Galatis)
• The Windows SessionStart hook stopped printing a write error every session — each printf now routes through cat to absorb the broken pipe, and the output is otherwise unchanged. (#1612, reported by @silvertakana)
• Windows foreground mode tracks the right process and clears its owner PID on MSYS2. (by @nestorluiscamachopaz)
• The using-superpowers bootstrap no longer lists "debugging" as a skill that doesn't exist. (reported by @mhat)
• The TDD skill links the testing anti-patterns reference. (#1532, #1529; link fix #1474 by @stable Genius)
• using-git-worktrees fixes its step numbering and drops stale Cursor references. (#1522, and by @fuleinist)
• The Codex review skill swaps a private in-joke for plain guidance. (#1531)

Documentation & Contributor Guidelines

• A guide to porting Superpowers to a new harness (docs/porting-to-a-new-harness.md) lays out the three pieces every integration needs and the one rule that makes or breaks it: load the bootstrap at session start.
• Every PR and issue now discloses how it was made — model, harness, version, and installed plugins, or a note that it was written by hand. We weigh a contribution differently depending on what produced it. PRs also target dev, not main. The PR template, all three issue templates, and a new platform-support template carry this.

Contributors

Thanks to @mattvanhorn, @nawfal, @nick Galatis, @silvertakana, @nestorluiscamachopaz, @qer, @mhat, @stable Genius, @fuleinist, @dev_Hakaze, @robotsnh, Rahul, and @arittr.

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)

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

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)

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.

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