Superpowers Bundle¶

Overview¶

The Superpowers Bundle provides a rigorous, TDD-driven development workflow for Amplifier. It enforces discipline through structured modes, specialized agents, and a clear methodology that moves from design through implementation to verified completion.

Core Philosophy: - Test-Driven Development is non-negotiable - RED-GREEN-REFACTOR on every task - Systematic over ad-hoc - Structured phases, not improvisation - Evidence over claims - Every assertion must be verified with actual output - Complexity reduction as primary goal - Simpler is always better - Planning before implementation - Think first, build second - Human checkpoints at critical points - You stay in control

The bundle is built around a single guiding principle: the Gate Function. Before any task is considered complete, it must pass through IDENTIFY-RUN-READ-VERIFY. Identify what to test, run it, read the output, and verify it matches expectations. No shortcuts.

Modes¶

Superpowers organizes work into focused modes, each activated with the /mode command. Each mode constrains behavior to a specific phase of development, preventing scope creep and ensuring thoroughness.

Brainstorm Mode¶

Collaborative design refinement where you and Amplifier explore the problem space together. This mode focuses on understanding requirements, considering alternatives, and arriving at a validated design.

What happens in brainstorm mode: - Problem decomposition and analysis - Design alternative exploration - Tradeoff discussion - Constraint identification - Design validation with you before proceeding

When to use: Starting a new feature, exploring a refactoring approach, or making architectural decisions.

> /brainstorm

"I need a caching layer for our API responses. 
 Some endpoints change rarely, others change per-request."

Amplifier explores: cache strategies, TTL policies, 
invalidation approaches, storage options...

You validate the design before moving to planning.

Write Plan Mode¶

Takes a validated design and breaks it into bite-sized implementation tasks. Each task should take roughly 2-5 minutes and be independently testable.

What happens in write-plan mode: - Design decomposition into ordered tasks - Test specification for each task - Dependency identification between tasks - Acceptance criteria definition - Task ordering for incremental progress

When to use: After brainstorm produces a validated design, before starting implementation.

> /write-plan

Amplifier produces:
  Task 1: Create CacheEntry dataclass with TTL field (test: unit)
  Task 2: Implement LRUCache with max_size (test: unit)
  Task 3: Add TTL expiration logic (test: unit)
  Task 4: Create cache middleware for API routes (test: integration)
  Task 5: Wire cache into endpoint handlers (test: integration)

Execute Plan Mode¶

Systematic task execution following strict TDD. Each task goes through RED-GREEN-REFACTOR: write a failing test first, make it pass with minimal code, then clean up.

What happens in execute-plan mode: - Pick next task from plan - Write failing test (RED) - Implement minimal code to pass (GREEN) - Refactor for clarity (REFACTOR) - Verify with Gate Function (IDENTIFY-RUN-READ-VERIFY) - Move to next task

When to use: After write-plan produces a task list.

> /execute-plan

Task 1: Create CacheEntry dataclass
  RED:    Write test_cache_entry_stores_value_and_ttl -> FAIL
  GREEN:  Implement CacheEntry dataclass -> PASS
  REFACTOR: Clean up, add docstring
  VERIFY: Run tests, read output, confirm pass

  -> Task 1 complete. Moving to Task 2...

Debug Mode¶

Root-cause investigation before fixes. Debug mode prevents the common mistake of guessing at fixes. Instead, it follows a systematic investigation process to understand the problem before changing any code.

What happens in debug mode: - Reproduce the failure - Gather evidence (logs, stack traces, test output) - Form hypotheses - Test hypotheses systematically - Identify root cause with evidence - Only then propose a fix

When to use: Test failures, unexpected behavior, runtime errors.

> /debug

"test_cache_expiration is failing intermittently"

Amplifier investigates:
  1. Reproduces failure
  2. Examines timing-dependent code
  3. Identifies race condition in TTL check
  4. Proposes fix with evidence

Verify Mode¶

Evidence-based completion verification. Nothing is "done" until verify mode confirms it with actual test output and evidence.

What happens in verify mode: - Run all relevant tests - Read actual output (not assumed output) - Check coverage for new code - Verify acceptance criteria from the plan - Confirm no regressions

When to use: After completing implementation tasks, before finishing.

> /verify

Amplifier runs:
  1. Full test suite -> 47 passed, 0 failed
  2. Coverage check -> 94% on new code
  3. Acceptance criteria -> all 5 criteria met
  4. Regression check -> no existing tests broken

  VERIFIED: All evidence confirms completion.

Finish Mode¶

Clean completion: merge, PR creation, or cleanup. This mode handles the final handoff.

What happens in finish mode: - Final verification pass - Code cleanup and formatting - Commit with descriptive message - PR creation or merge - Summary of what was accomplished

When to use: After verify confirms everything is complete.

Agents¶

The Superpowers Bundle includes five specialized agents, each focused on a specific responsibility.

Implementer¶

The workhorse agent. Takes a single task from an implementation plan and executes it with strict TDD compliance. Requires a clear specification -- it will stop and ask if the spec is incomplete.

Input: Complete task specification with file paths, interfaces, and acceptance criteria.

Process: 1. Write failing test (RED) 2. Implement minimal passing code (GREEN) 3. Refactor for clarity (REFACTOR) 4. Run Gate Function to verify

Output: Implemented code with passing tests.

> Implement Task 3: Add TTL expiration logic

Agent: superpowers:implementer

The agent:
  1. Reads task spec for TTL expiration
  2. Writes test_expired_entries_are_evicted -> FAIL
  3. Adds expiration check to CacheEntry.is_valid() -> PASS
  4. Refactors for clarity
  5. Runs all cache tests -> all pass

Spec Reviewer¶

Verifies that an implementation matches its specification exactly. This is not a general code review -- it checks spec compliance only.

Input: Implementation code and the original specification.

Checks: - All specified interfaces are implemented - All acceptance criteria are met - No specified behavior is missing - Edge cases from the spec are handled

> Review the cache implementation against the spec

Agent: superpowers:spec-reviewer

Result: PASS - All 5 acceptance criteria met.
  - CacheEntry stores value and TTL
  - LRUCache respects max_size
  - Expired entries are evicted on access
  - Cache middleware intercepts GET requests
  - TTL is configurable per endpoint

Code Quality Reviewer¶

Assesses code quality independent of spec compliance. A separate concern from whether the code does what was specified.

Input: Implementation code to review.

Checks: - Readability and clarity - Naming conventions - Complexity (cyclomatic, cognitive) - Test quality and coverage - Error handling patterns - Adherence to project conventions

> Review code quality of the cache module

Agent: superpowers:code-quality-reviewer

Result: PASS with suggestions.
  Quality: Good
  Suggestions:
  - Extract magic number 300 into DEFAULT_TTL constant
  - Add type hints to cache_middleware return value

Brainstormer¶

Writes a validated design as a formal document. This agent runs after you and Amplifier have completed a brainstorm-mode conversation and agreed on a design.

Input: Validated design from brainstorm conversation.

Output: Structured design document with problem statement, approach, tradeoffs, and decisions.

Plan Writer¶

Formats a validated plan as a formal document. Runs after write-plan-mode conversation produces agreed-upon tasks.

Input: Validated task breakdown from write-plan conversation.

Output: Structured implementation plan with ordered tasks, test specifications, and acceptance criteria.

The Two-Stage Review Pattern¶

After each implementation task, Superpowers enforces a two-stage review. Both stages must pass, and order matters.

Task completed by implementer
         |
         v
  Stage 1: Spec Review (superpowers:spec-reviewer)
    "Does it match the specification?"
         |
         | PASS
         v
  Stage 2: Quality Review (superpowers:code-quality-reviewer)
    "Is the code well-written?"
         |
         | PASS
         v
  Task accepted

Why this order? There is no point reviewing code quality if the implementation does not match the spec. Spec compliance comes first. Quality review comes second.

Both must pass. If either stage fails, the task goes back to the implementer for revision before re-review.

Two-Track UX¶

Superpowers offers two ways to drive the workflow: automated or manual.

Track 1: Autopilot (Recipe-Driven)¶

The Full Development Cycle Recipe drives the entire pipeline automatically with approval gates at critical points:

Recipe: superpowers:recipes/superpowers-full-development-cycle.yaml

Flow:

Brainstorm -> [approval gate] -> Write Plan -> [approval gate] 
  -> Execute Tasks -> Spec Review -> Quality Review 
  -> [approval gate] -> Verify -> Finish

Approval gates pause execution and ask for your input before proceeding. You review the design before planning starts, review the plan before implementation starts, and review the results before finishing.

When to use: Full feature development where you want the pipeline managed for you.

> Run the full development cycle recipe for the caching feature

Recipe executes:
  1. Brainstorm phase -> produces design -> waits for approval
  2. You approve the design
  3. Planning phase -> produces task list -> waits for approval
  4. You approve the plan
  5. Execution phase -> implements all tasks with TDD
  6. Review phase -> spec + quality reviews
  7. Verification phase -> waits for approval
  8. You approve -> finish

Track 2: Manual (Mode-by-Mode)¶

Activate individual modes as needed. Full control over when to switch phases and what to skip.

When to use: Bug fixes, small changes, or when you want to use specific phases without the full pipeline.

> /debug
  [investigate the issue]

> /verify
  [confirm the fix works]

> /finish
  [commit and clean up]

Methodology Calibration¶

Not every change needs the full ceremony. Match the methodology to the scope of work:

New Feature (Multi-File)¶

Full cycle. Design matters, planning prevents thrashing, TDD catches edge cases.

/brainstorm -> /write-plan -> /execute-plan -> /verify -> /finish

Bug Fix¶

Investigate first, verify the fix, ship it.

/debug -> /verify -> /finish

Small Change (Under 20 Lines)¶

Make the change directly, then verify it works.

[make change] -> /verify

Refactoring¶

Design the target structure, execute systematically, verify nothing broke.

/brainstorm -> /execute-plan -> /verify -> /finish

Exploratory Work¶

When you are not sure what you are building yet, brainstorm without committing to implementation.

/brainstorm -> [decide next steps based on findings]

The Gate Function¶

The Gate Function is Superpowers' core verification mechanism. It applies everywhere: after implementing a task, after fixing a bug, after any change that needs confirmation.

IDENTIFY  ->  What specific thing needs to be verified?
RUN       ->  Execute the test/command that produces evidence
READ      ->  Read the actual output (do not assume)
VERIFY    ->  Does the output match expectations?

Key rule: The READ step must read actual output. Never assume a test passed because the code looks correct. Run it, read it, confirm it.

Getting Started¶

Quick Start¶

1. Ensure the Superpowers bundle is loaded in your configuration
2. Start with /brainstorm for a new feature or /debug for a bug
3. Follow the mode progression naturally
4. Let the Gate Function verify each step

First Time Walkthrough¶

Try the full cycle on a small feature:

1. /brainstorm - Design a simple utility function
2. /write-plan - Break it into 2-3 tasks
3. /execute-plan - Implement with TDD
4. /verify - Confirm everything passes
5. /finish - Commit the result

This gives you a feel for the rhythm before applying it to larger work.

Configuration¶

The Superpowers bundle is loaded via your bundle configuration:

# .amplifier/config.yaml
bundles:
  superpowers:
    enabled: true

The Full Development Cycle Recipe is available at:

superpowers:recipes/superpowers-full-development-cycle.yaml

Best Practices¶

Trust the Process¶

The mode progression exists for a reason. Jumping from brainstorm straight to implementation skips the planning that prevents rework.

Keep Tasks Small¶

Write-plan should produce tasks that take 2-5 minutes each. If a task feels large, break it down further. Small tasks are easier to test, review, and verify.

Read the Output¶

The most common failure mode is assuming tests pass. The Gate Function's READ step exists to prevent this. Always read actual test output.

Use the Right Track¶

Do not force the full recipe on a one-line bug fix. Do not skip planning on a multi-file feature. Match the methodology to the work.

Let Reviews Catch Issues¶

The two-stage review pattern exists to separate concerns. Do not conflate spec compliance with code quality. They are different questions answered by different reviewers.

Common Patterns¶

Pattern: Feature Development¶

/brainstorm
  -> Explore problem space
  -> Validate design with user

/write-plan
  -> Decompose into tasks
  -> Define tests for each task

/execute-plan
  -> RED-GREEN-REFACTOR each task
  -> Two-stage review after each

/verify
  -> Run full test suite
  -> Check all acceptance criteria

/finish
  -> Commit and PR

Pattern: Bug Fix with Regression Test¶

/debug
  -> Reproduce failure
  -> Identify root cause
  -> Write failing test that captures the bug
  -> Fix the code (test now passes)

/verify
  -> Confirm fix
  -> Confirm no regressions

/finish
  -> Commit with descriptive message

Pattern: Refactoring with Safety Net¶

/brainstorm
  -> Define target structure
  -> Identify what changes

/execute-plan
  -> Move code incrementally
  -> Run tests after each move
  -> Never break existing tests

/verify
  -> All original tests still pass
  -> New structure matches design

/finish
  -> Clean commit history

Pattern: Design Exploration Only¶

/brainstorm
  -> Explore multiple approaches
  -> Document tradeoffs
  -> Produce design document (via brainstormer agent)
  -> Stop here -- implementation is a separate decision

Integration¶

With Foundation Bundle¶

Superpowers builds on Foundation's tools and agents. The implementer agent uses Foundation's write_file, edit_file, bash, and grep tools. The debug mode leverages Foundation's bug-hunter patterns.

With Recipes Bundle¶

The Full Development Cycle Recipe uses the Recipes infrastructure for staged execution and approval gates. Understanding Recipes helps you customize the pipeline.

With Python Check Tool¶

When working on Python projects, the python_check tool integrates naturally with Superpowers' verify mode. Type checking and linting become part of the Gate Function's evidence.

Troubleshooting¶

Implementer Refuses to Start¶

Problem: "Specification incomplete, cannot proceed"

Cause: The implementer requires complete specs with file paths,
       interfaces, and acceptance criteria.

Solution: Run /write-plan first to produce proper task specs.
          Or provide the missing details manually.

Reviews Keep Failing¶

Problem: Two-stage review rejects implementation repeatedly

Cause: Usually a mismatch between spec and implementation.

Solution:
  1. Re-read the original spec carefully
  2. Check if the spec needs updating (design changed)
  3. Ensure all acceptance criteria are addressed

Full Recipe Feels Heavy¶

Problem: The development cycle recipe is too much process

Cause: The recipe is designed for multi-file features.

Solution: Use manual mode for smaller work.
  - Bug fix: /debug -> /verify -> /finish
  - Small change: make change -> /verify
  - Skip the recipe entirely for trivial changes

Tests Not Running in Execute Mode¶

Problem: TDD cycle skips the RED phase

Cause: Test infrastructure may not be configured.

Solution:
  1. Ensure test runner is available (pytest, jest, etc.)
  2. Check that test directory structure exists
  3. Verify test configuration in project settings

What's Next?¶

• Learn about Foundation Bundle for the base tools Superpowers builds on
• Explore Recipes Bundle for understanding the automation pipeline
• Check out Design Intelligence Bundle for UI-focused workflows

The Superpowers Bundle transforms ad-hoc development into a disciplined, evidence-based process. Whether you use the full automated pipeline or individual modes, the core principles remain: plan before building, test before claiming success, and verify with evidence.