SDD 11 - Superpowers: Quick & Dirty Starter Guide
SDD Learning · Previous: BMAD Method lab route · Next: Superpowers lab route
Superpowers, maintained in obra/superpowers, is an engineering workflow built from composable skills. It aims to make a coding agent clarify the job, choose an appropriately sized design process, implement with feedback and verify its claims before finishing.
It belongs in this Learning because specifications are only one part of reliable delivery. A good contract can still be implemented with weak tests, speculative debugging or an unchecked “done”. Superpowers puts particular emphasis on those execution habits.
Quick start with Claude Code
In Claude Code's chat, install from the project's marketplace:
/plugin marketplace add obra/superpowers-marketplace
Then:
/plugin install superpowers@superpowers-marketplace
Restart or begin a fresh session if the tool requires it. These are Claude Code plugin commands, not Bash commands. The upstream README also lists the official Claude marketplace route; choose one route, not duplicate installations.
Ask the agent to use the workflow on a small change. A successful installation makes the relevant skills discoverable and changes how the agent works.
If you use Pi or OpenCode
For Pi, the current upstream README documents this terminal command:
$ pi install git:github.com/obra/superpowers
Start a fresh Pi session in the project. The package supplies skills and startup guidance. Subagent and task-list capabilities depend on optional companion tooling; do not assume installation creates them.
OpenCode has a separate plugin installation route. Follow the repository's OpenCode installation file and OpenCode guide. Inspect the steps for your installed version rather than copying another agent's plugin command.
Installing the package for one harness does not install it for all the others. A harness is the application that runs the agent, exposes tools and discovers skills; it is distinct from the language model.
The three starting paths
The current brainstorming skill scales the design artifacts to the work:
| Path | Fits | Expected design handoff |
|---|---|---|
| Spike | A feasibility question | An agreed probe and a finding; exploratory code is disposable |
| Bounded | A small change to an existing flow | A short design in chat, reviewed before implementation |
| Architectural | A new project, subsystem or interface restructuring | A written specification and implementation plan, with review stages |
“Small” is not just a word count. Adding a flag to an existing CLI is different from building a new CLI whose interfaces, error model and file handling do not yet exist.
Colors mean the same thing in every diagram of this Learning: see the color key.
The workflow's review pauses are part of its design. If your team wants a different interaction policy, document that policy explicitly rather than assuming a skill installation provides the same autonomy settings everywhere.
The skills to recognize first
| Skill | Engineering purpose |
|---|---|
brainstorming | Establish intent and a suitable design handoff |
writing-plans | Turn an approved architectural design into executable tasks |
test-driven-development | Work through observable red, green and refactor steps |
systematic-debugging | Find a cause before patching symptoms |
verification-before-completion | Require fresh evidence for completion claims |
requesting-code-review | Check work against the plan and engineering expectations |
finishing-a-development-branch | Verify the branch and present completion options |
You do not need to memorize all the invocation names. In a supported installation, skills can be selected by context. Explicitly ask for the relevant skill when you want to make that choice visible.
TDD should create evidence one behavior at a time
For the JSON feature, a useful first test invokes the existing CLI with --format json and expects parseable records. It should fail before the feature exists because the argument is unsupported. The agent then implements enough to satisfy that behavior and checks the unchanged baseline tests.
The next tests can exercise empty input and escaping. Avoid a single giant implementation followed by a test suite that simply records whatever the implementation happened to do.
TDD is a method for steering implementation. It is not proof that the requirement was the right one, that the test oracle is correct or that all important failure modes were covered.
Verification before completion
Ask the agent to distinguish what it executed from what it inferred. “The tests should pass” is a prediction; a current test result is evidence. A previous passing run becomes less useful after another code edit.
The verification-before-completion skill makes that distinction explicit. Apply it to builds, linters and integration checks as well as unit tests.
Subagents are an execution option
For planned work, upstream describes both subagent-driven development and an inline execution path. Their review costs and context behavior differ. Check what the selected harness actually supports.
More agents do not automatically create independent evidence. A reviewer can repeat the implementer's assumption, miss the same boundary case or review a diff that changed afterward. Associate findings with the actual code being reviewed, rerun relevant checks after fixes and keep final responsibility with the maintainer.
For the starter CLI change, one implementation session is enough. Parallel work would add coordination without much independent work to schedule.
How this differs from Matt Pocock's skills
Both projects include design thinking, testing, debugging and review. Compare how each one behaves as a workflow in your agent.
Matt's current system emphasizes explicitly chosen workflows, domain vocabulary, durable decisions and ticket decomposition. Superpowers emphasizes context-triggered engineering routines and staged design-to-execution behavior. Those emphases overlap and change over time; they are not exclusive capability boundaries.
If you try both, compare them in separate working copies first. Two active orchestrators can both try to own the next step, create competing plans or request the same decision twice.
Common mistakes
| Instead of | Prefer |
|---|---|
| Assuming installation equals activation | Confirm skill discovery in a fresh session |
| Treating a new subsystem as a tiny bounded edit | Choose the path based on the actual repository change |
| Writing tests after accepting the implementation | Observe a relevant failure before the fix |
| Accepting “looks correct” as verification | Ask for executed commands and current results |
| Installing several workflow frameworks at once | Evaluate one owner of the workflow at a time |
| Treating extra reviewers as a correctness guarantee | Review specific evidence and unresolved findings |
Practice on the shared lab
The Superpowers lab route walks levels 2 to 6 of the SDD Learning with Superpowers. It is the same small change every track uses: add JSON output to a tiny CLI and keep its text output unchanged.
A pragmatic adoption path
- Begin with one small change to existing code.
- Observe whether the agent chooses the right design path.
- Check that a meaningful failing test appears before the implementation.
- Review the completion evidence and remaining limitations.
- Try systematic debugging on a reproducible bug after the basic workflow is familiar.
My recommendation: choose Superpowers when the agent already understands the task but its implementation, debugging and completion habits need more structure.