Skip to main content

​
Quickstart Guide

Get your coding agent powered up with systematic workflows in just a few steps.

​
Installation

Superpowers installs differently depending on your platform. Choose your coding agent:
1

Choose Your Platform

Claude Code

Install via plugin marketplace

Cursor

Install via plugin marketplace

Codex

Manual installation via git clone

OpenCode

Manual installation via git clone
2

Install the Plugin

Follow the platform-specific installation instructions:
# Register the marketplace
/plugin marketplace add obra/superpowers-marketplace

# Install Superpowers
/plugin install superpowers@superpowers-marketplace
For detailed platform-specific instructions, see the Installation pages.
3

Verify Installation

Start a new session and verify Superpowers is loaded:
Do you have superpowers?
Your agent should confirm that Superpowers is active and ready to use.
Superpowers activates automatically based on context. You don’t need special commands — just start working!

​
Your First Workflow

Let’s build a simple feature using Superpowers to see the workflow in action.
1

Start with an Idea

Tell your agent what you want to build:
Let's build a simple todo list app
What happens: The brainstorming skill activates automatically. Instead of jumping into code, your agent will:
  • Ask clarifying questions about your requirements
  • Explore your project context
  • Propose 2-3 different approaches with trade-offs
  • Present a design for your approval
The brainstorming skill prevents wasted work by ensuring you and your agent are aligned before any code is written.
2

Review and Approve the Design

Your agent will present the design in digestible sections:
## Architecture
We'll use vanilla JavaScript with a simple store pattern...

## Components
- TodoInput: Handles new todo creation
- TodoList: Renders the todo items
- TodoItem: Individual todo with complete/delete actions

## Data Model
interface Todo {
  id: string;
  text: string;
  completed: boolean;
}

Does this look right so far?
After you approve, the design gets saved to docs/plans/YYYY-MM-DD-todo-app-design.md and committed.
3

Review the Implementation Plan

The writing-plans skill automatically creates a detailed implementation plan:
## Task 1: Set up project structure
- Create index.html, main.js, styles.css
- Verify: Files exist and are empty
- Time: 2 minutes

## Task 2: Write TodoItem tests
- Test: Creating a todo item
- Test: Toggling completion
- Test: Deleting a todo
- Verify: Tests fail (no implementation yet)
- Time: 3 minutes

## Task 3: Implement TodoItem
- Write minimal code to pass tests
- Verify: All TodoItem tests pass
- Time: 4 minutes
...
Each task is bite-sized (2-5 minutes) with clear verification steps.
4

Execute with TDD

As implementation begins, test-driven-development enforces the RED-GREEN-REFACTOR cycle:
  1. RED: Write a failing test first
  2. Verify: Run tests to confirm it fails
  3. GREEN: Write minimal code to pass
  4. Verify: Run tests to confirm it passes
  5. Commit: Save progress
If you write code before the test, TDD requires you to delete it and start over. This ensures tests actually validate behavior.
5

Review and Finish

Between tasks, requesting-code-review validates:
  • Spec compliance (does it match the plan?)
  • Code quality (is it maintainable?)
  • Test coverage (are tests meaningful?)
When all tasks complete, finishing-a-development-branch helps you:
  • Run final test verification
  • Choose merge strategy (merge, PR, keep branch, discard)
  • Clean up worktrees

​
What Just Happened?

You experienced the core Superpowers workflow:
  1. brainstorming — Design before code
  2. writing-plans — Break work into tasks
  3. test-driven-development — Tests first, always
  4. requesting-code-review — Validate as you go
  5. finishing-a-development-branch — Clean completion
All of this happened automatically based on context. No special commands required.

​
Next Steps

Core Concepts

Understand how Superpowers workflows enforce best practices

Skills Library

Explore all available skills and when they activate

Test-Driven Development

Deep dive into the RED-GREEN-REFACTOR cycle

Systematic Debugging

Learn the 4-phase root cause analysis process

​
Common Questions

No! Skills activate automatically based on context. For example, if you say “let’s build a feature”, the brainstorming skill activates. If you say “fix this bug”, systematic-debugging activates.The agent checks for relevant skills before every action.
Superpowers enforces TDD for all production code — no exceptions. “Simple” changes are where untested assumptions cause the most problems.If you’re prototyping or generating throwaway code, discuss with your agent first.
Skills are designed to prevent common mistakes and enforce proven practices. If a workflow feels unnecessary, that’s often a sign it’s most needed.However, you can always discuss concerns with your agent. Some skills are rigid (TDD, debugging), others are flexible (patterns).
Claude Code / Cursor:
/plugin update superpowers
Codex / OpenCode:
cd ~/.codex/superpowers  # or ~/.config/opencode/superpowers
git pull
Skills update automatically through the symlink.

​
Get Help

GitHub Issues

Report bugs or request features

Read the Blog

Learn about the philosophy behind Superpowers

Build docs developers (and LLMs) love

Get started for freeTalk to us