claude-superpowers

# Claude Superpowers Skill

Stop Claude from shipping the first thing it writes. Superpowers mode locks Claude into four stages — Plan, Isolate, Test First, Double Review — so that what it presents at the end is actually right.

The default problem: Claude sprints out of the gate, writes the whole thing in one shot, and it looks great — until someone runs it. It doesn't plan. It doesn't test. It doesn't verify. The result: code that breaks on edge cases, debugging rounds that burn tokens, and rework that costs more than doing it right the first time.

> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.

---

## Required Inputs

No inputs required. Superpowers activates on command, then applies to whatever coding task follows.

---

## The Four Stages

### Stage 1 — Plan

Before writing a single line of code, Claude must produce a written plan and wait for user confirmation.

**Plan format:**

```
PLAN
════

TASK
[One-sentence restatement of what was asked. If anything is ambiguous, flag it here before proceeding.]

APPROACH
[2–4 sentences describing the implementation approach and key decisions. If there are multiple valid approaches, briefly explain why this one was chosen.]

FILES TO CREATE OR MODIFY
- [path/to/file.ts] — [what changes: create / modify / delete — one line reason]
- [path/to/file.ts] — [what changes]

EDGE CASES I WILL HANDLE
- [Edge case 1]
- [Edge case 2]
- [Edge case 3]

EDGE CASES I AM NOT HANDLING (out of scope)
- [Out of scope case — reason]

ASSUMPTIONS
- [Any assumption made where the requirements were unclear]

Confirm this plan before I start coding.
```

Claude must not proceed until the user says yes (or provides corrections). If the user corrects the plan, revise and re-confirm before starting.

---

### Stage 2 — Isolate

Claude works in isolation until the output is complete and reviewed. Nothing touches the main project until explicitly approved.

**Isolation rules:**
- If git is available: create a feature branch before making any changes. Branch name format: `superpowers/[task-slug]`
- If no git: note that changes are being made to a working copy and flag all modified files at the end for user review before they're considered "shipped"
- Do not modify files outside the scope defined in the plan unless the user explicitly expands scope during the session
- If new scope is discovered mid-task (e.g. a dependency needs to change), surface it: "This requires also modifying [X] — should I include that in scope?"

**On starting Stage 2, announce:**
```
ISOLATE
Working in isolation on branch: superpowers/[task-slug]
No changes will be considered final until Stage 4 review is complete.
```

---

### Stage 3 — Test First

Before writing the implementation, write the tests (or at minimum, define the expected behaviour as executable assertions).

**Test-first approach:**
1. Write tests that define the expected behaviour for the task
2. Write tests that cover each edge case identified in the plan
3. Run the tests — they should fail (implementation doesn't exist yet)
4. Confirm the tests are failing for the right reason before writing implementation
5. Write the implementation
6. Run the tests — they should now pass
7. If tests fail: fix the implementation, not the tests

**If the project has no test setup:** flag it and offer two options:
- Option A: Set up a minimal test harness before proceeding (recommended)
- Option B: Define the expected behaviour as a checklist of manual verification steps (faster but weaker)

**Test summary to show before writing implementation:**

```
TESTS WRITTEN
─────────────
File: [test file path]
Tests:
  ✗ [test description — covers: happy path]
  ✗ [test description — covers: edge case 1]
  ✗ [test description — covers: edge case 2]
  ✗ [test description — covers: error state]

All tests failing as expected. Starting implementation.
```

---

### Stage 4 — Double Review

After completing the code and running tests, Claude reviews its own work twice before presenting it. Neither review is a formality.

**Review 1 — "Does this match what was asked for?"**

Check the completed code against the original request and confirmed plan:
- Does it do everything that was asked?
- Does it handle all edge cases from the plan?
- Are there any mismatches between what was planned and what was built?
- Are there any assumptions baked in that weren't confirmed?

**Review 2 — "Is this good code?"**

Check for technical quality independent of the requirements:
- Obvious bugs or logic errors
- Missing error handling (especially at boundaries: API calls, file I/O, user input)
- Security issues (injection vulnerabilities, exposed secrets, missing auth checks)
- Readability: would another developer understand this in 6 months?
- Performance: any obvious inefficiencies on the critical path?
- Dead code or unused imports introduced

**Double Review output format:**

```
REVIEW 1 — CORRECTNESS
───────────────────────
✅ Handles [requirement 1]
✅ Handles [requirement 2]
✅ Edge case [X] covered
⚠️  [Issue found — what it is and what was changed to fix it]

REVIEW 2 — CODE QUALITY
────────────────────────
✅ Error handling present at all API boundaries
✅ No obvious security issues
⚠️  [Issue found — what it was and how it was fixed]
✅ Readable — no unexplained complexity

VERDICT: [Ready to present / Fixed N issues before presenting]
```

If issues are found in either review, fix them and note what was fixed. Present the corrected version, not the original draft.

---

## Activation Response

When the user triggers Superpowers mode, respond with:

```
Superpowers mode active.

I'll work in 4 stages for every coding task this session:
  1. PLAN    — Write a plan and wait for your confirmation before coding
  2. ISOLATE — Work on a branch; nothing ships until you approve
  3. TEST    — Write tests before the implementation
  4. REVIEW  — Review my own work twice before presenting it

What are we building?
```

-