Releases · obra/superpowers

17 Jun 05:43

obra

Immutable

v6.0.2

b62616f

v6.0.2 Latest

Latest

Install Fixes

We no longer ship the evals submodule. It broke plugin installs for some users, so the eval harness now lives in its own repo, separate from the published plugin. (#1778, #1774)

Assets 3

16 Jun 17:47

obra

Immutable

v6.0.0

284be59

v6.0.0

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

Contributors

nick, mhat, and 9 other contributors

Assets 3

04 May 22:13

obra

Immutable

v5.1.0

f2cbfbe

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.