Superpowers: The 185k-Star Plugin That Forces Discipline on AI Coding Agents

The Superpowers plugin for Claude Code has reached 185,000 GitHub stars (v5.1.0, May 2026), yet the author observes most users only invoke /brainstorming and treat it as a simple Q&A before letting the agent write code — equivalent to buying a Swiss Army knife and using only the bottle opener. The core thesis: AI coding agents lack not capability but discipline, and Superpowers distributes that discipline as plain-text behavioral constraints.

What Superpowers Is: Text-Based Engineering Discipline

Every skill in Superpowers is a Markdown file ( SKILL.md) that states: "When you encounter this task type, you must follow this process." No code, no tool calls — only textual enforcement. The plugin ships 14 skills across three categories:

Testing: test-driven-development

Debugging: systematic-debugging, verification-before-completion

Collaboration/Workflow: brainstorming, writing-plans, executing-plans, subagent-driven-development, dispatching-parallel-agents, requesting-code-review, receiving-code-review, using-git-worktrees, finishing-a-development-branch, writing-skills, using-superpowers

Brainstorming: A Hard Gate Before Any Code

The most used yet most shallowly used skill. Its SKILL.md opens with a <HARD-GATE>:

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design
and the user has approved it.
</HARD-GATE>

This is not a suggestion; it blocks any implementation until design approval. The full flow is nine steps:

Explore project state (files, commits, docs)

Provide visual companion for UI issues (separate message)

Ask clarifying questions one at a time

Propose 2–3 options with rationale

Present design section-by-section with confirmation

Write design to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit

Self-check spec for TBD/TODO, contradictions, scope, ambiguity

User reviews spec file

Handoff to writing-plans (the only allowed next skill)

Steps 6–8 are most often skipped. The author's case study: a refactor took 40 minutes to complete all nine steps but near-zero rework afterward; skipping design saved 30 minutes upfront but caused three rewrite cycles totaling two extra hours. Counter-intuitively, the skill insists even trivial changes run the full flow — "hidden assumptions in simple tasks are the biggest source of wasted work."

Systematic-Debugging: Four Phases, No Guessing

The author calls this the most undervalued skill. Ordinary debugging: error → paste → guess → fail → guess again. Superpowers data: ad-hoc debugging averages 2–3 hours; systematic-debugging 15–30 minutes. The iron law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST Four sequential phases (cannot advance until current phase completes):

Phase 1: Root-Cause Investigation

Read the entire error message (not a glance)

Stable reproduction steps

Check recent git changes

For multi-component systems, add diagnostic logs at every boundary, run once, collect evidence, then analyze the break point

Phase 2: Pattern Analysis

Find similar working code in the same codebase

Diff every difference against the broken code ("list every difference, no matter how small, do not assume it's irrelevant")

Understand dependencies and preconditions

Phase 3: Single-Hypothesis Verification

Write one concrete hypothesis ("I think X is root cause because Y")

Make the minimal change to test it

If wrong: new hypothesis, do not stack changes

Phase 4: Implement Fix

Write a failing reproduction test first

Change only one location

Three-failure rule: after three failed fixes, stop and discuss whether the architecture itself is flawed — do not attempt a fourth guess

The skill includes an "excuse vs. reality" comparison:

"Issue is simple, skip process" → Simple bugs have root causes too; process is faster even for simple problems

"Emergency, no time to investigate" → Systematic debugging is faster than guessing; urgency is not an excuse

"Try it first" → First guess locks you into guess-forever mode

"I already know roughly where it is" → Knowing symptom ≠ knowing root cause

Writing-Plans: 2–5 Minute Steps, Zero Placeholders

After brainstorming hands off, writing-plans breaks the spec into executable tasks. Key design: each step sized to 2–5 minutes. Example task breakdown:

- [ ] Step 1: Write a failing test
- [ ] Step 2: Run it, confirm it fails
- [ ] Step 3: Write minimal implementation to pass
- [ ] Step 4: Run test, confirm pass
- [ ] Step 5: Commit

"Write failing test" and "run to confirm failure" are separate steps — each has a clear done criterion so neither a subagent nor a human wonders "is this half-done?"

Zero-placeholder rule: the following are plan failures and must be corrected: TBD, TODO, "implement later"

"Add appropriate error handling" (without specifics)

"Write tests for above" (no test code provided)

"Similar to Task N" (no referencing allowed)

Rationale: when the executor hits a placeholder, it either stalls asking or improvises — both are failure modes.

Two execution options after plan approval:

Option 1 (recommended): subagent-driven-development — each task spawns a fresh subagent with two review rounds (spec compliance then code quality)

Option 2: executing-plans — serial execution in current session, periodic checkpoints for human intervention

Subagent-Driven-Development vs Executing-Plans: How to Choose

Selection criteria:

Claude Code / Codex (subagent support) → choose subagent-driven-development

Cursor or no-subagent environments → choose executing-plans

Many tasks, context drift risk → choose subagent-driven-development

Small simple tasks, avoid overhead → choose executing-plans

Documentation states: "If your environment supports subagent, use subagent-driven-development; code quality will be significantly higher." Clean context prevents prior failed attempts from biasing the agent. Author's experience: an 8-task feature using executing-plans saw task 5 corrupt a previously passing test due to context crosstalk; switching to subagents eliminated the interference. Overhead: each subagent reloads the plan file, but token cost of avoided rework far exceeds the reload cost.

Finishing-a-Development-Branch: Clean Closure

Most skipped skill. Flow:

Verify tests pass (stop if fail)

Determine base branch

Present four options:

1. Local merge to <base-branch>
2. Push and create Pull Request
3. Keep branch (I'll handle later)
4. Discard this work

Execute chosen option

Clean up worktree (only for options 1 and 4; options 2 and 3 retain)

Discard requires typing "discard" explicitly to prevent accidental deletion.

Complete Workflow

brainstorming           ← design phase, produces spec doc
    ↓
using-git-worktrees     ← create isolated workspace
    ↓
writing-plans           ← break spec into 2–5 min executable tasks
    ↓
subagent-driven-development or executing-plans ← parallel or serial implementation
    ↓
test-driven-development (runs throughout implementation) ← RED-GREEN-REFACTOR
    ↓
requesting-code-review  ← pre-submission self-check
    ↓
finishing-a-development-branch ← choose merge/PR/keep/discard, clean worktree

Insert systematic-debugging on bugs; insert verification-before-completion on validation doubts. First run feels slow; by the third run, upfront investment pays off via cliff-drop in rework.

Two Common Pitfalls

Pitfall 1: Context Drift

Long sessions cause Claude to "forget" skills and revert to default mode (skip tests, guess bugs, write without design). Fix: explicitly invoke /using-superpowers to reset skill priority.

Pitfall 2: Treating Brainstorming as a Q&A Machine

Brainstorming asks questions to produce a design , not merely to clarify requirements. Stopping after Q&A without a committed spec leaves execution without a concrete reference, degrading quality.

FAQ Highlights

Small projects? Spec can be a few sentences. The question isn't project size but tolerance for rework. Many "5-minute tweaks" without design become 2-hour multi-rewrite ordeals.

Mix subagent and executing-plans? Yes — per task. Useful when some tasks need manual steps (e.g., env var setup).

Three-failure rule absolute? Not "never fix again"; after three failures you must pause and discuss architecture vs. another guess. Continue only after that discussion.

Total time? Medium feature (4–6 tasks): brainstorming 30–40 min, writing-plans 15–20 min, execution varies. Upfront cost usually recouped by eliminated rework.

Custom skills? Yes, writing-skills teaches Claude to create new skills. Personal skill library at ~/.config/superpowers/skills/.

Ultimately, Superpowers solves not "can Claude do it?" — it usually can — but "will Claude skip steps?" Discipline, distributed as plain text, is the 185,000-star consensus.