Superpowers SDD: Subagent-Driven Development, and Where the Spec Lives
In Superpowers, "SDD" means subagent-driven development: the skill that carries out a written plan with a fresh implementer subagent for every task and a reviewer after each one. It does not mean spec-driven development, a phrase the repository never uses. Superpowers still has a spec, the design doc its brainstorming skill writes, and every task is checked against the plan that points back to it. This page covers where that spec and plan live, what a task goes through, how SDD compares with the cheaper Native mode in two runs we recorded, and what to add if you want acceptance criteria you can check.
This page is an independent explainer. Spec Coding is not affiliated with Superpowers, Jesse Vincent or Prime Radiant. Skill behaviour was checked against the source of Superpowers v7.0.2 (released 2026-11-03, still the latest on 2026-11-21). Run numbers come from our two recorded bridge runs of 2026-11-17, which used Superpowers inside OpenSpec; read the caveats in that section before quoting them.
What SDD means in Superpowers
Every "SDD" in the Superpowers repository refers to subagent-driven development. The release notes file the topic under "Subagent-Driven Development and Executing Plans". The progress file the skill keeps starts with # SDD ledger. Its helper scripts are called sdd-workspace and sdd-repo, and its scratch folder is .superpowers/sdd/. A search of the v7.0.2 source for "spec-driven" returns nothing.
The word "spec" does appear, in two places that matter. The design doc that brainstorming writes is saved under a folder called specs/, and the README describes the agent teasing "a spec out of the conversation". And each task review in SDD has a "spec compliance" verdict, which compares the diff with what that task asked for: the task brief and the plan's global constraints, not a separate requirements file.
So if you searched for "Superpowers SDD" you probably want one of two things. If you want the execution skill, the next three sections are about it. If you want to know whether Superpowers does spec-driven development, skip to Is Superpowers spec-driven development?
From request to merge: where the spec and the plan live
Superpowers is a set of skills that trigger on their own. Its bootstrap skill tells the agent that if there is "even a 1% chance a skill might apply", it must use it, and that "Let's build X" starts with brainstorming. The skills that make up a feature, in the order the README gives:
| Skill | What it produces | The gate |
|---|---|---|
brainstorming | A design doc, short for a small change and full for a project, at docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md, committed. It covers intent, goals, non-goals, constraints, the two or three approaches considered and which was picked. | "Nothing gets built until your human partner approves the design doc." A quick, clear task (its example is changing an icon colour) is simply done. |
using-git-worktrees | An isolated worktree with a clean test baseline | Asks before creating one in a normal checkout |
writing-plans | A plan at docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md: a header that names the design doc, then numbered tasks with exact files, interfaces and test-first steps | A self-review checklist; then the person reviews the plan and picks how to run it |
subagent-driven-development or executing-plans | Commits, task by task | Per-task review in SDD; test-first per task in both |
test-driven-development | A failing test before any production code | "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST" |
requesting-code-review | A review from a subagent using its code-reviewer.md prompt | Critical findings fixed at once, Important ones before moving on |
finishing-a-development-branch | Exactly three options: merge locally, push and open a PR, or keep the branch | The full test suite passes first; discarding needs you to type discard |
Both paths are defaults. The brainstorming skill says your own preference overrides its location, and the bootstrap skill puts instructions in CLAUDE.md, AGENTS.md or GEMINI.md above any skill. That is how the OpenSpec bridge redirects the design doc into its own change folder, and how you can add rules of your own (see below).
The plan is what SDD reads, so its header is worth knowing. writing-plans requires a goal, the architecture, the tech stack, a Spec: line with the design doc's path, global constraints with exact values copied from the design doc, and a review focus: inputs or failure modes the design implies that no task's tests cover. Each task names its files and the signatures it consumes or produces, then lists test-first steps. Here is a header and first task we wrote by hand to that shape, for the coupon example used elsewhere on this site:
**Goal:** Signed-in shoppers can apply one coupon code before payment.
**Architecture:** Validation in packages/billing; checkout calls it before
creating the payment intent.
**Tech Stack:** TypeScript, Node 22, Vitest
**Spec:** docs/superpowers/specs/2026-11-20-checkout-coupons-design.md
**Global Constraints:** one coupon per order; codes are case-insensitive;
a discount never takes the total below 0.00
**Review Focus:** a code that expires between validation and payment;
two tabs applying the same single-use code
### Task 1: Validate a coupon code
**Files:** Create packages/billing/coupons.ts
Test packages/billing/coupons.test.ts
**Interfaces:** Produces validateCoupon(code, orderId): CouponResult
- [ ] Write a failing test: an expired code returns { ok: false, reason: "expired" }
- [ ] Run it and confirm it fails
- [ ] Implement validateCoupon
- [ ] Run it and confirm it passes, with the rest of the suite
- [ ] Commit
The skill puts the size limit in one line: "A plan is the set of decisions the implementer cannot make alone. A plan longer than the code it describes has written the code instead." Lines like "handle edge cases" or "add appropriate validation" count as failures in the other direction, because they decide nothing.
What subagent-driven development does with each task
The skill's own summary: "Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end." In more detail:
- Set up a workspace. Each plan gets a git-ignored folder at
.superpowers/sdd/<plan name>/holding the ledger (progress.md), task briefs, reports and review packages. The ledger is, in the skills' words, "your memory": it records which task is done and every ruling made along the way. - Read the plan once, and the design doc it names. In the skill's words, "the spec is the authority the plan argues from". A pre-flight scan looks for conflicts before the first task.
- Brief one task. A script copies the task into its own file. "Never make a subagent read the whole plan file."
- Implement it with a fresh subagent. The implementer may not start subagents of its own, and the skill forbids running several implementers in parallel: tasks go one at a time.
- Review it. A script writes the diff to a file, and one task reviewer returns two verdicts, spec compliance and task quality. "Implementer self-review never replaces the task review." (The README still describes this as a two-stage review with two reviewers. That changed in 6.0; the skill files are current.)
- Fix, at most five rounds. Rounds one to three go back to the same implementer, rounds four and five to a fresh one on a more capable model, each followed by a scoped re-review. At the cap, open findings are ruled on in writing; "a silent discard is forbidden".
- Keep going without check-ins. The skill tells the agent not to pause between tasks. Only four things stop it: irreversible or destructive operations, security-sensitive actions, side effects outside the worktree, and a plan so broken that every path is a guess. Every other judgement call is written to the ledger as a
Ruling:. - Review the whole branch. After the last task, a reviewer on the most capable model available reads the entire branch. One fix subagent addresses its findings, followed by exactly one scoped re-review.
- Report and clean up. The final message lists every ruling under "Rulings I made", the workspace is deleted ("the git history is the record now"), and finishing-a-development-branch offers its three options.
The skill also says to name the model on every dispatch. In our run the implementers and task reviewers ran on Sonnet and the whole-branch review on Opus, the controller's model.
SDD or Native: what two recorded runs showed
Since 6.4.1, the plan handoff offers two ways to execute. Subagent-driven is "most thorough; costs a fresh context per task and per review". Native, the executing-plans skill, is "cheapest and fastest; no independent review until the end": the session implements every task itself under test-driven development, keeps the same ledger, and runs one fresh reviewer over the whole branch before fixing what it finds in a single pass, without a re-review.
Our two OpenSpec + Superpowers bridge runs happened to take one path each. Same request, same repository, same versions (Superpowers 7.0.2, OpenSpec 2.1.0, Claude Code 2.1.326, Opus 5.5 as the controller), scored by the same hidden suite of eight checks:
| Run A: subagent-driven | Run B: Native | |
|---|---|---|
| How the mode was chosen | Not offered: "this project's workflow sets the execution method" | Offered; the agent recommended Native ("There are only three small tasks") and the person agreed |
| Tasks in the plan | 4 | 3 |
| Subagents | 11: four implementers and four task reviewers on Sonnet, one whole-branch review on Opus, one fix wave, one re-review | 1: the whole-branch review on Opus |
| Checks per task | Test-first, then a task review with two verdicts | Test-first; the agent confirmed each failing test before implementing |
The pre-existing __proto__ id bug | Missed by all four task reviews, found by the whole-branch review | Found by the whole-branch review |
| Time and cost, whole session | 21 min 25 s, $6.28 | 16 min 3 s, $5.18 ($3.12 at merge) |
| Tests in the repo afterwards | 40 | 32 at merge, 35 at the end |
| Hidden checks passed | 8 of 8 | 6 of 8 |
This was not a controlled test of SDD against Native, and the last row is not a verdict on either. The runs also differed in the person: in run A they answered from the case's spec, in run B they approved whatever was proposed. Both of run B's misses trace back to brainstorming, before any code: the agent proposed adding details to validation errors only and leaving the X-Request-Id header out as "a separate feature from consistency", and both proposals were approved. No execution mode would have recovered a requirement the approved design left out.
What the runs do show about SDD itself:
- Task reviews check the task, not the system. Four of them passed code that kept the prototype-pollution bug. Each one compared a diff with its brief, as designed, and the bug was older than the change. The whole-branch review, which both modes run, is where it surfaced.
- Most of the bill is the controller, not the workers. Run A's ten Sonnet subagents cost $0.81 together. The other $5.47 was Opus: the controller across the whole session, planning included, plus the whole-branch review. Run B ran entirely on Opus with one subagent.
- The agent's summary is not the file. Before the plan, run A's agent told the person its spec had "seven requirements with 18 testable scenarios". The file had 15. Read the design doc, not the chat about it.
Our rule of thumb from this: let the agent recommend Native for a plan of a few small tasks, as it did here, and choose subagent-driven when the plan is long enough that a drifting task would be expensive to find at the end, or when the controller's context is the scarce resource. Either way, the approval of the design doc is the decision that moves the score.
Is Superpowers spec-driven development?
Partly. It is design-first and test-first, with a hard approval gate: no product code, scaffolding, dependency install or implementation skill until you approve a written design doc, and every plan carries a pointer back to it. What it does not have, compared with the tools usually filed under spec-driven development:
| Superpowers 7.0.2 | OpenSpec 2.1 | |
|---|---|---|
| Spec artifact | One prose design doc per change, plus the plan | A change folder: proposal, spec deltas, design, tasks |
| Requirement format | None; the doc is written for "a talented builder in the domain" | ### Requirement: with #### Scenario: blocks in WHEN/THEN form |
| After the merge | Design doc and plan stay where they were written; the execution ledger is deleted | The change is archived and its spec deltas are merged into openspec/specs/ |
So the question to ask is not whether Superpowers has a spec but whether its spec can be checked. A prose design doc can be approved; it is harder to verify a diff against. That is the gap the bridges fill: OpenSpec or Spec Kit supplies the requirements and the archive, and Superpowers supplies the discipline. Our OpenSpec vs Spec Kit vs Superpowers comparison covers both bridges, and the recorded runs show one end to end.
Adding acceptance criteria without another tool
If you want checkable criteria but not a second framework, put the rule where Superpowers looks first. Its bootstrap skill ranks your instruction files above its skills, so three lines in AGENTS.md (or CLAUDE.md) change what brainstorming writes and what writing-plans carries forward:
## Design docs (Superpowers)
- Every design doc in docs/superpowers/specs/ ends with "## Acceptance criteria":
numbered AC-1..n, each one observable behaviour, never a file name.
- Every plan task lists the AC ids it serves; every AC is served by a task.
- Test names start with the AC id they prove, e.g. "AC-2: used code is rejected".
The design doc then ends like this, and the plan's review focus and test names can refer to the ids:
## Acceptance criteria
AC-1: An expired code shows an inline error and the total does not change.
AC-2: A single-use code already applied to another order is rejected.
AC-3: The payment intent amount equals the discounted total.
This is our convention, not a Superpowers feature, and the agent follows it as an instruction rather than a schema, so check the first design doc it writes. The payoff comes at review: "which AC does this task serve?" has an answer, and a criterion with no task or no test shows up before the merge instead of after it. Our acceptance criteria for AI coding page has more on writing them.
Install and check that it is active
In Claude Code, install from the official marketplace with /plugin install superpowers@claude-plugins-official, or add the project's own marketplace with /plugin marketplace add obra/superpowers-marketplace and then /plugin install superpowers@superpowers-marketplace. The README documents installs for fifteen other harnesses, among them Codex CLI (/plugins, then search), Cursor (/add-plugin superpowers) and Gemini CLI (gemini extensions install https://github.com/obra/superpowers).
The README's check: start a fresh session and ask for something like "Let's make a react todo list". A working install starts brainstorming before it writes any code. Superpowers is MIT-licensed. Its brainstorming visual companion loads a logo that reports the plugin version; SUPERPOWERS_DISABLE_TELEMETRY turns that off.
FAQ
What does SDD stand for in Superpowers?
Subagent-driven development, the subagent-driven-development skill. It runs a written plan with a fresh implementer subagent per task and one reviewer after each task. The repository never uses the phrase spec-driven development.
Where does Superpowers save the spec?
brainstorming writes the design doc to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commits it. writing-plans saves the plan to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, with a Spec: line pointing back to the design doc. A location you set yourself overrides both.
What is the difference between subagent-driven-development and executing-plans?
subagent-driven-development gives every task a fresh implementer and a task reviewer with two verdicts. executing-plans, shown as Native in the handoff, has the session implement every task itself under test-driven development, with one fresh reviewer over the whole branch at the end. Both share the workspace, the ledger and the final review.
Is Superpowers a spec-driven development tool?
Partly. It will not build until you approve a written design doc, and every plan points back to it. It has no acceptance-criteria format and keeps no living spec after the merge. Pair it with OpenSpec or Spec Kit, or add numbered criteria to the design doc yourself.
Can subagent-driven development run tasks in parallel?
No. The skill says never to dispatch several implementers in parallel. For a skill that does run independent tickets side by side and reviews once at the end, see the implement-spec skill.
References
- subagent-driven-development SKILL.md, with its fix-loop and final-review references
- executing-plans SKILL.md (Native)
- brainstorming SKILL.md and writing-plans SKILL.md
- using-superpowers SKILL.md (the bootstrap and its precedence rule)
- Superpowers release notes and README (installation)
- Our bridge run pack: transcripts, plans, per-turn costs and hidden-suite results for both runs
Checked on 2026-11-21 against obra/superpowers v7.0.2 (commit 22f0b46). Quotes are from the linked files. Run figures are from the run pack recorded on 2026-11-17.