> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# The Superpowers Workflow

> A complete walkthrough of the systematic development process enforced by Superpowers

## Overview

Superpowers enforces a complete software development workflow through composable skills. The agent checks for relevant skills before any task and **mandatory workflows replace ad-hoc development**.

<Info>
  From the README: "The agent checks for relevant skills before any task. Mandatory workflows, not suggestions."
</Info>

## The Complete Workflow

Here's the end-to-end process from idea to deployment:

```mermaid theme={null}
graph TB
    A[💡 Idea] --> B[1. Brainstorming]
    B --> C[2. Git Worktrees]
    C --> D[3. Writing Plans]
    D --> E{Execution Choice}
    E -->|Same Session| F[4a. Subagent-Driven]
    E -->|New Session| G[4b. Executing Plans]
    F --> H[5. TDD]
    G --> H
    H --> I[6. Code Review]
    I --> J[7. Finishing Branch]
    
    style B fill:#e1f5ff
    style C fill:#fff4e1
    style D fill:#ffe1f5
    style F fill:#e1ffe1
    style G fill:#e1ffe1
    style H fill:#ffe1e1
    style I fill:#f5e1ff
    style J fill:#e1fff5
```

## Phase 1: Brainstorming

**Skill:** `brainstorming`\
**Activates:** Before writing any code, creating features, or modifying behavior

### What Happens

From `skills/brainstorming/SKILL.md:14-16`:

<Warning>
  Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.
</Warning>

The agent doesn't jump straight into coding. Instead:

<Steps>
  <Step title="Explore Project Context">
    Check files, docs, and recent commits to understand the current state.
  </Step>

  <Step title="Ask Clarifying Questions">
    One question at a time to understand purpose, constraints, and success criteria.

    From `skills/brainstorming/SKILL.md:60-64`:

    * Prefer multiple choice questions when possible
    * Only one question per message
    * Focus on understanding: purpose, constraints, success criteria
  </Step>

  <Step title="Propose 2-3 Approaches">
    Present different options with trade-offs and a recommendation.

    From `skills/brainstorming/SKILL.md:67-69`:

    * Lead with your recommended option
    * Explain trade-offs
    * Present reasoning
  </Step>

  <Step title="Present Design">
    Once the agent understands what to build, it presents the design in digestible sections.

    From `skills/brainstorming/SKILL.md:71-76`:

    * Scale each section to complexity (few sentences if straightforward, 200-300 words if nuanced)
    * Ask after each section whether it looks right
    * Cover: architecture, components, data flow, error handling, testing
  </Step>

  <Step title="Write Design Doc">
    Save validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit it.
  </Step>

  <Step title="Transition to Implementation">
    Invoke the `writing-plans` skill to create the implementation plan.
  </Step>
</Steps>

### Why This Matters

From `skills/brainstorming/SKILL.md:19-20`:

<Note>
  Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work.
</Note>

## Phase 2: Using Git Worktrees

**Skill:** `using-git-worktrees`\
**Activates:** After design approval, before executing implementation plans

### What Happens

Git worktrees create isolated workspaces sharing the same repository. This allows work on the new feature without disturbing your current workspace.

<Steps>
  <Step title="Directory Selection">
    Follow priority order:

    1. Check existing `.worktrees/` or `worktrees/` directories
    2. Check `CLAUDE.md` for preferences
    3. Ask user to choose between project-local or global location
  </Step>

  <Step title="Safety Verification">
    For project-local directories, verify they're in `.gitignore`.

    From `skills/using-git-worktrees/SKILL.md:55-68`:

    ```bash theme={null}
    git check-ignore -q .worktrees
    ```

    If NOT ignored: Add to `.gitignore`, commit, then proceed.
  </Step>

  <Step title="Create Worktree">
    ```bash theme={null}
    git worktree add .worktrees/feature-name -b feature/feature-name
    cd .worktrees/feature-name
    ```
  </Step>

  <Step title="Run Project Setup">
    Auto-detect and run appropriate setup:

    * Node.js: `npm install`
    * Rust: `cargo build`
    * Python: `pip install -r requirements.txt`
    * Go: `go mod download`
  </Step>

  <Step title="Verify Clean Baseline">
    Run tests to ensure worktree starts clean. If tests fail, report and ask whether to proceed.
  </Step>
</Steps>

### Why Worktrees?

<CardGroup cols={2}>
  <Card title="Isolation" icon="shield">
    Work on features without affecting your main workspace
  </Card>

  <Card title="Parallel Development" icon="arrows-split-up-and-left">
    Multiple branches can be active simultaneously
  </Card>

  <Card title="Clean State" icon="broom">
    Each worktree starts from a known-good baseline
  </Card>

  <Card title="Easy Cleanup" icon="trash">
    Remove worktrees without affecting the main repo
  </Card>
</CardGroup>

## Phase 3: Writing Plans

**Skill:** `writing-plans`\
**Activates:** After brainstorming, with approved design, before touching code

### What Happens

The agent creates a comprehensive implementation plan with bite-sized tasks.

From `skills/writing-plans/SKILL.md:10-12`:

<Note>
  Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it.
</Note>

### Task Granularity

From `skills/writing-plans/SKILL.md:20-27`, each step is one action (2-5 minutes):

* "Write the failing test" - step
* "Run it to make sure it fails" - step
* "Implement the minimal code to make the test pass" - step
* "Run the tests and make sure they pass" - step
* "Commit" - step

### Plan Structure

Every plan starts with a header:

```markdown theme={null}
# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans 
> to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]
```

Then each task includes:

<Accordion title="Example Task Structure">
  ````markdown theme={null}
  ### Task N: [Component Name]

  **Files:**
  - Create: `exact/path/to/file.py`
  - Modify: `exact/path/to/existing.py:123-145`
  - Test: `tests/exact/path/to/test.py`

  **Step 1: Write the failing test**

  ```python
  def test_specific_behavior():
      result = function(input)
      assert result == expected
  ````

  **Step 2: Run test to verify it fails**

  Run: `pytest tests/path/test.py::test_name -v`
  Expected: FAIL with "function not defined"

  **Step 3: Write minimal implementation**

  ```python theme={null}
  def function(input):
      return expected
  ```

  **Step 4: Run test to verify it passes**

  Run: `pytest tests/path/test.py::test_name -v`
  Expected: PASS

  **Step 5: Commit**

  ```bash theme={null}
  git add tests/path/test.py src/path/file.py
  git commit -m "feat: add specific feature"
  ```
</Accordion>

### Execution Handoff

After saving the plan, the agent offers two execution options:

1. **Subagent-Driven (this session)** - Dispatch fresh subagent per task, review between tasks, fast iteration
2. **Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints

## Phase 4: Implementation

### Option A: Subagent-Driven Development

**Skill:** `subagent-driven-development`\
**When:** Executing in the current session with independent tasks

From `skills/subagent-driven-development/SKILL.md:10`:

<Info>
  **Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
</Info>

#### The Process

<Steps>
  <Step title="Read Plan & Create Todos">
    Extract all tasks with full text and create TodoWrite items for tracking.
  </Step>

  <Step title="Dispatch Implementer Subagent">
    For each task, launch a fresh subagent with:

    * Full task text and context
    * Relevant portions of the plan
    * Project background
  </Step>

  <Step title="Implementer Works">
    The subagent:

    * Asks clarifying questions before starting
    * Implements following TDD
    * Self-reviews the work
    * Runs tests and commits
  </Step>

  <Step title="Spec Compliance Review">
    Dispatch a **spec reviewer** subagent to verify:

    * All requirements from the task are met
    * Nothing extra was added (YAGNI)

    From `skills/subagent-driven-development/SKILL.md:190`:

    * Issues found → Implementer fixes → Re-review
  </Step>

  <Step title="Code Quality Review">
    Only after spec compliance passes, dispatch a **code quality reviewer** to check:

    * Code quality and structure
    * Test coverage
    * Edge cases

    Issues found → Implementer fixes → Re-review
  </Step>

  <Step title="Mark Complete & Continue">
    Mark the task complete and move to the next one.
  </Step>
</Steps>

<Warning>
  From `skills/subagent-driven-development/SKILL.md:212`: **Start code quality review before spec compliance is ✅** (wrong order). Never skip the two-stage review process.
</Warning>

### Option B: Executing Plans

**Skill:** `executing-plans`\
**When:** Executing in a separate parallel session with checkpoint-based batches

Batch execution with human checkpoints every 3 tasks. Useful for:

* Tightly coupled tasks that need continuous context
* When you want manual oversight between batches

## Phase 5: Test-Driven Development

**Skill:** `test-driven-development`\
**Activates:** During implementation of any feature or bugfix

From `skills/test-driven-development/SKILL.md:12-14`:

<Warning>
  **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.

  **Violating the letter of the rules is violating the spirit of the rules.**
</Warning>

### The Iron Law

From `skills/test-driven-development/SKILL.md:33-45`:

```
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
```

Write code before the test? Delete it. Start over.

**No exceptions:**

* Don't keep it as "reference"
* Don't "adapt" it while writing tests
* Don't look at it
* Delete means delete

### RED-GREEN-REFACTOR Cycle

<Steps>
  <Step title="RED - Write Failing Test">
    Write one minimal test showing what should happen.

    **Requirements:**

    * One behavior
    * Clear name
    * Real code (no mocks unless unavoidable)
  </Step>

  <Step title="Verify RED - Watch It Fail">
    **MANDATORY. Never skip.**

    Run the test and confirm:

    * Test fails (not errors)
    * Failure message is expected
    * Fails because feature missing (not typos)

    Test passes? You're testing existing behavior. Fix test.
  </Step>

  <Step title="GREEN - Minimal Code">
    Write simplest code to pass the test.

    Don't add features, refactor other code, or "improve" beyond the test.
  </Step>

  <Step title="Verify GREEN - Watch It Pass">
    **MANDATORY.**

    Confirm:

    * Test passes
    * Other tests still pass
    * Output pristine (no errors, warnings)
  </Step>

  <Step title="REFACTOR - Clean Up">
    After green only:

    * Remove duplication
    * Improve names
    * Extract helpers

    Keep tests green. Don't add behavior.
  </Step>
</Steps>

### Why Order Matters

From `skills/test-driven-development/SKILL.md:247-252`:

<Note>
  **"Tests after achieve the same goals - it's spirit not ritual"**

  No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"

  Tests-after are biased by your implementation. You test what you built, not what's required.
</Note>

## Phase 6: Code Review

**Skill:** `requesting-code-review`\
**Activates:** After completing tasks, before merging

From `skills/requesting-code-review/SKILL.md:11-17`, review is **mandatory**:

* After each task in subagent-driven development
* After completing major feature
* Before merge to main

### The Review Process

<Steps>
  <Step title="Get Git SHAs">
    ```bash theme={null}
    BASE_SHA=$(git rev-parse HEAD~1)
    HEAD_SHA=$(git rev-parse HEAD)
    ```
  </Step>

  <Step title="Dispatch Code Reviewer Subagent">
    Provide:

    * What was implemented
    * Plan or requirements
    * Base and HEAD commit SHAs
    * Brief description
  </Step>

  <Step title="Act on Feedback">
    * Fix **Critical** issues immediately
    * Fix **Important** issues before proceeding
    * Note **Minor** issues for later
    * Push back if reviewer is wrong (with reasoning)
  </Step>
</Steps>

## Phase 7: Finishing the Branch

**Skill:** `finishing-a-development-branch`\
**Activates:** When implementation is complete and all tests pass

From `skills/finishing-a-development-branch/SKILL.md:12`:

<Info>
  **Core principle:** Verify tests → Present options → Execute choice → Clean up
</Info>

### The Process

<Steps>
  <Step title="Verify Tests">
    Run the full test suite. If tests fail, cannot proceed.
  </Step>

  <Step title="Determine Base Branch">
    Figure out which branch this split from (usually `main` or `master`).
  </Step>

  <Step title="Present Options">
    Exactly 4 options:

    1. Merge back to base branch locally
    2. Push and create a Pull Request
    3. Keep the branch as-is (I'll handle it later)
    4. Discard this work
  </Step>

  <Step title="Execute Choice">
    Based on user selection:

    * **Option 1:** Merge locally, verify tests, delete branch, cleanup worktree
    * **Option 2:** Push, create PR with summary, cleanup worktree
    * **Option 3:** Keep everything as-is
    * **Option 4:** Confirm with typed "discard", then delete branch and worktree
  </Step>
</Steps>

## Real-World Example

Let's walk through building an authentication feature:

<Accordion title="Complete Workflow Example">
  **You:** "Help me add OAuth authentication to the app"

  **Phase 1: Brainstorming**

  * Agent: "I'm using the brainstorming skill to refine this design."
  * Explores current auth implementation
  * Asks: "Which OAuth providers do you want to support?"
  * You: "Google and GitHub"
  * Proposes 3 approaches: custom implementation, Passport.js, or Auth0
  * Recommends Passport.js with reasoning
  * Presents design in sections covering:
    * OAuth flow architecture
    * Session management
    * Security considerations
    * Error handling
  * Saves `docs/plans/2026-03-09-oauth-auth-design.md`
  * Invokes writing-plans skill

  **Phase 2: Git Worktrees**

  * Agent: "I'm using the using-git-worktrees skill to set up an isolated workspace."
  * Checks for `.worktrees/` directory
  * Verifies it's in `.gitignore`
  * Creates: `git worktree add .worktrees/oauth-auth -b feature/oauth-auth`
  * Runs `npm install`
  * Verifies baseline: 47 tests passing
  * Reports: "Worktree ready at .worktrees/oauth-auth"

  **Phase 3: Writing Plans**

  * Agent: "I'm using the writing-plans skill to create the implementation plan."
  * Creates detailed plan with 8 tasks:
    * Task 1: Install dependencies (passport, passport-google, passport-github)
    * Task 2: OAuth configuration module
    * Task 3: Google strategy implementation
    * Task 4: GitHub strategy implementation
    * Task 5: Session management
    * Task 6: Protected route middleware
    * Task 7: Login/logout endpoints
    * Task 8: Integration tests
  * Saves `docs/plans/2026-03-09-oauth-auth.md`
  * Offers execution choice
  * You: "Use subagent-driven development"

  **Phase 4: Subagent-Driven Development**

  * Creates 8 TodoWrite items
  * **Task 1:** Dispatches implementer subagent
    * Implementer: "Should I pin passport to a specific version?"
    * You: "Yes, use latest stable"
    * Implementer: Adds dependencies, commits
    * Spec reviewer: ✅ Compliant
    * Code quality reviewer: ✅ Approved
    * Marks Task 1 complete
  * **Task 2:** Fresh implementer subagent
    * Implements OAuth config module with TDD
    * Spec reviewer: ❌ "Missing environment variable validation"
    * Implementer: Adds validation
    * Spec reviewer: ✅ Compliant
    * Code quality reviewer: ✅ Approved
    * Marks Task 2 complete
  * Continues through all 8 tasks...

  **Phase 5: TDD (within each task)**

  * RED: Write failing test for Google strategy
  * Verify RED: Test fails with "GoogleStrategy not defined"
  * GREEN: Implement minimal GoogleStrategy
  * Verify GREEN: Test passes, all other tests still pass
  * REFACTOR: Extract strategy factory
  * Commit

  **Phase 6: Code Review**

  * After each task: Subagent reviews against spec
  * After all tasks: Final review of entire implementation
  * Reviewer: "All requirements met, ready to merge"

  **Phase 7: Finishing Branch**

  * Agent: "I'm using the finishing-a-development-branch skill to complete this work."
  * Runs full test suite: 55 tests passing (8 new)
  * Presents 4 options
  * You: "Create a PR"
  * Pushes branch
  * Creates PR with summary:
    ```
    ## Summary
    - Added OAuth authentication via Passport.js
    - Supports Google and GitHub providers
    - Includes session management and protected routes

    ## Test Plan
    - ✅ 8 new integration tests
    - ✅ All existing tests still pass
    ```
  * Cleans up worktree
  * Done!
</Accordion>

## Key Takeaways

<CardGroup cols={2}>
  <Card title="Design Before Code" icon="pencil">
    Brainstorming ensures you build the right thing before investing time in code.
  </Card>

  <Card title="Isolation" icon="layer-group">
    Git worktrees provide safe, isolated workspaces for each feature.
  </Card>

  <Card title="Detailed Plans" icon="list-check">
    Bite-sized tasks with exact instructions enable autonomous execution.
  </Card>

  <Card title="Fresh Context" icon="sparkles">
    Subagents get clean context per task, avoiding pollution and confusion.
  </Card>

  <Card title="Test First, Always" icon="vial">
    TDD ensures code does what it should and proves tests actually work.
  </Card>

  <Card title="Two-Stage Review" icon="magnifying-glass">
    Spec compliance first, then code quality - catches issues early.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Philosophy" href="/concepts/philosophy" icon="lightbulb">
    Learn the four core principles that drive this workflow
  </Card>

  <Card title="Skills Reference" href="/skills/brainstorming" icon="book">
    Explore individual skills in depth
  </Card>
</CardGroup>