superpowers-reference

name	superpowers-reference
description	Complete reference tables for Superpowers modes, agents, recipes, and anti-patterns

Reference: The Superpowers Pipeline

The full development workflow:

/brainstorm  ->  Design document (user validates each section)
     |
/write-plan  ->  Implementation plan (bite-sized TDD tasks)
     |
/execute-plan  ->  Subagent-driven development (implement -> spec-review -> quality-review per task)
     |
/verify  ->  Fresh evidence that everything works
     |
/finish  ->  Merge / PR / Keep / Discard

At any point, if bugs arise: /debug (4-phase systematic debugging).

Priority order when multiple modes could apply:

1. Process modes first (/brainstorm, /debug) -- determine HOW to approach the task
2. Implementation modes second (/write-plan, /execute-plan) -- guide execution
3. Completion modes last (/verify, /finish) -- close out work

Reference: Mode Tool

The mode tool allows programmatic mode transitions. Use mode(operation="set", name="write-plan") to request a mode change. The first request will be blocked with a reminder — call again to confirm. This is useful when agents need to request transitions during automated workflows.

Reference: Modes

Mode	Shortcut	Purpose	Who Does The Work
Brainstorm	/brainstorm	Design refinement through collaborative dialogue	You (main agent)
Write Plan	/write-plan	Create detailed implementation plan with TDD tasks	You (main agent)
Execute Plan	/execute-plan	Subagent-driven development with three-agent pipeline	Subagents (you orchestrate)
Debug	/debug	4-phase systematic debugging	You (main agent)
Verify	/verify	Evidence-based completion verification	You (main agent)
Finish	/finish	Complete branch -- verify, merge/PR/keep/discard	You (main agent)

Reference: Agents

Agent	Purpose	When to Use
superpowers:brainstormer	Design refinement specialist	MANDATORY — after brainstorm conversation, delegate document creation
superpowers:plan-writer	Detailed plan creation	MANDATORY — after write-plan conversation, delegate plan creation
superpowers:implementer	Implements tasks following strict TDD	MANDATORY -- every task in /execute-plan
superpowers:spec-reviewer	Reviews implementation against spec	MANDATORY -- every task in /execute-plan, after implementer
superpowers:code-quality-reviewer	Reviews code quality and best practices	MANDATORY -- every task in /execute-plan, after spec-reviewer

Delegation rules:

• Brainstorm and Write-Plan: YOU own the conversation. When it's time to write the artifact, delegate to the brainstormer/plan-writer agent. The back-and-forth with the user is what makes these phases effective. The agent writes the document after you've validated everything.
• Execute-Plan: YOU delegate everything. You are the orchestrator. Every task goes through the three-agent pipeline (implementer -> spec-reviewer -> code-quality-reviewer). You never write code in this mode.
• Debug: YOU investigate (Phases 1-3). Fixes MUST be delegated to foundation:bug-hunter or superpowers:implementer (Phase 4). You own the investigation process but cannot write fixes directly — write tools are blocked in debug mode.
• Verify, Finish: YOU do the work directly. You may delegate infrastructure (shadow environments, test runners) in verify mode, but you own verification and completion.

Why fresh subagents per task:

• Clean context — No pollution from previous work
• Focused attention — Single task, single responsibility
• Quality gates — Review checkpoints catch issues early
• Parallel safety — Subagents don't interfere with each other

Reference: Recipes

Execute these workflows using the recipes tool:

Recipe	Purpose	When to Use
superpowers:recipes/superpowers-full-development-cycle.yaml	End-to-end: idea to merged code	Complete feature development
superpowers:recipes/brainstorming.yaml	Refine ideas into designs	Starting a new feature
superpowers:recipes/writing-plans.yaml	Create detailed implementation plans	After design is approved
superpowers:recipes/executing-plans.yaml	Execute plans in batches	For batch execution with checkpoints
superpowers:recipes/subagent-driven-development.yaml	Fresh agent per task + reviews	For same-session execution with foreach
superpowers:recipes/git-worktree-setup.yaml	Create isolated workspace	Before implementation
superpowers:recipes/finish-branch.yaml	Complete development branch	After implementation done

Reference: Anti-Rationalization Table

Your Excuse	Why It's Wrong	What You MUST Do
"This is a simple/trivial change"	Simple changes cause production outages. They still need tests and review.	Follow the appropriate mode's process.
"I can do this faster myself"	Speed is not the goal. Tested, reviewed, quality code is the goal.	In /execute-plan: delegate. In /brainstorm: follow the process.
"The user seems to want a quick response"	The user chose the Superpowers methodology. They want quality.	Give them the full process for the active mode.
"I'll write the test after"	That's not TDD. Test FIRST defines what you need, not confirms what you wrote.	RED-GREEN-REFACTOR. Always.
"This doesn't need a review"	Everything in /execute-plan needs review. Both reviews.	Delegate to spec-reviewer, then code-quality-reviewer.
"I need to debug this myself"	Use /debug mode and follow the 4-phase framework.	Activate debug mode. Phase 1 before any fixes.
"I already know what to build"	Then the brainstorming questions will be fast. That's not a reason to skip design.	Follow /brainstorm process. Assumptions kill designs.
"The plan is obvious"	If it's obvious, writing exact code will be fast. Vague plans produce bad implementations.	Follow /write-plan process. Every task needs complete code.
"Should work now"	Run the verification. "Should" is not evidence.	Use /verify. Run the command. Read the output. THEN claim.
"Just one more fix attempt"	3+ failed fixes = architectural problem. Stop fixing symptoms.	Question the architecture. Discuss with user.
"No mode applies here"	If there's even a 1% chance, suggest it. Let the user decide.	State which mode might apply and why.

Reference: Key Rules

1. Standing Order First -- Check which mode applies before starting any work. Suggest it even if you're only 1% sure.
2. Own Design Conversations, Delegate Artifacts -- You brainstorm and write plans through conversation. When it's time to produce the document, delegate to the brainstormer/plan-writer agent.
3. Delegate in Execution -- Every task in /execute-plan goes through the three-agent pipeline. No exceptions.
4. TDD Always -- No production code without failing test first.
5. Verify Everything -- Evidence before claims, fresh commands before assertions.
6. Systematic Debugging -- Root cause before fixes, 4 phases in order.
7. Human Checkpoints -- Validate designs section by section, approval gates at critical points.
8. Two-Stage Review -- Spec compliance first, then code quality -- for EVERY task in execution.

Reference: Skills

This bundle provides 2 Amplifier-specific skills. All other methodology skills are provided by obra/superpowers.

Skill	Purpose	Source
integration-testing-discipline	4 principles for E2E testing discipline	This bundle
superpowers-reference	Complete reference tables (this document)	This bundle
test-driven-development	TDD methodology and rules	obra/superpowers

Philosophy Reference

For deep understanding of the principles, see:

• superpowers:context/philosophy.md -- Core principles, anti-patterns, and the two-stage review pattern