microsoft/superpowers-reference

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