# Superpowers Plugin — The Actual Workflow Engine

The Superpowers plugin is not optional tooling — it's the primary workflow enforcement mechanism. It drives the day-to-day development cycle across all projects.

## What Superpowers Enforces

Superpowers provides a suite of skills that activate based on what you're doing. The AI assistant is required to invoke them — they're not suggestions.

### Brainstorming (before any creative work)

**Trigger:** Creating features, building components, adding functionality, or modifying behavior.

**What it does:**
1. Explores the current project context (files, docs, commits)
2. Asks clarifying questions one at a time
3. Proposes 2-3 approaches with trade-offs and a recommendation
4. Gets user approval before any code is written
5. Writes a design spec
6. Transitions to implementation planning

**Why it matters:** Without brainstorming, AI assistants jump to the first reasonable implementation. Brainstorming catches bad assumptions before code exists.

### Test-Driven Development (before writing implementation)

**Trigger:** Implementing any feature or bugfix.

**What it does:**
1. Write a failing test first
2. Implement the minimum code to pass the test
3. Refactor if needed
4. Repeat

**Enforcement:** If active, Superpowers will delete production code written without failing tests first. This is intentionally strict.

### Systematic Debugging (before proposing fixes)

**Trigger:** Any bug, test failure, or unexpected behavior.

**What it does:**
1. Reproduce the issue
2. Form hypotheses about root cause
3. Test hypotheses systematically
4. Fix the root cause, not the symptom
5. Add regression test

**Why it matters:** Without this, AI assistants guess at fixes and retry until something works. Systematic debugging finds the actual problem.

### Verification Before Completion (before claiming done)

**Trigger:** About to claim work is complete, fixed, or passing.

**What it does:**
1. Requires running verification commands (tests, build, lint)
2. Requires confirming output — not just "tests passed" but showing the output
3. Evidence before assertions, always

**Why it matters:** AI assistants will confidently claim "all tests pass" without running them. This forces actual verification.

### Code Review (after completing work)

**Trigger:** Major project step completed, implementation finished.

**What it does:**
1. Reviews implementation against the original plan
2. Checks coding standards
3. Identifies issues, gaps, and improvements

### Writing Plans (before multi-step implementation)

**Trigger:** Multi-step task with a design spec ready.

**What it does:**
1. Creates a step-by-step implementation plan
2. Identifies critical files and dependencies
3. Considers architectural trade-offs
4. Provides review checkpoints

### Subagent-Driven Development (for parallel work)

**Trigger:** Implementation plan with independent tasks.

**What it does:**
1. Dispatches independent tasks to parallel sub-agents
2. Each agent works in isolation
3. Results are reviewed and integrated

## The Actual Daily Cycle

For a typical feature, the real workflow is:

```
1. User describes what they want
2. Superpowers: brainstorming activates
   → Clarify requirements
   → Propose approaches
   → Get approval
   → Write spec
3. Superpowers: writing-plans activates
   → Create implementation plan
4. Superpowers: test-driven-development activates
   → Write failing test
   → Implement
   → Verify
5. Superpowers: verification-before-completion activates
   → Run tests, show output
   → Confirm everything works
6. Superpowers: code-review activates (if major step)
   → Review against plan
```

For a bugfix:
```
1. User reports bug
2. Superpowers: systematic-debugging activates
   → Reproduce → Hypothesize → Test → Fix
3. Superpowers: verification-before-completion activates
   → Run tests, confirm fix
```

## Installation

```bash
# In Claude Code
claude plugin install superpowers
```

Enable in `~/.claude/settings.json`:
```json
{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true
  }
}
```

## Relationship to Rules

Superpowers is the **enforcement layer** — it actively intervenes during work. The `.claude/rules/` files are the **governance layer** — they define conventions and decision frameworks. Most projects rely on Superpowers alone for workflow enforcement, without explicit rules files.

When both exist (like in advanced projects), the authority hierarchy applies:
1. Rules (`.claude/rules/`) — highest
2. Superpowers enforcement — second
3. Learned patterns — third
4. Defaults — lowest