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.

From the README: “The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.”

The Complete Workflow

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

Phase 1: Brainstorming

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

What Happens

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

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.

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

1. Explore Project Context

   Check files, docs, and recent commits to understand the current state.

2. 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
3. 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
4. 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
5. Write Design Doc

   Save validated design to docs/plans/YYYY-MM-DD-<topic>-design.md and commit it.

6. Transition to Implementation

   Invoke the writing-plans skill to create the implementation plan.

Why This Matters

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

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.

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.

1. 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
2. Safety Verification

   For project-local directories, verify they’re in .gitignore.

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

   git check-ignore -q .worktrees
   

   If NOT ignored: Add to .gitignore, commit, then proceed.

3. Create Worktree

   git worktree add .worktrees/feature-name -b feature/feature-name
   cd .worktrees/feature-name
   
4. 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
5. Verify Clean Baseline

   Run tests to ensure worktree starts clean. If tests fail, report and ask whether to proceed.

Why Worktrees?

Isolation

Work on features without affecting your main workspace

Parallel Development

Multiple branches can be active simultaneously

Clean State

Each worktree starts from a known-good baseline

Easy Cleanup

Remove worktrees without affecting the main repo

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:

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.

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:

# [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:

Example Task Structure

### 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

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

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"

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:

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

The Process

1. Read Plan & Create Todos

   Extract all tasks with full text and create TodoWrite items for tracking.

2. Dispatch Implementer Subagent

   For each task, launch a fresh subagent with:

   • Full task text and context
   • Relevant portions of the plan
   • Project background
3. Implementer Works

   The subagent:

   • Asks clarifying questions before starting
   • Implements following TDD
   • Self-reviews the work
   • Runs tests and commits
4. 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
5. 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

6. Mark Complete & Continue

   Mark the task complete and move to the next one.

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.

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:

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.

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

1. RED - Write Failing Test

   Write one minimal test showing what should happen.

   Requirements:

   • One behavior
   • Clear name
   • Real code (no mocks unless unavoidable)
2. 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.

3. GREEN - Minimal Code

   Write simplest code to pass the test.

   Don’t add features, refactor other code, or “improve” beyond the test.

4. Verify GREEN - Watch It Pass

   MANDATORY.

   Confirm:

   • Test passes
   • Other tests still pass
   • Output pristine (no errors, warnings)
5. REFACTOR - Clean Up

   After green only:

   • Remove duplication
   • Improve names
   • Extract helpers

   Keep tests green. Don’t add behavior.

Why Order Matters

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

“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.

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

1. Get Git SHAs

   BASE_SHA=$(git rev-parse HEAD~1)
   HEAD_SHA=$(git rev-parse HEAD)
   
2. Dispatch Code Reviewer Subagent

   Provide:

   • What was implemented
   • Plan or requirements
   • Base and HEAD commit SHAs
   • Brief description
3. 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)

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:

Core principle: Verify tests → Present options → Execute choice → Clean up

The Process

1. Verify Tests

   Run the full test suite. If tests fail, cannot proceed.

2. Determine Base Branch

   Figure out which branch this split from (usually main or master).

3. 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
4. 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

Real-World Example

Let’s walk through building an authentication feature:

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!

Key Takeaways

Design Before Code

Brainstorming ensures you build the right thing before investing time in code.

Isolation

Git worktrees provide safe, isolated workspaces for each feature.

Detailed Plans

Bite-sized tasks with exact instructions enable autonomous execution.

Fresh Context

Subagents get clean context per task, avoiding pollution and confusion.

Test First, Always

TDD ensures code does what it should and proves tests actually work.

Two-Stage Review

Spec compliance first, then code quality - catches issues early.

Next Steps

Philosophy

Learn the four core principles that drive this workflow

Skills Reference

Explore individual skills in depth