claude-superpowers

name

claude-superpowers

description

Force Claude Code to work like a senior developer: plan before coding, work in isolation, write tests first, and review its own output twice before presenting it. Use when asked to enable superpowers mode, activate the superpowers framework, or turn on superpowers for this session. Installs a 4-stage framework — Plan, Isolate, Test First, Double Review — that prevents Claude from sprinting into broken code.

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

---

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"