pm-claude-skills/exports/cursor/pm-engineering/claude-superpowers/claude-superpowers.mdc

---
description: "Activate a 4-stage coding discipline framework that forces Claude to plan before coding, isolate changes on a branch, write tests first, and self-review output twice before presenting it. Use when starting a complex coding task, when past Claude sessions produced broken first drafts, or when you want to prevent rework cycles. Produces a confirmed written plan, isolated feature branch, test-first implementation, and a double-reviewed output with a correctness and code-quality checklist."
globs:
alwaysApply: false
---

# 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?
```

---

## Output Structure

### Full task flow (all four stages)

```
PLAN
════
[Plan format as above]
Confirm this plan before I start coding.

---
[User confirms]
---

ISOLATE
Working in isolation on branch: superpowers/[task-slug]

TESTS WRITTEN
─────────────
[Test summary — all failing]
Starting implementation.

---
[Implementation runs]
---

REVIEW 1 — CORRECTNESS
───────────────────────
[Checklist]

REVIEW 2 — CODE QUALITY
────────────────────────
[Checklist]

VERDICT: Ready to present.

---

COMPLETE
════════
[Summary of what was built, files created/modified, how to run/test it]
Branch: superpowers/[task-slug] — merge when ready.
```

---

## CLAUDE.md Installation Text

After activating Superpowers for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent:

````
```
## Superpowers Framework

This framework is always active for coding tasks in this project.

### Stage 1 — Plan
Before writing any code: produce a written plan including task restatement, approach, files to create/modify, edge cases to handle, and assumptions. Wait for explicit user confirmation before proceeding.

### Stage 2 — Isolate
Work on a feature branch (superpowers/[task-slug]) or clearly flagged working copy. Nothing is considered shipped until the user approves after Stage 4.

### Stage 3 — Test First
Write tests before writing the implementation. Tests should fail before implementation, pass after. If no test setup exists, offer to create one or produce a manual verification checklist.

### Stage 4 — Double Review
After completing code, run two reviews before presenting:
- Review 1: Does this match what was asked for? Check against original request and plan.
- Review 2: Is this good code? Check for bugs, missing error handling, security issues, readability.
Fix any issues found. Present the corrected version. Show the review checklist.
```
````

Tell the user: "Add this to your CLAUDE.md and Superpowers will be active permanently for this project."

---

## Quality Checks

- [ ] Stage 1 plan was shown and user explicitly confirmed before any code was written
- [ ] Plan includes: task restatement, approach, files to modify, edge cases in scope, edge cases out of scope, assumptions
- [ ] Ambiguities in the original request were flagged in the plan (not silently assumed)
- [ ] Stage 2 isolation: a feature branch was created (or flagged as working copy if no git)
- [ ] Stage 3 tests were written before implementation — not after
- [ ] Tests were run and confirmed to be failing before implementation started
- [ ] Stage 4 Review 1 checked against the original request — not just against the plan
- [ ] Stage 4 Review 2 checked for bugs, error handling, security, readability — all four
- [ ] Issues found in either review were fixed before presenting — not flagged as "things to fix later"
- [ ] Final output shows what was built, which files were changed, and how to run/test it
- [ ] CLAUDE.md installation text was offered after activation

---

## Anti-Patterns

- [ ] Do not proceed to Stage 2 without explicit user confirmation of the plan — coding before confirmation defeats the entire purpose of the planning stage
- [ ] Do not write tests after the implementation and call it "test-first" — tests must be written and confirmed failing before the implementation starts
- [ ] Do not skip the Double Review when time is tight — the review is most valuable precisely when speed is the priority, because that is when errors are most likely
- [ ] Do not expand scope during Stage 2 without surfacing it — silent scope expansion produces code the user did not approve and may not want
- [ ] Do not mark both reviews as clean without actually performing them — a rubber-stamp review produces false confidence and defeats the framework

## Example Trigger Phrases

- "Enable superpowers mode"
- "Activate superpowers"
- "Turn on superpowers for this session"
- "Use the superpowers framework"
- "Make sure you plan before coding"
- "I want you to review your work before showing me"
- "Write tests first this time"
- "Slow down and plan it out before you start building"
- "Work on a branch and show me a plan before touching anything"