/concepts/how-it-works

How it works

Understand the Superpowers mental model, philosophy, and why it improves agentic software development.

Superpowers is built on a simple premise: coding agents work better with structure than with blank prompts. This page explains the mental model and philosophy behind the methodology.

Core idea

Most AI coding sessions fail the same way:

1. The user asks for a feature
2. The agent immediately starts writing code
3. The code is confidently wrong
4. The user finds bugs in production
5. Rinse and repeat

Superpowers breaks this cycle by inserting mandatory checkpoints into the workflow. The agent cannot proceed to the next phase until the current phase is complete and validated.

The workflow phases

Idea → Brainstorming → Design → Worktree → Plan → Execute → Test → Review → Ship

Each arrow is a Superpowers skill. The agent checks for the relevant skill before any task.

Phase 1: Brainstorming

Before writing code, the agent must understand what you’re trying to do. The brainstorming skill uses Socratic questioning to:

• Refine rough ideas through targeted questions
• Explore alternatives and tradeoffs
• Surface edge cases and constraints
• Present design in short, reviewable chunks

The output is a written design document saved in your project. You approve it before proceeding.

Phase 2: Worktree isolation

The using-git-worktrees skill creates an isolated branch for the work. This prevents experimental code from polluting your main branch.

The skill also:

• Runs project setup on the new branch
• Verifies a clean test baseline
• Ensures you’re starting from green tests

Phase 3: Implementation planning

The writing-plans skill breaks approved designs into bite-sized tasks:

• 2-5 minutes per task
• Exact file paths specified
• Complete code provided
• Verification steps included

The plan is clear enough that an enthusiastic junior engineer with poor taste, no judgment, no project context, and an aversion to testing could follow it.

Phase 4: Execution

Superpowers offers two execution modes depending on platform support:

subagent-driven-development: For platforms with subagent support. Dispatches fresh subagents per task with two-stage review. Enables autonomous work for hours.

executing-plans: For platforms without subagents. Batch execution with human checkpoints.

Phase 5: Test-driven development

The test-driven-development skill enforces true TDD:

• Write failing test first
• Watch it fail
• Write minimal code to pass
• Watch it pass
• Commit

If the agent tries to write code before tests, the skill makes it delete that code. This is not a suggestion—it’s enforced.

Phase 6: Code review

The requesting-code-review skill reviews work against the original plan:

• Reports issues by severity (critical, warning, info)
• Critical issues block progress
• Ensures deviations are intentional, not accidental

Phase 7: Clean finish

The finishing-a-development-branch skill:

• Verifies tests pass
• Presents merge/PR options
• Cleans up worktree
• Leaves git history clean

Philosophy

Superpowers is built on four principles:

Test-driven development

Write tests first, always. Evidence over claims. If you can’t write a test for it, you don’t understand it.

Systematic over ad-hoc

Process over guessing. The 4-phase debugging skill replaces “try this, try that” with hypothesis-driven investigation.

Complexity reduction

Simplicity as primary goal. YAGNI (You Aren’t Gonna Need It) is enforced during planning. Every feature must justify its existence.

Evidence over claims

Verify before declaring success. The verification-before-completion skill requires proof, not promises.

Why this works

Traditional agent interactions are:

• Stateless: Each prompt is independent
• Unconstrained: The agent can do anything
• Unverified: Claims are accepted at face value

Superpowers makes them:

• Stateful: Skills track workflow phase and context
• Constrained: Skills limit what the agent can do at each phase
• Verified: Every claim requires evidence

The skills trigger automatically, so you don’t need to learn new commands or remember to invoke them. Your agent just has Superpowers.

Comparison to unassisted agents

When to use Superpowers

Use Superpowers when:

• You want structured workflows instead of blank prompts
• You’re building features that need testing and review
• You’re working on production code that affects users
• You want autonomous agents that work for hours without deviating
• You need consistent process across a team

Superpowers may be unnecessary when:

• You’re prototyping throwaway code
• You’re exploring ideas without implementation intent
• Your agent doesn’t support the plugin/extension system

Learn more

• Read the original release announcement by Jesse Vincent
• Try the Quick start to experience the workflow
• Browse Skills for detailed skill descriptions