1. What Superpowers Is

Superpowers is a plugin that bolts “engineering discipline” onto a coding agent, maintained by Prime Radiant. It is not a library of prompt templates but a complete software engineering methodology built on top of Skills — at session startup a bootstrap mechanism makes the AI automatically invoke the right process at the right moment.

Core design:

1. Skills — behavior specifications written in Markdown and version-controllable, describing “when to use it,” “what must be done,” and “what is forbidden”
2. Bootstrap — at session start it injects the using-superpowers skill, teaching the agent: if a skill exists you must use it, and check for skills before replying or acting
3. Automatic triggering — no need to type /brainstorm by hand. When the agent judges that you are “starting a task,” it defaults to design discussion rather than writing code immediately

The project deliberately keeps zero third-party dependencies — skills are plain text, hooks are shell scripts, and it runs on any harness that supports plugins/hooks.

• Project repository: https://github.com/obra/superpowers
• Original announcement: https://blog.fsck.com/2025/10/09/superpowers/
• Current version: v6.x (June 2026)

It supports more than a dozen harnesses, including Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Pi, Antigravity, and Kimi Code.

2. Why You Need It

AI coding assistants can already write code, but the common experience is:

• You say “make me a React todo list” and the AI immediately scaffolds a project and writes components — without ever asking what you actually want
• The code runs, but the architecture is arbitrary, tests are missing, and edge cases were never considered
• You fix one bug and introduce two new ones
• In a long session the AI gradually “forgets” the design conventions it started with

What Superpowers solves is a process problem: it encodes design, isolated development, fine-grained planning, TDD, review, and wrap-up into the system, instead of relying on a human to remind it every time.

3. The Core Workflow

Superpowers breaks a feature development effort into seven stages, each corresponding to a skill, chained together automatically in order:

brainstorming → using-git-worktrees → writing-plans
       → subagent-driven-development / executing-plans
       → test-driven-development（贯穿实现）
       → requesting-code-review → finishing-a-development-branch

3.1 Brainstorming — Design First, Code Later

When it triggers: before any creative work — a new feature, a new component, a behavior change.

What it does:

• Explores project context (files, docs, recent commits)
• Asks one question at a time, progressively clarifying purpose, constraints, and success criteria
• Proposes 2–3 approaches with trade-offs and a recommendation
• Presents the design in chunks, waiting for your confirmation on each
• Writes a design document (docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md)
• Only after the design is approved does it move on to writing-plans

HARD-GATE: until the user approves the design, writing code, scaffolding, or invoking any implementation skill is forbidden. “It’s too simple to need a design” is an explicitly banned anti-pattern.

An optional Visual Companion opens a local web interface whenever “showing is clearer than describing,” making multiple-choice style requirement clarification convenient.

3.2 Using Git Worktrees — An Isolated Workspace

Once the design is approved, it creates an independent worktree and a new branch in the git repository, runs the project setup, and confirms the test baseline is clean. Multiple tasks on the same project can run in parallel without interfering with each other.

v5.1+ improvements: if the agent is already running inside a worktree it skips creation; it asks for consent before creating; and it prefers the harness’s native worktree tooling.

3.3 Writing Plans — A Plan for a “Junior Engineer with Zero Context”

Plans are written in enough detail that an implementer with no project context can follow them. YAGNI, DRY, and true RED/GREEN TDD are emphasized.

New structure in v6.0:

• Global Constraints — global rules every task must obey (minimum versions, dependency limits, naming conventions, and so on)
• Interfaces — each task states explicitly “what it consumes and what it produces”
• Task granularity — each task is on the order of 2–5 minutes, with exact file paths, complete code snippets, and verification steps

3.4 Subagent-Driven Development — A Subagent Pipeline

After you say “go,” the main agent acts as coordinator:

1. Dispatches a brand-new implementer subagent for each task
2. The subagent implements, tests, commits, and self-reviews
3. After each task it dispatches a task reviewer to check both spec compliance and code quality
4. When all tasks are done, it performs one broad review of the whole branch
5. It invokes finishing-a-development-branch to handle merge/PR/keep/discard

The main agent will not stop between tasks to ask “shall I continue?” — you approved the plan, so it executes it to the end.

v6.0 review flow rework (roughly 2× faster and ~50% token savings in evals):

Progress is recorded under .superpowers/sdd/.

Alternative path executing-plans: when tasks are tightly coupled, or you want to keep the pace under human control, you can choose batch execution with manual checkpoints.

3.5 Test-Driven Development — The Iron Law

Running through the entire implementation stage:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

• RED: write a failing test and watch it fail with your own eyes
• GREEN: write the minimum code to make the test pass
• REFACTOR: tidy up while the light is green

Wrote the implementation first? Delete it and start over. There is no exception for “keep it around as a reference.”

3.6 Requesting Code Review

Issues are reported by severity, and Critical issues block further progress.

3.7 Finishing a Development Branch

Verify the tests, present the options (merge / open a PR / keep the branch / discard), and clean up the worktree. It is now forge-neutral and no longer hardcodes gh pr create.

4. The Skills Mechanism

The workflow itself is not the point — Skills are. Skills are executable specifications for an LLM: in the situations where they apply they are mandatory process, not suggestions.

A skill file typically contains:

• YAML frontmatter (name, description) — the description determines when it is retrieved/triggered
• A flow chart (Graphviz dot)
• A checklist (the agent must create a todo for each item)
• A Red Flags table — listing the agent’s common self-rationalizing excuses and the rebuttals
• HARD-GATE — a threshold that cannot be crossed

4.1 Bootstrap: using-superpowers

Every harness loads the bootstrap at session startup. The core rule:

If there is even a 1% chance that a skill applies, you must invoke that skill — before replying, before clarifying questions, before reading files.

Common Red Flags:

Priority: explicit user instructions > Superpowers skills > default system prompt.

4.2 Skills Also Get “TDD”

The writing-skills skill requires new skills to go through adversarial stress testing: subagents simulate real-world scenarios (production outage, sunk cost, time pressure) rather than quiz-style “perfect score tests.” When a test fails, the skill’s wording is hardened — this is the RED/GREEN of skills.

4.3 Persuasion Principles

writing-skills/persuasion-principles.md documents research by Meincke et al. (2025): applying Cialdini’s seven persuasion principles to an LLM raised compliance from 33% to 72%. Superpowers uses levers such as Authority, Commitment, Scarcity, and Social proof to keep engineering discipline in force under pressure — countering the LLM’s innate tendency to “act first and think later.”

5. The Skills Library at a Glance

Testing

Debugging

Collaboration / Process

Meta-skills

6. Design Philosophy

Skills deliberately use “your human partner” rather than “user” — emphasizing the pairing relationship, a design choice that was tested.

7. Installation and Supported Platforms

Superpowers is harness-neutral: the same set of skills adapts to different runtimes through each platform’s hooks/bootstrap.

Integration standard: it must load the using-superpowers bootstrap at session startup. Manually copying skill files, or a scheme that requires manual opt-in every session, does not count as a qualified integration.

Acceptance Test

In a fresh session, send:

Let's make a react todo list

If brainstorming triggers automatically before any code is written, the integration works.

8. Version Evolution

Still in progress: Sharing (a mechanism for sharing personal skills) and Memories (remembering-conversations — the components are written but not yet fully wired together and released).

9. Testing and Quality Assurance

Superpowers splits testing into two layers:

1. tests/ — plugin infrastructure tests (hooks, manifest, cross-platform shell)
2. evals/ (superpowers-evals) — drives real Claude Code / Codex / Gemini sessions with the Drill harness, with an LLM verifier judging skill compliance

Changing skill content has a very high bar: it requires adversarial pressure testing and before/after eval evidence.

10. Usage Advice

10.1 Your First Run

After installing, send the single line Let's make a react todo list and watch whether the agent asks “what kind of todo list do you want” or has already run npm create vite — that difference alone is the reason Superpowers exists.

10.2 Relationship to OpenSpec

Both emphasize “align before writing code,” but they take different paths:

They can be used together: OpenSpec governs “what to do,” Superpowers governs “how to do it.”

10.3 Telemetry

Brainstorming’s Visual Companion loads a logo (with a version number) from the Prime Radiant website by default, for rough usage counting — it contains no project content. It can be turned off with SUPERPOWERS_DISABLE_TELEMETRY=1.

11. FAQ

Q: How much process overhead does Superpowers add?

A: The design for a simple feature can be just a few sentences, but the brainstorming flow cannot be skipped. The payoff is less rework, fewer missing tests, and less arbitrary architecture.

Q: Do I have to use Superpowers to do AI coding?

A: No. But if you have been through the pain of “the AI misunderstood, so I had to redo it” or “the code runs but there are no tests,” this discipline pays for itself well.

Q: Does it support Cursor?

A: Yes. Install it from the plugin marketplace or with /add-plugin superpowers in Agent chat, and make sure the bootstrap loads at session startup.

Q: How do I contribute?

A: Target PRs at the dev branch; you must fill in the PR template, disclose your authoring environment, and attach a human partner’s review. See CONTRIBUTING for details.

12. Summary

The core insights of Superpowers:

1. An LLM being able to write code does not mean it can do engineering. Design, testing, review, and version isolation need to be encoded into the system.
2. Skills are behavior as code. Version-controllable, testable, composable, and portable across harnesses.
3. Automatic triggering is the key. Bootstrap plus description-driven retrieval make “brainstorm before you write code” the default path.

The complete work cycle:

1. brainstorming 对齐设计
2. worktree 隔离开发
3. writing-plans 细粒度计划
4. subagent-driven-development 逐任务实现 + 审查
5. TDD 贯穿实现
6. finishing-a-development-branch 收尾

If you already use an AI coding assistant, Superpowers is worth one try. After installing, start from Let's make a react todo list and see whether the agent asks about requirements before it writes code.