---
name: superpowers-workflow
description: "Agentic software development workflow inspired by obra/superpowers (118k stars). Use when building any software feature, fixing bugs, or working on a codebase. Activates a structured 6-stage pipeline: brainstorm, spec, plan, TDD implementation, code review, and verification. Prevents jumping straight into code without a design. Enforces test-driven development, sub-agent task dispatch, and mandatory code review before merge."
---

# Superpowers Workflow

This skill implements the full obra/superpowers development methodology adapted for Manus. It turns any coding task into a structured, high-quality pipeline that prevents the most common AI coding failures: skipping design, writing untested code, and shipping without review.

**Source:** https://github.com/obra/superpowers (118k stars)

**Announce at start of any coding task:** "I'm using the superpowers-workflow skill. Starting with brainstorming before touching any code."

---

## Karpathy Behavioral Guardrails (Always Active)

These 4 principles from Andrej Karpathy (Tesla AI, OpenAI) run underneath every stage of the pipeline. They are not optional and do not turn off for "simple" tasks.

**Source:** https://github.com/forrestchang/andrej-karpathy-skills (84.5k stars)

### 1. Think Before Coding
Never assume. Never pick an interpretation silently and run with it.
- State assumptions explicitly before starting
- If ambiguity exists, present multiple interpretations — do not pick one silently
- Push back when a simpler approach exists — say so before coding
- Stop and name what is unclear rather than guessing and proceeding
- Ask rather than assume. Always.

**The test:** Could the user have meant something different? If yes, ask.

### 2. Simplicity First
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was explicitly asked
- No abstractions for single-use code
- No "flexibility" or "configurability" that was not requested
- No error handling for impossible scenarios
- If 200 lines could be 50, rewrite it

**The test:** Would a senior engineer say this is overcomplicated? If yes, simplify before submitting.

### 3. Surgical Changes
Touch only what you must. Clean up only your own mess.
- Do not "improve" adjacent code, comments, or formatting that was not part of the request
- Do not refactor things that are not broken
- Match existing style, even if you would do it differently
- If you notice unrelated dead code, mention it — do not delete it
- Remove only imports/variables/functions that YOUR changes made unused

**The test:** Every changed line must trace directly to the user's request. If it cannot, undo it.

### 4. Goal-Driven Execution
Define success criteria first. Loop until verified.
- Transform imperative tasks into verifiable goals
- Instead of "fix the bug" → "write a test that reproduces it, then make it pass"
- Instead of "add validation" → "write tests for invalid inputs, then make them pass"
- For multi-step tasks, state a brief plan with a verify step after each action
- Strong success criteria let the agent loop independently — weak criteria require constant clarification

**The test:** Can success be verified without asking the user? If not, define better success criteria first.

---

## The 6-Stage Pipeline

Every task — no matter how simple — goes through these stages in order. Never skip a stage.

```
BRAINSTORM → SPEC → PLAN → IMPLEMENT (TDD) → REVIEW → VERIFY
```

---

## Stage 1: Brainstorm

**Trigger:** Any request to build, modify, or fix something.

**Hard Gate:** Do NOT write any code until the user has approved a design. This applies to every project regardless of perceived simplicity.

**Steps (in order):**
1. Explore project context — read existing files, docs, recent changes
2. Ask clarifying questions — one at a time, never multiple at once
3. Propose 2-3 approaches with trade-offs and a recommendation
4. Present design in sections — get approval after each section
5. Write spec document to `docs/specs/YYYY-MM-DD-<topic>-design.md`
6. Self-review the spec: scan for TBD/TODO, contradictions, ambiguity
7. Ask user to review the written spec before proceeding

**Key principles:**
- One question per message. Multiple choice preferred over open-ended.
- YAGNI ruthlessly — remove unnecessary features from all designs.
- If request covers multiple independent subsystems, decompose first.
- For existing codebases, explore structure before proposing changes.

**After approval:** Proceed to Stage 2 (Plan).

---

## Stage 2: Write the Implementation Plan

**Trigger:** After user approves the spec from Stage 1.

**Announce:** "I'm writing the implementation plan now."

**Save plan to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`

**Every plan must include:**
- Goal: one sentence describing what this builds
- Architecture: 2-3 sentences about the approach
- Tech stack: key technologies
- File map: which files get created or modified and why

**Task granularity — each task is 2-5 minutes:**
- Write the failing test (step)
- Run it to confirm it fails (step)
- Write minimal code to pass (step)
- Run tests to confirm pass (step)
- Commit (step)

**No placeholders allowed:** Every step must contain actual code, exact file paths, and exact commands with expected output. Never write "TBD", "TODO", "add appropriate error handling", or "similar to Task N".

**After plan is written:** Offer two execution modes:
- Subagent-Driven (recommended): dispatch a fresh sub-agent per task with two-stage review
- Inline Execution: execute tasks in this session with batch checkpoints

---

## Stage 3: Implement with TDD

**The Iron Law:** NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.

If code was written before a test: delete it. Start over. No exceptions.

**Red-Green-Refactor cycle (mandatory for every task):**

1. **RED** — Write the failing test. Run it. Confirm it fails for the right reason.
2. **GREEN** — Write the minimal code to make the test pass. Run tests. Confirm all green.
3. **REFACTOR** — Clean up without changing behavior. Run tests again. Commit.

**What counts as a test:**
- Unit tests for functions and classes
- Integration tests for APIs and services
- End-to-end tests for user flows

**What does NOT count:**
- Console.log checks
- Manual browser verification
- "I can see it works"

**Commit after every green cycle.** Small, frequent commits. Never batch multiple features into one commit.

---

## Stage 4: Sub-Agent Task Dispatch (Subagent-Driven Mode)

When executing plans in subagent-driven mode, dispatch a fresh sub-agent per task.

**Core principle:** Fresh sub-agent per task = no context pollution, focused execution.

**Per-task process:**
1. Dispatch implementer sub-agent with exactly the context it needs (task description, relevant files, spec excerpt). Never pass your full session history.
2. Sub-agent implements, tests, and commits.
3. Dispatch spec-reviewer sub-agent: does the code match the spec?
4. If spec gaps found: implementer sub-agent fixes them.
5. Dispatch code-quality reviewer sub-agent: is the code production-grade?
6. If quality issues found: implementer sub-agent fixes them.
7. Mark task complete. Move to next task.

**Two-stage review is mandatory after every task.** Never skip review because "it's simple."

---

## Stage 5: Code Review

**Trigger:** After each major task, after completing a feature, before merging to main.

**How to request review:**
1. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
2. Dispatch code-reviewer with: what was implemented, the plan/requirements, BASE_SHA, HEAD_SHA
3. Act on feedback:
   - CRITICAL: fix immediately, do not proceed
   - IMPORTANT: fix before moving to next task
   - MINOR: note for later, can proceed

**Never:**
- Skip review because "it's simple"
- Ignore Critical issues
- Proceed with unfixed Important issues

---

## Stage 6: Verify Before Completion

**Before declaring any task done:**

1. Run the full test suite. All tests must pass.
2. Check that the specific behavior requested actually works end-to-end.
3. Confirm no regressions in existing functionality.
4. Review the original request — does the implementation match what was asked?

**Never say "done" based on:**
- The code looking correct
- Individual tests passing
- No error messages during implementation

Only declare done after running the full suite and manually verifying the behavior.

---

## Reference Files

For detailed guidance on specific stages, read:
- `references/karpathy-principles.md` — detailed examples and anti-patterns for all 4 Karpathy guardrails (read this when unsure how to apply a principle)
- `references/brainstorm-guide.md` — full brainstorming checklist and visual companion guide
- `references/tdd-patterns.md` — TDD anti-patterns, edge cases, and testing philosophy
- `references/plan-template.md` — complete plan document template with examples

---

## Quick Reference: What Triggers Each Stage

| Situation | Stage to Activate |
|---|---|
| User asks to build/modify anything | Stage 1: Brainstorm |
| Spec approved, ready to code | Stage 2: Write Plan |
| Starting a task from the plan | Stage 3: TDD Implementation |
| Plan has independent tasks | Stage 4: Sub-Agent Dispatch |
| Task complete or feature done | Stage 5: Code Review |
| About to say "done" | Stage 6: Verify |