Quickstart

Get up and running with Superpowers in 5 minutes

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:

   Claude Code

   # Register the marketplace
   /plugin marketplace add obra/superpowers-marketplace
   
   # Install Superpowers
   /plugin install superpowers@superpowers-marketplace
   

   # Install from marketplace
   /plugin-add superpowers
   

   # Clone the repository
   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
   
   # Create skills symlink
   mkdir -p ~/.agents/skills
   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
   
   # Restart Codex
   

   # Clone the repository
   git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
   
   # Create plugin symlink
   mkdir -p ~/.config/opencode/plugins
   ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
   
   # Create skills symlink
   mkdir -p ~/.config/opencode/skills
   ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
   
   # Restart OpenCode
   

   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

Do I need to manually invoke skills?

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.

Can I skip TDD for simple changes?

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.

What if I disagree with a skill's workflow?

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).

How do I update Superpowers?

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