Superpowers — A Complete Software Development Methodology for AI Coding Agents

I’ve been deep in the agent tooling space lately — exploring Agent Harness architectures and Deep Agent. But knowing what a harness is and knowing how to structure agent behavior effectively are two different things.

Enter Superpowers by Jesse Vincent (of Prime Radiant). It’s a complete software development methodology encoded as composable skills for coding agents. It doesn’t just give agents tools — it gives them process.

And it’s been sitting in my bookmarks for a while. Time to dig in.

What Superpowers Is

Superpowers is a plugin available for Claude Code, Codex CLI, Codex App, Cursor, Gemini CLI, OpenCode, Factory Droid, and GitHub Copilot CLI. Once installed, it transforms how your coding agent behaves from the moment you start a session.

The core workflow:

Brainstorming → Design Doc → Implementation Plan → Subagent-Driven Development → TDD → Code Review → Finish Branch

Each step is a skill that auto-triggers at the right moment. The agent doesn’t ask “what should I do?” — it follows the workflow.

The 7-Step Development Pipeline

1. Brainstorming

Before any code is written, the brainstorming skill activates. It’s a hard gate — no implementation skill can run until the user has reviewed and approved a written design.

The agent explores project context, asks clarifying questions one at a time, proposes 2-3 approaches with trade-offs, and presents the design in digestible sections. Only after you approve each section and review the written spec file does it proceed.

The skill is explicit about what triggers it: “creating features, building components, adding functionality, or modifying behavior.” Even a todo list app goes through this process. The reasoning is that “simple” projects are where unexamined assumptions cause the most wasted work.

2. Design Document

After approval, the agent saves a spec to docs/superpowers/specs/YYYY-MM-DD-topic-design.md and commits it. This becomes the source of truth for the entire implementation.

3. Implementation Plan

The writing-plans skill takes the approved spec and breaks it into bite-sized tasks — each one a 2-5 minute action. Every task specifies exact file paths, complete code, testing steps, and verification criteria.

The plan assumes the engineer has “zero context for our codebase and questionable taste.” It documents everything needed to execute without referring back to the original session.

4. Subagent-Driven Development

This is the most interesting skill. Instead of the main agent doing all the work (and polluting its context), it dispatches a fresh subagent for each task with precisely scoped instructions and no inherited context.

After each task, a two-stage review runs:

1. Spec compliance review — does the code match the design?
2. Code quality review — is the implementation sound?

If either review fails, the implementer subagent fixes it before the next task starts. The main agent never sees the implementation details — it only coordinates.

5. TDD (Test-Driven Development)

Enforced at the process level, not just suggested. The skill’s iron law:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over. The agent watches the test fail first (to confirm it tests the right thing), writes the minimal code to pass, refactors, and commits. Every step is explicit.

6. Code Review

Between tasks, the requesting-code-review skill triggers. It reviews the implementation against the plan and reports issues by severity: Critical, Important, or Minor. Critical issues block progress until resolved.

The review includes planted-bug detection — the test suite asserts that the reviewer flags SQL injection, plaintext password handling, and credential logging at Critical or Important severity.

7. Finishing a Branch

When all tasks are complete, the agent verifies tests, presents options (merge, PR, keep, discard), and cleans up worktrees. The using-git-worktrees skill ensures all feature work happens in isolated workspaces via native tools or git worktree fallback.

The Philosophy Behind It

Superpowers is opinionated in ways that make it effective:

• Process over guessing — systematic beats ad-hoc every time
• Evidence over claims — verify before declaring success
• Complexity reduction — simplicity as a primary goal
• TDD is not optional — the methodology enforces it

These aren’t just suggestions in the README. They’re encoded into the skill behavior. The brainstorming skill’s hard gate prevents any code from being written without design approval. The TDD skill’s iron law enforces test-first. The subagent dispatch ensures clean context isolation.

The 94% PR Rejection Rate

One of the most striking signals about this project is its 94% PR rejection rate, documented in the contributor guidelines. Almost every rejected PR was submitted by an AI agent that didn’t read the guidelines, didn’t verify the problem was real, or pushed domain-specific changes upstream.

The CLAUDE.md / AGENTS.md file is a direct, unflinching message to AI agents:

Your job is to protect your human partner from that outcome. Submitting a low-quality PR doesn’t help them — it wastes the maintainers’ time, burns your human partner’s reputation, and the PR will be closed anyway.

The guidelines require:

• Reading the entire PR template and filling every section
• Searching for existing PRs before opening a new one
• Verifying the problem is real (not theoretical)
• Confirming the change belongs in core vs. a standalone plugin
• Identifying the model, harness, and plugins used
• Showing the human partner the complete diff before submitting
• Including a session transcript for new harness support

This is a masterclass in how to structure contributor guidelines for AI-generated contributions.

What I Learned for My Own Agent Work

Superpowers validated several design decisions in my doppelganger agent and showed me new patterns:

1. Hard gates work. The brainstorming skill’s hard gate (“don’t write code until design is approved”) is a pattern I want to adopt. My agent already has a plan-gate, but making it truly enforced rather than suggested would improve outcomes.

2. Subagent dispatch solves context pollution. Instead of one agent accumulating context across hours of work, dispatch specialized subagents with isolated context. This is what I’ve been doing manually — Superpowers formalizes it into a skill.

3. Two-stage review catches different things. Spec compliance (does it match the design?) and code quality (is it well-written?) are separate concerns that need separate review passes. My current system combines them.

4. TDD as process, not preference. The iron law approach — “no production code without a failing test first” — is the only way TDD actually works. If it’s optional, it won’t happen.

5. Worktree isolation for every feature. Working in isolated workspaces prevents cross-feature contamination and makes reverting trivial. This is a pattern I’m adopting for my own projects.

If you’re building agentic development workflows, I highly recommend reading through the Superpowers source. The skills are written as SKILL.md files that are designed to be read and understood by both humans and agents — they’re some of the best examples of agent skill design I’ve seen.