Superpowers Tutorial: Give Your AI Coding Agent a Complete Software Development Methodology

Created

Ever asked Claude Code to write some code, only to watch it dive straight into implementation — producing logic that misses the point, has no tests, and doesn’t match what you actually needed? Superpowers fixes this. It doesn’t make AI write code faster — it makes AI think before it types, following a complete software development methodology.

What is Superpowers? Superpowers is an open-source AI coding skills framework (MIT license, 202k+ GitHub Stars) built by Jesse Vincent and the Prime Radiant team. It injects a complete software development methodology into Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, GitHub Copilot CLI, and 5 more agents — from requirements brainstorming to subagent-driven development, code review, and branch merging.

Prerequisites

  • AI Coding Assistant: Any of the following:
    • Claude Code (recommended)
    • Codex CLI / Codex App
    • Cursor
    • Gemini CLI
    • OpenCode
    • Factory Droid
    • GitHub Copilot CLI

💡 Tip: If you use multiple AI coding assistants, install Superpowers separately for each one.

Overview

Superpowers’ core philosophy is: AI coding agents should not jump straight into writing code. Instead, they should step back, ask what you’re really trying to do, create a plan, and then execute it.

The workflow has 7 stages:

  1. Brainstorming → Clarify requirements
  2. Git Worktree → Create isolated workspace
  3. Writing Plans → Break work into tasks
  4. Subagent-Driven Development → Execute tasks in parallel
  5. Test-Driven Development → RED-GREEN-REFACTOR
  6. Code Review → Quality gate
  7. Finishing the Branch → Merge/PR

These skills trigger automatically — no manual invocation needed. After installation, your AI coding agent has Superpowers.

Step 1: Install Superpowers

Method 1: Official Plugin Marketplace

1
/plugin install superpowers@claude-plugins-official

Method 2: Superpowers Marketplace

1
2
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex CLI

1
/plugins

Search for superpowers, select Install Plugin.

Cursor

In Cursor Agent chat:

1
/add-plugin superpowers

Or search “superpowers” in the plugin marketplace.

Gemini CLI

1
gemini extensions install https://github.com/obra/superpowers

OpenCode

Tell OpenCode:

1
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

GitHub Copilot CLI

1
2
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

Step 2: Understand the Core Workflow

1. Brainstorming

When you tell the AI what you want to build, Superpowers won’t let it jump into coding. Instead, it will:

  • Ask questions to clarify your real needs
  • Explore alternatives
  • Present the design in digestible chunks for your approval
  • Save a design document

💡 Tip: This is Superpowers’ most valuable stage — it ensures the AI understands what you actually want, not what it thinks you want.

2. Git Worktree

After design approval, Superpowers:

  • Creates an isolated workspace on a new branch
  • Runs project setup
  • Verifies the test baseline is clean

3. Writing Plans

Superpowers breaks work into small tasks (2-5 minutes each), each containing:

  • Exact file paths
  • Complete code
  • Verification steps

The plan is designed so that even “an enthusiastic junior engineer with poor taste, no judgment, no project context, and an aversion to testing” could follow it.

4. Subagent-Driven Development

During execution, Superpowers:

  • Dispatches a fresh subagent for each task
  • Each subagent completes its task independently
  • Two-stage review: spec compliance → code quality
  • Claude can work autonomously for hours without deviating from the plan

5. Test-Driven Development (TDD)

Superpowers enforces the RED-GREEN-REFACTOR cycle:

  1. 🔴 Write a failing test
  2. Watch it fail
  3. 🟢 Write minimal code to make it pass
  4. Watch it pass
  5. Commit

Iron Rule: If code is written before tests, Superpowers deletes it.

6. Code Review

Between tasks, Superpowers:

  • Reviews against the plan
  • Reports issues by severity
  • Critical issues block progress

7. Finishing the Branch

After all tasks complete, Superpowers:

  • Verifies tests
  • Presents options: merge / create PR / keep / discard
  • Cleans up the worktree

Step 3: Master the 14 Core Skills

Testing

Skill Purpose
test-driven-development RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging

Skill Purpose
systematic-debugging 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting)
verification-before-completion Ensure the fix actually works

Collaboration

Skill Purpose
brainstorming Socratic design refinement
writing-plans Detailed implementation plans
executing-plans Batch execution with checkpoints
dispatching-parallel-agents Concurrent subagent workflows
requesting-code-review Pre-review checklist
receiving-code-review Responding to feedback
using-git-worktrees Parallel development branches
finishing-a-development-branch Merge/PR decision workflow
subagent-driven-development Fast iteration with two-stage review

Meta

Skill Purpose
writing-skills Create new skills following best practices
using-superpowers Introduction to the skills system

Design Philosophy

Superpowers’ core principles:

  • Test-Driven Development: Write tests first, always
  • Systematic over ad-hoc: Process over guessing
  • Complexity reduction: Simplicity as primary goal
  • Evidence over claims: Verify before declaring success

FAQ

Q: Does Superpowers trigger automatically?
A: Yes. After installation, the AI coding agent checks for relevant skills before any task. These are mandatory workflows, not suggestions.

Q: Which AI coding assistants are supported?
A: Currently 8: Claude Code, Codex CLI, Codex App, Factory Droid, Gemini CLI, OpenCode, Cursor, GitHub Copilot CLI.

Q: How is Superpowers different from other AI coding skill packs?
A: Superpowers isn’t just a collection of skills — it’s a complete software development methodology. It enforces TDD, systematic debugging, code review, and other engineering practices, rather than letting AI write code arbitrarily.

Q: How do I update Superpowers?
A: Depends on your AI coding assistant, but updates are often automatic.

Q: Can I contribute new skills?
A: Superpowers generally does not accept new skill contributions. Any skill updates must work across all supported coding agents. See skills/writing-skills/SKILL.md for details.

Conclusion

You’ve learned the core capabilities of Superpowers:

  1. ✅ Installed Superpowers in your AI coding assistant
  2. ✅ Understood the 7-stage core workflow (brainstorming → planning → TDD → review)
  3. ✅ Mastered the 14 core skills
  4. ✅ Learned Superpowers’ design philosophy

Superpowers’ core value is making AI coding agents follow engineering best practices instead of writing code haphazardly. By enforcing TDD, systematic debugging, and code review, your AI assistant transforms from “an enthusiastic junior engineer with poor taste” into a reliable partner following a complete software development methodology.

📖 Official repo: github.com/obra/superpowers
💬 Discord: Join the community
📝 Release announcements: primeradiant.com/superpowers