superpowers

Superpowers — Mandatory Agent Workflows

Superpowers enforces a structured development workflow. Skills activate automatically when their trigger conditions are met. This is not optional guidance — it is mandatory workflow.

Philosophy

AI agents skip steps, guess, and declare "done" without verifying. Superpowers blocks this by making workflow stages explicit and enforced.

The Basic Workflow

Order	Skill	When It Activates
1	brainstorming	Before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
2	using-git-worktrees	After design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
3	writing-plans	With approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
4	subagent-driven-development or executing-plans	With plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
5	test-driven-development	During implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
6	requesting-code-review	Between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
7	finishing-a-development-branch	When tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

The agent checks for relevant skills before any task. These are mandatory workflows, not suggestions.

Skill Library

Testing

• test-driven-development — RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging

• systematic-debugging — 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
• verification-before-completion — Ensure it's actually fixed

Collaboration

• brainstorming — Socratic design refinement
• writing-plans — Detailed implementation plans
• executing-plans — Batch execution with checkpoints
• dispatching-parallel-agents — Concurrent subagent workflows
• requesting-code-review — Pre-review checklist
• receiving-code-review — Responding to feedback
• using-git-worktrees — Parallel development branches
• finishing-a-development-branch — Merge/PR decision workflow
• subagent-driven-development — Fast iteration with two-stage review (spec compliance, then code quality)

Meta

• writing-skills — Create new skills following best practices (includes testing methodology)
• using-superpowers — Introduction to the skills system

Test-Driven Development (Mandatory)

RED: Write failing test → Watch it fail
GREEN: Write minimal code → Watch it pass
REFACTOR: Improve while staying green → Commit

Code written before tests is deleted. No exceptions.

Brainstorming Protocol

When given a vague request:

1. Ask clarifying questions
2. Explore 2-3 alternative approaches
3. Present design in sections
4. Wait for explicit approval before proceeding

Plan Format

Every task in a plan must include:

- task: "Specific action"
  file: "exact/path/to/file.ext"
  code: "Complete implementation"
  verify: "How to confirm it works"
  estimate: "2-5 minutes"

Code Review Severity

Level	Action
Critical	Blocks progress. Must fix before continuing.
Warning	Should fix. Note and continue.
Info	Noted for later. No action required.

Subagent Development

Two-stage review for every task:

1. Spec compliance — Does it match the plan?
2. Code quality — Is it clean, tested, and maintainable?

Both must pass. Fresh subagent per task prevents context pollution.

Git Worktrees

Each feature gets an isolated workspace:

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

Clean separation, parallel development, easy cleanup.

Using Superpowers

Superpowers skills activate when their trigger conditions are detected:

• "Create a feature" → brainstorming → writing-plans → executing-plans
• "Fix this bug" → systematic-debugging → verification-before-completion
• "Review this PR" → requesting-code-review

No manual skill selection. The framework detects and enforces.