Don’t Let AI Write for You Yet: Why the 250k‑Star Superpowers Plugin’s Full Power Remains Untapped

What Superpowers Is

Superpowers is not a code‑generation tool but a set of markdown‑based skills that enforce engineering discipline for Claude‑based AI agents. Each skill is a text file that defines a mandatory workflow, ensuring the AI follows design, testing, and review steps before writing code.

Core Skill Categories

The plugin ships with 14 skills grouped into 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 – The Hard Gate

The first hard gate in <HARD‑GATE> forbids any implementation until a design is presented and approved. The full brainstorming workflow has nine steps, from exploring the current project state to committing a design spec. Most users stop after step 4‑5, skipping steps 6‑8, which leads to missing specifications and later drift in Claude’s memory.

<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>

In practice, a complete run of the nine‑step process took about 40 minutes, but it eliminated three rounds of rework that would otherwise add two hours.

Systematic‑Debugging – Four Phases

Systematic‑debugging forces root‑cause investigation before any fix. The author reports typical manual debugging takes 2‑3 hours, while systematic‑debugging reduces it to 15‑30 minutes because Claude can no longer guess.

Phase 1 – Root‑Cause Investigation

Read the full error message.

Stably reproduce the steps.

Check recent git changes.

Add diagnostic logs at component boundaries.

Phase 2 – Pattern Analysis

Find similar working code in the same codebase.

Compare differences line‑by‑line.

Understand dependencies and assumptions.

Phase 3 – Single‑Hypothesis Validation

Write a concrete hypothesis.

Make the minimal change to test it.

If it fails, discard and try a new hypothesis.

Phase 4 – Implement Fix

Write a failing test first.

Change only one location.

If three attempts fail, stop and discuss possible architectural issues.

The “three‑failure rule” prevents endless guessing and aligns with the principle that further attempts after repeated failure increase uncertainty.

Writing‑Plans – 2‑5 Minute Tasks

After brainstorming, the spec is broken into tiny, executable tasks, each taking 2‑5 minutes. Example task list:

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

The skill rejects placeholders such as “TBD”, “TODO”, or vague descriptions, because Claude would otherwise pause for clarification or hallucinate.

Execution Options

Two execution modes are offered:

subagent‑driven‑development (recommended): each task spawns a fresh sub‑agent with a clean context, two rounds of review, and then reports back.

executing‑plans: tasks run serially in the current session, accumulating context.

Selection rules:

If the platform (Claude Code, Codex, etc.) supports sub‑agents → use subagent‑driven‑development.

If using environments like Cursor that lack sub‑agent support → use executing‑plans.

For many small tasks where overhead matters → executing‑plans may be simpler.

Empirical observation: using subagents eliminates “context bleed” where Claude unintentionally modifies previously verified code.

Finishing a Development Branch

The final skill ensures a clean finish: verify tests, choose a base branch, select one of four actions (local merge, PR, keep branch, discard), and clean the worktree accordingly. The discard option requires explicit “discard” input to avoid accidental loss.

Common Pitfalls

Context Drift

Long sessions cause Claude to forget available skills and revert to default behavior. Re‑issuing /using‑superpowers resets the skill priority.

Using Brainstorming as a Q&A Bot

Brainstorming is meant to produce a committed spec, not to act as an AI product manager. Skipping the spec and writing‑plans leads to poor implementation quality.

FAQs

Is Superpowers suitable for small projects? Yes—specs can be a few sentences, and the overhead is offset by reduced rework.

Can the two execution modes be mixed? Yes—different tasks within the same plan can use different modes.

Is the “three‑failure rule” absolute? No—it mandates a pause for discussion after three failed attempts, not a hard stop.

How long does a full run take? For a medium‑complex feature (4‑6 tasks), brainstorming 30‑40 min, writing‑plans 15‑20 min, and execution time varies; overall time usually drops after the first run due to reduced rework.

Can skills be customized? Yes—users can add custom skills under ~/.config/superpowers/skills/ to encode team‑specific policies.

Conclusion

Superpowers addresses the core problem of AI‑assisted programming: the lack of disciplined workflow, not a lack of capability. By encoding engineering processes as plain‑text skills, it forces Claude to follow design, testing, and review steps, dramatically improving reliability and reducing wasted effort.