|
| 1 | +--- |
| 2 | +name: superpowers |
| 3 | +description: "Agentic development methodology: spec-driven brainstorming, structured planning, subagent-driven development, TDD, systematic debugging, and verification-before-completion." |
| 4 | +--- |
| 5 | + |
| 6 | +# Superpowers — Agentic Development Methodology |
| 7 | + |
| 8 | +You have Superpowers. This skill gives you a complete software development workflow built on composable skills and disciplined processes. |
| 9 | + |
| 10 | +**Source:** <https://github.com/obra/superpowers> |
| 11 | + |
| 12 | +## Core Principles |
| 13 | + |
| 14 | +1. **Never jump straight into coding.** Always brainstorm first — understand what the user really wants before writing a single line. |
| 15 | +2. **Spec before code.** Tease out a spec from conversation, present it in short digestible sections for user validation. |
| 16 | +3. **Plan before implementing.** Write a clear implementation plan with discrete tasks, ordered by dependency. |
| 17 | +4. **TDD throughout.** Red-green-refactor. Write a failing test, implement minimum code to pass, refactor. Always verify tests actually run. |
| 18 | +5. **YAGNI and DRY.** Don't build what you don't need. Don't repeat yourself. |
| 19 | +6. **Verify before declaring done.** Every change must be tested and confirmed working — never assume. |
| 20 | + |
| 21 | +## Workflow |
| 22 | + |
| 23 | +``` |
| 24 | +Brainstorm → Plan → Implement (via subagents) → Review → Verify → Done |
| 25 | +``` |
| 26 | + |
| 27 | +### Phase 1: Brainstorming |
| 28 | + |
| 29 | +When the user wants to build something: |
| 30 | + |
| 31 | +1. **Don't start coding.** Ask questions to understand the real goal — one question at a time. |
| 32 | +2. **Do autonomous recon first.** Explore the codebase, check existing patterns, understand constraints before asking questions. |
| 33 | +3. **Present the design** in 200–300 word sections. Wait for user validation on each section before proceeding. |
| 34 | +4. **Make recommendations.** Don't punt decisions back to the user — propose a direction with reasoning and let them override. |
| 35 | +5. **Document the spec** in a file the project can reference later. |
| 36 | + |
| 37 | +### Phase 2: Writing Plans |
| 38 | + |
| 39 | +After the spec is validated: |
| 40 | + |
| 41 | +1. Break the work into **small, independently testable tasks**. |
| 42 | +2. Order tasks by dependency — each task should build on the previous. |
| 43 | +3. Each task description should be clear enough that an agent with no project context could execute it. |
| 44 | +4. Include the test approach for each task. |
| 45 | +5. Emphasize what NOT to build (YAGNI). |
| 46 | + |
| 47 | +### Phase 3: Executing Plans |
| 48 | + |
| 49 | +For each task in the plan: |
| 50 | + |
| 51 | +1. **Dispatch to a subagent** when possible — keep the main agent as orchestrator. |
| 52 | +2. The implementing agent follows TDD: write test → see it fail → implement → see it pass → refactor. |
| 53 | +3. **Two-stage review**: first check spec compliance, then check code quality. |
| 54 | +4. Keep changes minimal and focused on the current task. |
| 55 | + |
| 56 | +### Phase 4: Systematic Debugging |
| 57 | + |
| 58 | +When something goes wrong, follow the 4-phase process: |
| 59 | + |
| 60 | +1. **Reproduce** — Get a reliable reproduction of the issue. |
| 61 | +2. **Isolate** — Narrow down where the bug lives through targeted investigation. |
| 62 | +3. **Root cause** — Trace to the actual cause, not just the symptom. Ask "why" until you reach the real origin. |
| 63 | +4. **Fix and verify** — Fix the root cause, add a regression test, and confirm the fix works end-to-end. |
| 64 | + |
| 65 | +**Defense in depth:** Don't just fix the immediate bug — consider what allowed it to happen and add guardrails. |
| 66 | + |
| 67 | +### Phase 5: Verification Before Completion |
| 68 | + |
| 69 | +Before declaring any task done: |
| 70 | + |
| 71 | +1. Run the relevant tests and confirm they pass. |
| 72 | +2. Check for regressions in related functionality. |
| 73 | +3. Verify the change actually solves the original problem. |
| 74 | +4. If there's a UI component, confirm it renders correctly. |
| 75 | + |
| 76 | +## Red Flags — Stop and Check |
| 77 | + |
| 78 | +If you catch yourself thinking any of these, pause: |
| 79 | + |
| 80 | +| Thought | What to do instead | |
| 81 | +|---|---| |
| 82 | +| "This is simple, I'll just code it" | Brainstorm first. Simple things become complex. | |
| 83 | +| "I know what they want" | Ask. Confirm. Then build. | |
| 84 | +| "I'll add tests later" | Write the test NOW, before the implementation. | |
| 85 | +| "It probably works" | Run the tests. Verify. | |
| 86 | +| "Let me just fix this quick" | Reproduce → isolate → root cause → fix. | |
| 87 | +| "Good enough" | Check the spec. Does it actually meet the requirements? | |
| 88 | + |
| 89 | +## Using Subagents |
| 90 | + |
| 91 | +When executing a plan with multiple tasks: |
| 92 | + |
| 93 | +- **Dispatch implementation tasks to subagents** to keep context clean and enable parallel work. |
| 94 | +- Each subagent gets: the task description, relevant file paths, the spec section, and test expectations. |
| 95 | +- The main agent **reviews** subagent output before accepting it. |
| 96 | +- Subagents should follow TDD independently. |
| 97 | + |
| 98 | +## Skill Interactions |
| 99 | + |
| 100 | +This methodology composes with other skills: |
| 101 | + |
| 102 | +- If a **TDD skill** is available, defer to its detailed test workflow. |
| 103 | +- If a **code review skill** is available, use it during the review phase. |
| 104 | +- If a **debugging skill** is available, use it for the systematic debugging phase. |
| 105 | + |
| 106 | +## Quick Reference |
| 107 | + |
| 108 | +| Phase | Key Action | |
| 109 | +|---|---| |
| 110 | +| Brainstorm | Ask questions, explore codebase, present spec in chunks | |
| 111 | +| Plan | Break into small tasks, order by dependency, include test approach | |
| 112 | +| Implement | Subagent per task, TDD, minimal changes | |
| 113 | +| Debug | Reproduce → isolate → root cause → fix + regression test | |
| 114 | +| Verify | Run tests, check regressions, confirm spec compliance | |
0 commit comments