The Superpowers Workflow

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:

Explore Project Context

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

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

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

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

Write Design Doc

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

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.

Directory Selection

Follow priority order:

Check existing .worktrees/ or worktrees/ directories
Check CLAUDE.md for preferences
Ask user to choose between project-local or global location

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.

Create Worktree

git worktree add .worktrees/feature-name -b feature/feature-name
cd .worktrees/feature-name

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

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 failsRun: 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 passesRun: pytest tests/path/test.py::test_name -v Expected: PASSStep 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:

Subagent-Driven (this session) - Dispatch fresh subagent per task, review between tasks, fast iteration
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

Read Plan & Create Todos

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

Dispatch Implementer Subagent

For each task, launch a fresh subagent with:

Full task text and context
Relevant portions of the plan
Project background

Implementer Works

The subagent:

Asks clarifying questions before starting
Implements following TDD
Self-reviews the work
Runs tests and commits

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

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

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

RED - Write Failing Test

Write one minimal test showing what should happen.Requirements:

One behavior
Clear name
Real code (no mocks unless unavoidable)

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.

GREEN - Minimal Code

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

Verify GREEN - Watch It Pass

MANDATORY.Confirm:

Test passes
Other tests still pass
Output pristine (no errors, warnings)

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

Get Git SHAs

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

Dispatch Code Reviewer Subagent

Provide:

What was implemented
Plan or requirements
Base and HEAD commit SHAs
Brief description

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

Verify Tests

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

Determine Base Branch

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

Present Options

Exactly 4 options:

Merge back to base branch locally
Push and create a Pull Request
Keep the branch as-is (I’ll handle it later)
Discard this work

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

Get Started

Installation

Core Concepts

Skills Library

​Overview

​The Complete Workflow

​Phase 1: Brainstorming

​What Happens

​Why This Matters

​Phase 2: Using Git Worktrees

​What Happens

​Why Worktrees?

Isolation

Parallel Development

Clean State

Easy Cleanup

​Phase 3: Writing Plans

​What Happens

​Task Granularity

​Plan Structure

​Execution Handoff

​Phase 4: Implementation

​Option A: Subagent-Driven Development

​The Process

​Option B: Executing Plans

​Phase 5: Test-Driven Development

​The Iron Law

​RED-GREEN-REFACTOR Cycle

​Why Order Matters

​Phase 6: Code Review

​The Review Process

​Phase 7: Finishing the Branch

​The Process

​Real-World Example

​Key Takeaways

Design Before Code

Isolation

Detailed Plans

Fresh Context

Test First, Always

Two-Stage Review

​Next Steps

Philosophy

Skills Reference

Build docs developers (and LLMs) love

Overview

The Complete Workflow

Phase 1: Brainstorming

What Happens

Why This Matters

Phase 2: Using Git Worktrees

What Happens

Why Worktrees?

Phase 3: Writing Plans

What Happens

Task Granularity

Plan Structure

Execution Handoff

Phase 4: Implementation

Option A: Subagent-Driven Development

The Process

Option B: Executing Plans

Phase 5: Test-Driven Development

The Iron Law

RED-GREEN-REFACTOR Cycle

Why Order Matters

Phase 6: Code Review

The Review Process

Phase 7: Finishing the Branch

The Process

Real-World Example

Key Takeaways

Next Steps