Getting Started with Superpowers
Install once. Change how your AI works forever.
What is Superpowers? (Technical)
Superpowers is an agentic skills framework — a structured set of behavioral protocols that you load into an AI coding agent. It was created by Jesse Vincent, best known as the author of Request Tracker, one of the most widely deployed issue tracking systems in history.
The framework defines how an AI agent should think and behave during software development — not just what code to write, but when to stop and ask, how to plan, how to verify, and how to know when something is actually finished.
Technically, Superpowers is a collection of skills (also called plugins or rules, depending on your platform). Each skill is a focused set of instructions that activates under specific conditions. When you install Superpowers into your AI tool, you're giving it a set of professional software engineering disciplines built as machine-readable protocols.
Core Philosophy
Superpowers is built on three principles that run through every skill:
1. TDD First (Test-Driven Development)
No production code is written without a failing test first. This is not a guideline — it is an enforced rule. The AI must write a test that fails before it writes any implementation. If you find yourself tempted to skip this step, Superpowers explicitly requires you to delete any code written without a test and start over.
Why this matters: Tests written after code tend to test what the code does, not what it should do. Tests written first capture intent and catch assumptions early.
2. YAGNI (You Aren't Gonna Need It)
Build only what is explicitly required. No speculative abstractions, no "future-proofing," no extra configuration options "just in case." Every addition to a codebase has a maintenance cost. Superpowers keeps the AI focused on the task at hand.
3. Evidence Over Claims
Seeing a test pass is evidence. Saying it should work is a claim. Superpowers requires the AI to produce actual output — real test results, real command outputs, real file diffs — before asserting that anything is complete. "It should work" is not an acceptable completion statement.
Installation
Superpowers works across multiple platforms. Choose your tool:
Claude Code
/plugin install superpowers@claude-plugins-official
This installs the full Superpowers skill suite into your Claude Code session. Skills activate automatically based on context.
Cursor
/add-plugin superpowers
After adding the plugin, Cursor will load the skill definitions. You may need to restart your Cursor session.
Gemini CLI
gemini extensions install superpowers
Follow the prompts to authorize the extension. All skills become available in your next Gemini CLI session.
Codex
Add Superpowers as a custom instruction set via the Codex configuration file. Refer to the official Codex documentation for plugin installation paths.
OpenCode
opencode plugin add superpowers
Skills load automatically on session start.
Verifying Your Installation
After installation, ask your AI agent:
"What Superpowers skills are available?"
A correctly installed Superpowers suite will list the active skills. You should see skills including brainstorming, writing-plans, executing-plans, test-driven-development, and others.
If the agent doesn't recognize the skills, re-run the installation command and restart your session.
The 7-Step Core Workflow
Once installed, Superpowers guides development through a structured 7-step process. Here's a brief overview — each step has its own dedicated chapter.
| Step | Skill | Description |
|---|---|---|
| 1 | BRAINSTORM | Explore problem space |
| 2 | ISOLATE | Create safe work environment |
| 3 | PLAN | Write detailed task list |
| 4 | EXECUTE | Implement with subagents |
| 5 | TEST | TDD cycle: Red → Green → Done |
| 6 | REVIEW | Two-stage quality gate |
| 7 | COMPLETE | Verified delivery |
Step 1: Brainstorming
The AI explores the problem with you before touching any code. It asks clarifying questions one at a time, presents 2–3 approaches with trade-offs, and waits for your approval. A hard gate prevents code from being written until a design is approved.
→ Covered in detail in Brainstorming & Design
Step 2: Isolation
Work happens in a git worktree — an isolated copy of your repository. Changes stay contained until they're deliberately merged. Your main branch is always safe.
→ Covered as part of the execution workflow
Step 3: Writing Plans
Before execution begins, a detailed implementation plan is produced. Each task in the plan is self-contained, with complete code snippets, exact file paths, and exact commands. The plan is reviewed and approved.
→ Covered in detail in Writing Plans
Step 4: Execution & Subagents
Tasks from the plan are dispatched to fresh subagent processes — isolated AI instances with no memory of previous tasks. This prevents errors from one task contaminating the next. Each completed task goes through a two-stage review.
→ Covered in detail in Execution & Subagents
Step 5: Test-Driven Development
Every feature begins with a failing test. The RED-GREEN-REFACTOR cycle is followed strictly. No feature is marked complete without running the test suite and seeing actual passing output.
→ Covered in detail in Test-Driven Development
Step 6: Review
A two-stage review process checks both spec compliance (did we build what was asked?) and code quality (is the code maintainable and correct?). These two concerns are evaluated separately.
→ Part of the Execution & Subagents chapter
Step 7: Completion
After all verification gates pass, the agent presents a clean completion report, helps create a pull request, and ensures the work is properly integrated. Nothing is "done" until it's provably done.
→ Covered in the finishing-a-development-branch skill documentation
Quick Reference: Key Commands
| Action | What to say to your AI |
|---|---|
| Start a new feature | "I want to add [feature]. Use the brainstorming skill." |
| Write a plan | "We've agreed on the design. Write an implementation plan." |
| Execute a plan | "Execute this plan using subagents." |
| Run TDD | "Implement [feature] using test-driven development." |
| Review work | "Review this implementation before we complete." |
What Comes Next
This guide walks through each step of the workflow in depth. The chapters are designed to be read in order for your first pass, then used as reference material afterward.
- Brainstorming & Design — The hard gate that protects you from premature code
- Writing Plans — How to turn a design into executable tasks
- Execution & Subagents — Running plans safely with context isolation
- Test-Driven Development — The iron law of evidence-based delivery
Remember: Superpowers is not about slowing down. It's about stopping the expensive cycle of write → break → fix → break again. The upfront discipline saves multiples of time downstream.