SUPER
POWERS
A complete software development workflow for AI coding agents. Composable "skills" enforce TDD, systematic debugging, brainstorm-to-plan-to-implement pipelines, git worktrees, subagent dispatching, and code review — automatically, from the first message.
& Spec
Worktree
Plan
Execution
Red/Green
Review
Branch
Superpowers is not a model — it's a process layer. It gives your AI agent a library of composable "skills" that enforce good engineering habits automatically. Before writing any code, it brainstorms. It plans before it acts. It tests before it ships.
brainstorming
Asks questions, refines ideas, presents design in chunks for review. Saves a design doc. Always runs before writing code.
Auto — before codewriting-plans
Breaks approved design into 2–5 minute tasks. Each task has exact file paths, complete code, and verification steps.
Auto — after designsubagent-driven-development
Dispatches a fresh subagent per task with two-stage review (spec compliance, then code quality).
Auto — after plantest-driven-development
Strict RED → GREEN → REFACTOR. Write the failing test first, implement just enough to pass, then clean up. No exceptions.
Rigid — always TDDsystematic-debugging
4-phase root cause process: identify, hypothesise, test, fix. Includes root-cause-tracing and verification-before-completion.
Auto — on bugsusing-git-worktrees
Creates isolated workspace on a new branch after design approval. Runs project setup, verifies clean test baseline.
Auto — after designcode-review
Validates each completed task against the original plan and coding standards before moving to the next.
Auto — after each taskverification-before-completion
Ensures the fix or feature actually works. Runs tests, lint, and build before declaring success.
Rigid — before doneIf there's even a 1% chance a skill applies to the current task, the agent must invoke it. This prevents skills from being quietly skipped.
Rigid skills (TDD, debugging) must be followed exactly — never adapt them away. Flexible skills (patterns, brainstorming) adapt principles to context. The skill itself tells you which it is.
Superpowers works with Claude Code, Cursor, Codex, OpenCode, Copilot CLI, and Gemini CLI. You need Node.js and the CLI for whichever agent you use. No Bun required — Superpowers installs via the plugin marketplace.
Add the Superpowers marketplace to Claude Code
Inside a Claude Code session, run:
Install the plugin from the marketplace
Or install directly from the official Claude marketplace (no marketplace add needed):
Quit and restart to activate
After restarting you'll see this injected at every session start:
This bootstrap teaches the agent it has skills and must search for and use them.
Start a new Claude Code session and ask: "What skills do you have?" — Claude will search and list the installed Superpowers skills.
Superpowers works across 6+ agents. Click a tab for agent-specific install commands.
You don't need to invoke skills manually. Once Superpowers is installed, the agent automatically picks the right skill based on what you ask.
"Let's build X" → brainstorming activates automatically
Just ask naturally. The agent will ask questions, build a spec, then a plan, then implement:
Claude will not jump straight into code. It will ask clarifying questions first, present a design for you to approve, then proceed to planning.
"Fix this bug" → systematic-debugging activates
The agent runs through the 4-phase debugging process: identify → hypothesise → test → fix. It will not declare success until verified.
After implementation, code review runs automatically per task
After each task in the plan is completed, a code-reviewer subagent validates it against the original spec and coding standards before moving on.
You can also ask for a review explicitly: "Review what you just implemented against our plan"
Ask Claude what skills it has available
Claude will search the skills directory and give you a full list with descriptions.
Dispatch multiple subagents in parallel for large plans
For plans with independent tasks (e.g. UI, tests, and docs), the subagent-driven-development skill can run them in parallel:
Each subagent gets its task, implements it with TDD, and is reviewed before the next task starts.
Write your own skills for your team's specific workflows
Skills are just markdown files. Create a SKILL.md in your repo and the agent will find and use it:
Skills placed in your repo are automatically discovered and indexed. The agent searches for skills before every action using the Skill tool.
Skills update automatically when you update the plugin
No manual file management needed. The plugin system handles versioning.
User instructions always win over skills
Add a CLAUDE.md to your project root to override any skill behaviour. For example, to disable TDD for a specific project:
User instructions (CLAUDE.md / AGENTS.md) > Superpowers skills > Default agent behaviour. You are always in control.
Test your custom skills with subagents before using them
The Superpowers repo includes a writing-skills skill that teaches Claude how to write and test new skills using realistic scenarios:
See skills/writing-skills/SKILL.md in the superpowers repo for the complete guide.
🛠 Install Commands
/plugin marketplace add obra/superpowers-marketplaceRegister the marketplace/plugin install superpowers@superpowers-marketplaceInstall from marketplace/plugin install superpowers@claude-plugins-officialInstall from official marketplace/plugin update superpowersUpdate to latest versioncopilot plugin marketplace add obra/superpowers-marketplaceCopilot CLI installgemini extensions install github.com/obra/superpowersGemini CLI install
🧠 Core Skills
brainstormingAuto-runs before any code — refines specwriting-plansBreaks design into 2–5 min taskssubagent-driven-developmentParallel subagent executiontest-driven-developmentStrict RED/GREEN/REFACTORsystematic-debugging4-phase root cause processusing-git-worktreesIsolated branch workspacecode-reviewPost-task quality gateverification-before-completionTests pass before done
💬 Trigger Phrases
"Let's build X"→ brainstorming first"Fix this bug"→ systematic-debugging"Plan this feature"→ brainstorming + writing-plans"Review my code"→ code-review skill"What skills do you have?"→ lists all skills"Use parallel subagents"→ subagent-driven-development
📁 File Locations
~/.claude/plugins/cache/Superpowers/Plugin install location~/.config/superpowers/skills/🔮 Personal skills (shadow core)skills/*/SKILL.mdIndividual skill filesCLAUDE.mdProject-level overrides (highest priority)AGENTS.mdMulti-agent project instructionsdocs/superpowers/plans/Generated plan location
🔮 Hidden Commands & Skills
/find-skills <query>Search all skills by description/using-superpowersManual skill-loader meta-command/brainstormingNew canonical name (v5)/writing-plansNew canonical name (v5)/executing-plansNew canonical name (v5)/subagent-driven-developmentParallel subagent skillexport CODEX_CI=1Foreground mode for Codex$SCREEN_DIR/.server-infoVisual Brainstorming URL location
📝 Phrases That Invoke Skills
"Show me visual mockups"→ Visual Brainstorming companion"Use the superpowers:X skill"Force a specific skill by name"Review the spec for gaps"→ Adversarial spec review"Use parallel subagents"→ subagent-driven-developmentultrathink(keyword)Force high-effort reasoning one turn"Create a skill for X"→ writing-skills
⛔ Rejected / Deprecated / Traps
/brainstorm❌ DEPRECATED in v5 — only shows warning. Use/brainstormingskill/write-plan❌ DEPRECATED in v5 — usewriting-plansskill/execute-plan❌ DEPRECATED in v5 — useexecuting-plansskill- Asking Claude to invoke /brainstorm❌ Blocked by
disable-model-invocation:true - Starting subagents from a subagent❌ v5 anti-recursion guard prevents this
- Plans with "TBD" sections❌ Spec review loop will reject — fill it in
- Skipping the brainstorming phase❌ Skills will re-introduce questions; just answer them
- Using
brainstormingwithout prefix❌ Usesuperpowers:brainstormingto avoid collisions - Editing core skill files❌ Use
~/.config/superpowers/skills/to shadow instead - Running
subagent-driven-developmenton Gemini❌ No subagent support — falls back to executing-plans
🚦 Troubleshooting
| Problem | Fix |
|---|---|
| Skills not activating | Quit and restart your agent after install — the session-start hook only fires on fresh sessions |
| Agent jumps straight into code | Skills aren't loaded. Verify install with "What Superpowers skills do you have?" |
| TDD being skipped | TDD is a rigid skill — add it to your CLAUDE.md as a reminder, or explicitly say "Use TDD" |
| Plugin not found in marketplace | Must register the marketplace first: /plugin marketplace add obra/superpowers-marketplace |
| Skills not updating | Run /plugin update superpowers inside Claude Code |
| CLAUDE.md conflicting with skills | User instructions always win — remove the conflicting line from CLAUDE.md if you want skill behaviour |
Automatically, every time you ask the agent to build something new — before it enters plan mode.
Turns vague ideas into clear, approved specs
- Assesses scope — if too large, helps you decompose into sub-projects first
- Asks questions one at a time (multiple choice where possible)
- Presents the design in sections short enough to actually read
- Saves the design document to disk
- Only proceeds to
writing-plans— never jumps to implementation
Browser-based mockups during brainstorming
For questions involving layouts or diagrams, the agent may offer to open a local browser URL to show you visual options. It will ask once for consent — you can decline and stay text-only.
Visual companion is token-intensive. Only say yes if you're designing a UI or need architecture diagrams.
TDD must be followed exactly. If the agent tries to skip it, it is rationalising. "Skip TDD just this once" is always wrong.
RED → GREEN → REFACTOR
Non-negotiable TDD rules
- ❌ Write code before the test? Delete it. Start over.
- ❌ Tests passing immediately (before any implementation)? Tests are wrong — fix them.
- ❌ "I'll add tests after" → Tests-after verify what you remembered, not what's required.
- ✅ Found a bug? Write a failing test reproducing it first, then fix.
Follow the 4 phases exactly. Don't skip to a solution before identifying root cause.
Clearly define what's wrong and gather evidence
What exactly fails? Under what conditions? What does the error message say? What does the stack trace show? Gather all data before forming hypotheses.
Generate potential causes from the evidence
List at least 3 plausible root causes. Rank by likelihood. Do not skip to the most obvious one.
Systematically test each hypothesis with controlled experiments
Isolate each hypothesis. Add targeted logging. Use condition-based-waiting and root-cause-tracing techniques where relevant.
Apply the verified fix, then confirm via verification-before-completion
Write a test that reproduces the bug first. Apply the fix. Confirm the test passes. Run the full test suite. Never declare "fixed" without verification.
After you approve the brainstormed design. Produces a plan clear enough for "an enthusiastic junior engineer with poor judgement and no project context" to follow.
Each task should be 2–5 minutes of work
YAGNI, DRY, TDD — baked into every task
- YAGNI — You Aren't Gonna Need It. Don't implement features not in the spec.
- DRY — Don't Repeat Yourself. Extract shared logic.
- Every task has a test — no task is complete without a passing test.
- Exact file paths — no ambiguity about where changes go.
Automatically after design approval. Creates an isolated branch workspace so parallel tasks don't clobber each other.
Creates a clean isolated workspace for each feature
- Creates a new git branch for the feature
- Sets up a git worktree so work is isolated from main
- Runs project setup (install deps, etc.)
- Verifies a clean test baseline before any code is written
At the end of implementation, Claude offers three options
- 🔀 Open a GitHub Pull Request — creates the PR automatically
- 🔗 Merge worktree back to source branch — merges locally
- ⏹ Stop — leave the worktree for you to handle
Copy these prompts directly into your agent session to see Superpowers in action.
Build a feature from scratch using the full 7-stage workflow
What happens: brainstorming asks 3–5 questions → spec saved → git worktree created → plan written in 2–5 min tasks → subagents implement each task with TDD → code reviewed → branch finished.
Reproduce, root cause, fix, verify
Systematic-debugging runs: identifies the session/cookie issue → tests hypotheses → fixes root cause → writes a regression test → verifies with the full test suite.
Split a large refactor across parallel agents
After brainstorming confirms the split is safe, three subagents work in parallel, each with their own worktree, TDD, and code review gate.
Teach Claude your team's deployment process
Claude uses the writing-skills skill to write and test your new skill with subagents before saving it to your repo.
Break a big idea into sub-projects
Brainstorming detects this is too large for one cycle. Claude helps decompose it into 4 sub-projects and starts with the first: "What order should we build these in?"
Don't rush through the spec phase
The brainstorming skill exists because jumping straight to code is the most common source of rework. Let Claude ask all its questions. Approve the spec only when you'd be happy building exactly what's written.
"Skip TDD just this once" is always wrong
Tests-first force edge case discovery before implementing. Tests-after verify what you remembered — not what's required. TDD is a rigid skill for a reason. If you find yourself wanting to skip it, that's a red flag, not a reason to skip.
Capture your project's specific constraints in CLAUDE.md
These rules override skills and persist across all agent sessions in this project.
Don't skip the verification step
When Claude says "done", it should have run tests, lint, and build first. If it hasn't, ask: "Run verification-before-completion before we continue."
Worktrees + TDD make risky changes safer
Refactors are where Superpowers shines most. Isolated worktrees mean you can't break main. Small planned tasks mean each change is verifiable. TDD means you know the behaviour hasn't changed.
Share useful skills with the community
If you write a skill that solves a common problem, submit a PR to github.com/obra/superpowers. Skills update automatically for all users when merged.
Join the Superpowers Discord for community support, sharing skills, and seeing what others are building.
How to write skills, contribute, and understand the Superpowers architecture.
Key folders
SKILL.md format — the complete structure
Any SKILL.md in a skills/*/ directory is automatically indexed and searchable by the agent.
The bootstrap process
At session start, the hooks system reads skills/using-superpowers/SKILL.md, escapes it for JSON embedding, and wraps it in an <EXTREMELY_IMPORTANT> block. It's injected as additionalContext — ensuring the agent sees it before any user message.
The output includes both additional_context (Cursor compatibility) and hookSpecificOutput.additionalContext (Claude Code) so the same skill works across agents.
Always respect this order
| Priority | Source | Example |
|---|---|---|
| 1 — Highest | User instructions (CLAUDE.md, AGENTS.md, chat) | "Don't use TDD for this project" |
| 2 — Skills | Superpowers skill files | test-driven-development skill |
| 3 — Lowest | Default agent behaviour | Agent's built-in tendencies |
How to submit a skill or fix
- Fork github.com/obra/superpowers
- Read
skills/writing-skills/SKILL.md— this is the authoritative guide for skill authoring - Write your skill following the SKILL.md format
- Test it with subagents using realistic scenarios (not quiz-show questions)
- Submit a Pull Request — MIT licensed
Before submitting, ask Claude to test your skill with "realistic scenarios that put pressure on the agent" — not easy questions where any answer looks correct. This is how the Superpowers team validates skills internally.