Superpowers: A Disciplined Development Workflow for Coding Agents

Superpowers (obra/superpowers, MIT, version 6.4.2) is a plugin of 15 skills plus a session-start bootstrap that makes a coding agent agree a design, isolate work in a worktree, write a reviewed plan, implement with strict TDD, review each task, and show test output before claiming done. It steers the model; CI and human review still enforce.

You ask the agent for “organization API keys with rotation”, and 20 minutes later it has touched 14 files, invented a permission model nobody asked for, and says “all tests pass” without showing a single run. This page is for developers and tech leads who want the agent to ask first, plan in the open, and prove its claims — and who need to know what that discipline costs.

What you get from this Superpowers guide

• Install lines for Claude Code, Codex and Cursor, and a 30-second check that the bootstrap fired.
• Which version each marketplace serves, and what 6.4.1 vs 6.4.2 changes in your plans.
• The eight-stage workflow and the artifact each stage leaves, so you review a design and a plan instead of every diff.
• Four copy-paste prompts, per-invocation token costs, and a failure table with recovery steps.

Superpowers at a glance (September 2026)

Fact	Value (read 2026-09-26 unless noted)	Source
Upstream version	6.4.2, released 2026-09-25	plugin.json, release notes
Anthropic’s claude-plugins-official	pins a commit that is 6.4.1	marketplace manifest
Author’s superpowers-marketplace	6.4.2	claude plugin install in Claude Code 2.1.283, 2026-09-26
Codex openai-curated (openai-api-curated with an API key)	manifest says 6.3.0	openai/plugins
Skills	15, plus a SessionStart hook that injects using-superpowers	claude plugin details
Always-on context	~838 tokens per session	claude plugin details, Claude Code 2.1.283, 2026-09-26
Popularity	1,009,371 installs on the Claude plugin directory; 291.7k GitHub stars	claude.com/plugins/superpowers; GitHub, read 2026-09-26

The install count covers Claude Code installs from Anthropic’s directory only, and stars measure attention on the repository, not active use. Neither says the workflow improves your code — that is what your own pilot measures.

How Superpowers works: skills, a bootstrap and harness adapters

Superpowers has three layers, and the difference between them explains most installation problems.

1. Skills. Fifteen SKILL.md procedures: brainstorming, using-git-worktrees, writing-plans, subagent-driven-development, executing-plans, dispatching-parallel-agents, test-driven-development, systematic-debugging, requesting-code-review, receiving-code-review, verification-before-completion, finishing-a-development-branch, writing-skills, using-superpowers and diagnosing-superpowers.
2. The bootstrap. using-superpowers tells the agent to check for an applicable skill before it answers, asks a question or touches the repository. The plugin injects it at session start; without it, the skills sit on disk and fire only when the model happens to pick them.
3. Harness adapters. Manifests and tool mappings for each host. Claude Code and Cursor use a session-start hook; Codex declares no hooks and relies on its native skill discovery.

The precedence is explicit: your instructions — direct requests and CLAUDE.md / AGENTS.md alike — override Superpowers skills, which override the agent’s defaults. If you want to learn skills and plugins in general first, start with the ecosystem overview and the plugins section.

Strong wording is not enforcement

Phrases like “Iron Law” and “You MUST” steer a probabilistic model. Agents still skip a test or misread a rule, especially after a model or harness update. Branch protection, CI and required review remain the actual gates.

Install Superpowers in Claude Code, Codex and Cursor

Install the native plugin for each agent you use. The README is explicit that each harness needs its own install.

Claude Code

Inside a session, pick one marketplace:

/plugin install superpowers@claude-plugins-official

That gives you Anthropic’s pinned commit (6.4.1 on 2026-09-26). To track upstream (6.4.2) instead:

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

The terminal equivalents are claude plugin marketplace add obra/superpowers-marketplace and claude plugin install superpowers@superpowers-marketplace (verified in Claude Code 2.1.283, 2026-09-26). Skills are namespaced: force a stage with /superpowers:brainstorming.

Codex

In the Codex CLI, open the plugin browser, search for superpowers, and select Install Plugin:

/plugins

In the Codex app, open Plugins in the sidebar and select + next to Superpowers. The plugin comes from the built-in openai-curated marketplace, whose manifest lagged upstream (6.3.0), so check what you received before you diagnose behaviour.

From a terminal, codex plugin list shows what the configured marketplaces offer, and codex plugin add installs by PLUGIN@MARKETPLACE (Codex 0.157.1):

codex plugin list
codex plugin add superpowers@openai-curated

Copy the exact id from codex plugin list: signed in with ChatGPT it is superpowers@openai-curated, with an API key superpowers@openai-api-curated (Codex 0.157.1).

Cursor

In Cursor Agent chat:

/add-plugin superpowers

Or search for “superpowers” in the plugin marketplace. This command comes from the Superpowers README; cursor.com was not reachable when this page was checked, so confirm the installed version in Cursor’s plugin view.

The upstream README also documents Antigravity, Devin CLI, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build CLI, Kimi Code, OpenCode, Pi, Qwen Code, Hermes Agent and Muse — copy those commands from the installation section, not from older articles. For Google’s agents, say “Antigravity CLI (personal accounts) / Gemini CLI (enterprise, API key)”: since 2026-06-18 Gemini CLI no longer serves free, Google AI Pro and Ultra users, who moved to Antigravity CLI. Superpowers dropped Gemini CLI in 6.1.0 and restored it in 6.2.0, so gemini extensions install https://github.com/obra/superpowers works again for Code Assist Standard or Enterprise, Google Cloud and paid API-key users.

Check that the bootstrap fired

Start a fresh session and send the README’s own smoke test:

Let's make a react todo list

A working install triggers brainstorming: the agent asks why you want the app and what it must do before it writes any code. If it starts scaffolding, the bootstrap is not loaded. In Claude Code, claude plugin list shows what is installed and claude plugin details superpowers shows the 15 skills, the SessionStart hook and the always-on token cost.

Traps when installing Superpowers

• npx skills add obra/superpowers is not the plugin. The portable copy has no session-start bootstrap, so the method does not fire on its own. Use it only when you want individual skills, such as npx skills add obra/superpowers --skill verification-before-completion.
• Install one copy per agent. The official and the author’s marketplaces both carry superpowers; installing from both, or the plugin plus npx skills add, gives duplicate skills.
• official does not mean latest. On 2026-09-26 superpowers@claude-plugins-official installed 6.4.1 while upstream was 6.4.2.
• npm superpowers is an unrelated 2022 package, and anthropics/superpowers does not exist.
• Legacy slash commands and the named code-reviewer agent were removed in 5.1.0. A guide that lists them describes an old version.

Which Superpowers version did you get, and why it matters

The three marketplaces served three versions in the same week. The differences are behavioural, not cosmetic:

You have	What changes in practice
6.3.0 (Codex openai-curated)	No diagnosing-superpowers. executing-plans is the old stub that stops every few tasks to check in. Brainstorming already scales ceremony (spike, bounded, architectural). The package ships its bundled scripts non-executable, so the SDD helpers fail with Permission denied (fixed upstream in 6.4.1).
6.4.1 (Claude official)	diagnosing-superpowers; executing-plans rebuilt as Native execution with one whole-branch review; you must review the saved plan before anything runs; plans carry a Review Focus section; TDD runs the project’s whole suite. Plans still spell out complete code.
6.4.2 (upstream, author’s marketplace)	writing-plans records decisions — signatures, test names and assertions, the spec’s values, the verification command — instead of full code. It was prompted by some frontier models implementing the project while “planning”. The maintainers report plans in about a quarter of the time and a third of the tokens in their reproduction (release notes, 2026-09-25).

If your team mixes Claude Code and Codex, the same prompt can produce a code-heavy plan on one and a decision-level plan on the other. Record the version in your pilot notes, and prefer the author’s marketplace in Claude Code if you want 6.4.2 now.

The Superpowers workflow, stage by stage

Each stage leaves an artifact you can review instead of the diff. The stages are the same in Claude Code, Codex and Cursor; what differs is the version each marketplace serves (see above) and the Claude Code-only nested controller.

1. Brainstorm and classify. brainstorming asks why you want the change, then classifies it as a spike, a bounded change or architectural work. A bounded change gets a short design in chat; architectural work gets a written spec at docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md. Every path stops for your approval.
2. Isolate. using-git-worktrees detects an existing isolated workspace or creates a worktree on a new branch, installs dependencies and runs the baseline tests. A red baseline stops the run and asks you what to do.
3. Plan. writing-plans saves docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md: per-task files, interfaces, test assertions, a verification command with its expected output, and a Review Focus list of inputs the spec implies but no test covers yet. You review the plan before execution.
4. Choose execution. The handoff offers two modes and recommends one. Subagent-driven dispatches a fresh implementer per task and a task review (spec compliance plus code quality) after each. Native (executing-plans) implements every task in the current session and gets one whole-branch review at the end — the cheapest mode.
5. Implement under TDD. test-driven-development requires a test that fails for the right reason, the smallest change that passes, then refactoring. Green means the project’s whole test command, not only the new test file.
6. Review. Task reviews loop up to five fix rounds before the controller adjudicates. A final reviewer reads the integrated branch.
7. Verify. verification-before-completion requires the actual output of the test, build, type-check or lint command before any “done”, “fixed” or “passing”.
8. Finish. finishing-a-development-branch reruns the tests and offers to merge locally, push and open a PR, or keep the branch. Discarding work happens only on your explicit request, with typed confirmation.

Example: organization API keys from vague request to PR

The request is: Add organization-level API keys with rotation and audit history. A healthy run looks like this:

Stage	Artifact you should see	Your checkpoint
Brainstorm	Questions on ownership, key visibility, revocation, permissions, retention and migration; two or three designs with trade-offs; classified as architectural	Approve behaviour and threat model
Spec	docs/superpowers/specs/2026-09-26-organization-api-keys-design.md, committed	Read it: it is shorter than the code
Isolation	A worktree with a passing baseline	Decide on any pre-existing failure
Plan	Schema, API, UI, migration and test tasks; Review Focus names “revoked key used during rotation” and “audit row on failed rotation”	Approve scope; add missing edge cases
Execution	Per task: failing test, minimal code, passing suite, commit, reviewer verdict	Answer product questions only
Final review	Whole-branch findings, fixed and re-reviewed	Decide whether the branch is ready
Verification	Fresh migration, test, type-check, lint and build output	Compare against acceptance criteria
Finish	PR opened	Normal PR review and CI

The value is not that the agent “made a plan”: the design, plan, test evidence and review findings stay inspectable after compaction or a handoff.

Copy-paste prompts for Superpowers

Copy-paste prompt: kick off a feature with explicit gates

Add organization-level API keys with rotation and audit history.
Use the Superpowers workflow. Treat this as architectural: write the design
spec and a plan, and stop for my approval after each. Constraints: keys are
shown once and stored hashed; rotation keeps the old key valid for 24 hours;
every create, rotate and revoke writes an audit row. Our test command is
`npm test` and the type check is `npm run typecheck`. Do not change the
auth middleware without asking.

Copy-paste prompt: review the plan before execution

Before we execute, review the saved plan against the design spec. List:
1) every requirement in the spec with the task and test that covers it,
2) any requirement with no test,
3) any task that changes a file the spec does not mention,
4) the Review Focus items and the test that pins each one.
Do not start implementation. Recommend Subagent-driven or Native execution
for this plan and give the reason in one sentence.

Copy-paste prompt: evidence before the pull request

Before you open the PR, use verification-before-completion. Run the full
test suite, the type check, lint and the build from a clean state. Paste the
command and the last 20 lines of output for each. Then map each acceptance
criterion in the spec to the test name that proves it. If any criterion has
no test, say so and stop instead of opening the PR.

Copy-paste prompt: find out why a session went wrong

Figure out what went wrong with superpowers in this session. I expected
brainstorming to stop for approval before any code, but files were created
before I approved the design. Report what happened with path:line evidence
from the transcript and tell me which skill did or did not fire.

The last prompt needs 6.4.1 or later, where diagnosing-superpowers exists.

How you verify Superpowers output without reading every line

Superpowers moves your review effort from the diff to three short documents and a set of machine gates:

• Before code: you approve the spec (behaviour, threat model, non-goals) and the plan (task list, test assertions, Review Focus). This is where a human catches “built the wrong thing”.
• During execution: each task commit must follow a failing test, and each task has a reviewer verdict. Spot-check two or three tasks: the test should fail on the parent commit and pass on the task commit.
• Before merge: the verification output, CI on the PR, and your repository’s required review. Add the gates Superpowers cannot provide — coverage or mutation thresholds and required status checks — so a skipped TDD step fails loudly instead of silently. See the evidence bundle a PR should carry and how to review agent pull requests.
• Sign-off: the developer who ran the session owns the spec and plan approval; the PR reviewer (or tech lead, for architectural work) signs off on the evidence, not on line-by-line reading.

What Superpowers costs per session and per invocation

Claude Code’s own projection (claude plugin details, 2.1.283, 2026-09-26):

Cost	Tokens
Always on, every session (skill listing + bootstrap)	~838
brainstorming, each time it fires	~6.3k
subagent-driven-development, each time it fires	~11.8k, plus a fresh context per implementer and per reviewer

The always-on cost is low for its family — Compound Engineering is ~2,989 and Everything Claude Code ~41,515 on the same measurement. The spend comes from execution. To keep it down:

• Choose Native execution for plans of small, same-shape tasks; it uses one context plus one final review.
• In Claude Code, ask for the SDD controller to run as a nested subagent on a mid-tier model; the 6.4.1 release notes (2026-09-18) report about half the cost and wall-clock time, measured by the maintainers. It is opt-in.
• Let brainstorming classify small work as bounded rather than forcing the full spec path.

When to use Superpowers and when to skip it

Use the full workflow when requirements are ambiguous, the change spans several layers, behaviour can be tested, or the work will be handed across sessions or people.

Skip it, or use single skills, for one-line or mechanical fixes, throwaway spikes, repositories without a test runner (TDD and verification then produce ceremony without a signal), or a process that already has stronger gates. systematic-debugging and verification-before-completion are worth having on their own; the testing and debugging skills page covers them without the framework.

If you need a durable, living specification rather than a per-feature design doc, compare spec-driven frameworks such as Spec Kit and OpenSpec. For the whole field, see the frameworks comparison.

What breaks with Superpowers and how to recover

Symptom	Cause	Recovery
The agent jumps straight to code	Bootstrap not loaded: a portable npx skills add copy, or the hook blocked	Install the native plugin; run the smoke test; check claude plugin details superpowers for the SessionStart hook
Skills appear twice	Installed from two marketplaces, or plugin plus npx skills add	Remove one copy per agent
Plans are pages of code on one tool, short on another	Version drift: 6.4.1 or 6.3.0 vs 6.4.2	Align versions; in Claude Code install from superpowers-marketplace
Execution stops every few tasks to check in	Codex 6.3.0 executing-plans	Expect it until openai-curated updates, or choose Subagent-driven
Codex: skill scripts fail with Permission denied	openai-curated 6.3.0 package strips executable bits (fixed in 6.4.1)	Invoke the script through its interpreter (bash scripts/<name>.sh) or wait for openai-curated to ship 6.4.1+
Codex asks to trust a SessionStart hook	A pre-6.1.1 package	Update the plugin; Codex versions from 6.1.1 declare no hooks
Windows: bootstrap silently never loads	Hook shell quoting before 6.2.0	Update to 6.2.0+, use Claude Code 2.1.81 or later, and install Git for Windows
Two plans in one checkout overwrite each other’s state	.superpowers/sdd/ shared before 6.2.0 (same basename before 6.4.1)	Update; still give each concurrent session its own worktree
“Tests pass” with no output	Verification skipped	Paste the evidence prompt above; treat the run as failed until output appears
TDD skipped	Model non-compliance	Treat as a failed run; add a CI or review gate instead of stronger wording
Worktree removal would lose files	Uncommitted work in the worktree	6.3.0+ stops and names the files; commit or stash, never --force
A skill fired or stayed silent unexpectedly	Trigger mismatch	Run the diagnosis prompt above (6.4.1+) and file the scrubbed bundle upstream

Security checks before you adopt Superpowers

Skills are instructions an agent with shell and network access acts on, so review them like code. Follow skill supply-chain security, then check these specifics:

• The Claude Code, Cursor and several other adapters run a SessionStart hook; read hooks/ before you install, and re-read it on updates.
• The optional brainstorming Visual Companion is a local Node server bound to 127.0.0.1 by default. Binding it to 0.0.0.0 widens the trust boundary.
• The companion loads a Prime Radiant logo URL that includes the Superpowers version. Set SUPERPOWERS_DISABLE_TELEMETRY=true to stop it; it also honours DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.
• An issue opened on 2026-09-10 (#2277) reports that systematic-debugging ships pressure-test fixtures written as imperative scenarios, which get installed into runtime directories. Check whether your version still has them.
• receiving-code-review treats review comments as claims to verify. External PR comments are still untrusted input: never let one trigger secrets access or unrelated commands.

What the evidence says about Superpowers

The maintainers run superpowers-evals, a lab that drives real agent CLIs through triggering, TDD, review and verification scenarios. It measures workflow compliance; its few no-plugin comparisons cover single skills (6.4.1 found the old executing-plans stub no better than no plugin), not the whole bundle, so it does not show that the bundle beats an agent without it. No independent, controlled comparison of the whole framework was available on 2026-09-26, so run your own.

Roll Superpowers out to a team

1. Pick one pilot. A medium feature with clear acceptance criteria — not a toy, not the riskiest migration.
2. Record a baseline on comparable work without the plugin: first-pass acceptance, human corrections, review defects, wall-clock time and tokens.
3. Pin and record the Superpowers version, marketplace, agent version and model for every participant, so drift does not look like a result.
4. Set policy in CLAUDE.md / AGENTS.md: who approves specs and plans, when TDD exceptions are allowed (visual work, generated files), and which commands always need confirmation.
5. Run each concurrent session in its own worktree, with no production secrets in the environment. See Git worktrees for parallel agents.
6. Measure with and without the plugin. In Claude Code, claude plugin eval runs eval cases against the plugin and reports the score delta against a no-plugin baseline. Put your cases (case.yaml, or prompt.md plus graders/*.md) in a directory below the plugin — a local checkout works as the target — and pass its name with --eval-dir; the no-plugin baseline arm (--ablation with-without) is on by default (Claude Code 2.1.285, checked 2026-09-26).
7. Keep, trim or remove skills after the pilot, and re-run it after every model, agent or plugin major update.

Where to go next with Superpowers

Agentic development frameworks compared Where Superpowers sits next to Spec Kit, BMAD, OpenSpec, GSD and Compound Engineering.

Spec-driven frameworks When a living specification beats a per-feature design doc.

Compound Engineering A plan–work–review–compound loop that feeds lessons back into the repo.

Test-driven development with agents RED–GREEN–REFACTOR with agents, beyond the Superpowers skill.

Top plugins The other plugins worth installing, with measured context cost.

Grill Me A deeper requirements interview to run before Superpowers brainstorming.