Getting Started with Superpowers: Installation, Workflow, and Practical Guide

Software engineering with LLMs is undergoing a rapid transition. We are moving away from "vibe coding"—the practice of feeding unstructured prompts to an LLM and hoping for working code—and moving toward Spec-Driven Development (SDD). However, the biggest challenge in SDD isn't the tooling; it is human discipline. When deadlines loom, developers often abandon structured workflows and slide back into ad-hoc prompting.

Superpowers, developed by Jesse Vincent and the team at Prime Radiant, solves this discipline problem. Rather than leaving the software development lifecycle up to the agent or the developer's patience, Superpowers packages a full, spec-driven methodology into installable Claude Skills. It treats brainstorming, planning, subagent review, and red-green-refactor Test-Driven Development (TDD) as mandatory checkpoints that the agent must verify before making any changes. To power these demanding agentic workflows, developers need a reliable, high-speed connection to state-of-the-art models like Claude 3.5 Sonnet and DeepSeek-V3. Aggregators like n1n.ai provide the robust API infrastructure needed to handle the high volume of parallel requests these agent workflows generate.

Why Claude 3.5 Sonnet and Superpowers Solve the Vibe Coding Problem

Most hand-rolled Claude Code setups fail because they rely on the developer to manually invoke planning or testing steps. Superpowers changes this by utilizing a bootstrap instruction that forces the agent to check for relevant skills before starting any task. This ensures the workflow activates automatically, regardless of the prompt you enter.

Superpowers operates on four core principles:

1. Test-Driven Development (TDD): Write tests first, always. Code written without a failing test is deleted.
2. Systematic over Ad-Hoc: Rely on a structured process rather than guessing.
3. Complexity Reduction: Prioritize simplicity as the primary design goal.
4. Evidence over Claims: Verify code execution before declaring success.

Unlike repo-local skills, Superpowers is distributed as a plugin package compatible with multiple agent harnesses. This portability means your development methodology remains consistent whether you are working in Claude Code, Cursor, or a CLI-based agent.

Multi-Agent Installation and Setup

Superpowers must be installed separately for each agent harness you use. There is no single global installation. Depending on your tool of choice, use the corresponding command below:

Critical Harness-Specific Details

• Antigravity: Runs the plugin's session-start hook automatically. Reinstalling with the same command updates the package.
• Pi: Loads skills through a small extension that injects the using-superpowers bootstrap at startup and after context compaction. It does not require Pi's compatibility Skill tool.
• Hermes Agent: Lacks a post-compaction hook. If a long session undergoes context compaction, the bootstrap instructions may be lost. If skills stop triggering, start a fresh session.
• OpenCode: Treats the installation as completely separate from other harnesses on the same machine. Follow the instructions in .opencode/INSTALL.md within the repository.

To verify that the installation succeeded, start your agent and run the discovery command:

What skills are available?

If configured correctly, the agent will list skills such as brainstorming, writing-plans, test-driven-development, and subagent-driven-development.

The Seven-Step Core Workflow

Superpowers structures development into a linear, seven-step pipeline. Each skill hands off control to the next:

[brainstorming]
       │
       ▼
[using-git-worktrees]
       │
       ▼
[writing-plans]
       │
       ▼
[subagent-driven-development] OR [executing-plans]
       │
       ▼
[test-driven-development]
       │
       ▼
[requesting-code-review]
       │
       ▼
[finishing-a-development-branch]

1. Brainstorming

Activates before any code is written. It refines your prompt by asking clarifying questions, exploring architectural alternatives, and breaking down the design into short, reviewable chunks. The output is saved as a design artifact.

2. Using Git Worktrees

Once you approve the design, this skill creates an isolated workspace on a new Git branch. It runs your project's setup commands and verifies that the existing test suite passes, establishing a clean baseline.

3. Writing Plans

Breaks the design artifact into small, bite-sized tasks. Superpowers targets an aggressive granularity of 2 to 5 minutes of work per task. Each task must specify exact file paths, code changes, and explicit verification steps.

4. Subagent-Driven Development / Executing Plans

Dispatches a separate subagent for each task. The subagent operates in an isolated context to prevent context drift. It uses a two-stage review process: first verifying spec compliance, then evaluating code quality.

5. Test-Driven Development (TDD)

Enforces a strict red-green-refactor cycle. The agent must write a failing test, verify the failure, write the minimal implementation code to make the test pass, and commit the changes. If implementation code is written before a failing test exists, Superpowers prompts the agent to delete the code and start over.

6. Requesting Code Review

Runs between tasks. It analyzes the git diff against the plan and categorizes issues by severity. Critical issues block the workflow and must be resolved before proceeding to the next task.

7. Finishing a Development Branch

Runs after all tasks are complete. It verifies that the entire test suite passes, offers options to merge or open a Pull Request, and cleans up the temporary Git worktree.

Step-by-Step Implementation: Adding API Rate Limiting

To see Superpowers in action, let's walk through implementing a rate-limiting middleware for a Python FastAPI application. We will use a setup powered by the n1n.ai API gateway to query Claude 3.5 Sonnet.

Step 1: Initiating the Task

Start the agent session and provide the initial prompt:

I want to add rate limiting to our public API endpoints.

Instead of writing code immediately, the brainstorming skill intercepts the prompt and asks:

1. What is the rate limit threshold (e.g., 100 requests per minute)?
2. Should we identify users by IP address, API key, or JWT token?
3. What status code and payload should be returned when the limit is exceeded?

Provide your answers:

Limit to 60 requests per minute per IP. Return HTTP 429 Too Many Requests with a JSON body: {"error": "Rate limit exceeded"}.

Step 2: The Plan

The writing-plans skill generates a plan file (.plans/rate_limiting.md):

# Plan: API Rate Limiting

- [ ] Task 1: Create a rate limiting utility class using an in-memory dictionary.
  - Verification: Run pytest on tests/test_rate_limiter.py
- [ ] Task 2: Implement FastAPI middleware that applies the rate limiter to all routes.
  - Verification: Run integration tests simulating rate limit breaches.

Step 3: TDD Execution (Task 1)

The subagent is dispatched to write the test first. It creates tests/test_rate_limiter.py:

import pytest
import time
from utils.rate_limiter import InMemoryRateLimiter

def test_rate_limiter_allows_under_limit():
    limiter = InMemoryRateLimiter(limit=5, window=60)
    ip = "192.168.1.1"
    for _ in range(5):
        assert limiter.is_allowed(ip) is True

def test_rate_limiter_blocks_over_limit():
    limiter = InMemoryRateLimiter(limit=5, window=60)
    ip = "192.168.1.1"
    for _ in range(5):
        limiter.is_allowed(ip)
    assert limiter.is_allowed(ip) is False

The agent runs the test suite. The tests fail because utils/rate_limiter does not exist yet (Red phase).

Next, the agent implements the minimal code in utils/rate_limiter.py:

import time
from collections import defaultdict

class InMemoryRateLimiter:
    def __init__(self, limit: int, window: int):
        self.limit = limit
        self.window = window
        self.requests = defaultdict(list)

    def is_allowed(self, ip: str) -> bool:
        now = time.time()
        # Filter out requests outside the current time window
        self.requests[ip] = [t for t in self.requests[ip] if now - t < self.window]

        if len(self.requests[ip]) < self.limit:
            self.requests[ip].append(now)
            return True
        return False

The agent runs the tests again. They pass (Green phase). The agent commits the progress.

Step 4: Middleware Integration (Task 2)

The agent writes integration tests for the FastAPI middleware, verifies they fail, implements the middleware, and verifies they pass. Finally, the finishing-a-development-branch skill cleans up the worktree and prepares the branch for merging.

Supporting Skills Reference

Superpowers includes several specialized skills beyond the core development flow:

• systematic-debugging: A four-phase root cause analysis process consisting of root-cause-tracing, defense-in-depth, and condition-based-waiting.
• dispatching-parallel-agents: Manages concurrent subagent execution. Each subagent runs in an isolated context and reports a summary back to the parent session, saving context window space.
• writing-skills: A meta-skill that allows developers to write new custom skills using Superpowers' testing and validation framework.

Tooling Comparison

When to Use Superpowers

Superpowers is highly recommended if:

• You struggle with "prompt drift" and want your agent to follow a strict planning and testing methodology automatically.
• You work across multiple environments (e.g., Cursor at home, Claude Code in the terminal) and want a consistent set of skills.
• You want automated TDD enforcement without writing custom pre-commit hooks or agent instructions yourself.
• You are managing large, multi-session tasks where architectural drift is a high risk.

You may want to skip Superpowers if:

• You are writing quick, throwaway scripts or single-file prototypes where planning overhead slows you down.
• Your team has a mature, highly customized SDD workflow that conflicts with Superpowers' strict 2-to-5-minute task sizing.

Troubleshooting and Optimization

If a skill fails to trigger during a session, perform the following troubleshooting steps:

1. Verify Discovery: Run What skills are available?. If the skills are not listed, the installation failed or the current agent harness is not loading the plugin directory.
2. Check for Context Compaction: In long sessions, some agents (like Hermes) compact their history and may discard the bootstrap instructions. Start a fresh session to restore the bootstrap.
3. Disable Telemetry: By default, the brainstorming skill loads a visual assets logo from Prime Radiant's servers, which sends your Superpowers version number. To disable this, set the environment variable:

   export SUPERPOWERS_DISABLE_TELEMETRY=true
   

   Superpowers also respects standard flags like DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.

Implementing structured agent workflows requires stable, high-throughput LLM APIs. By using an aggregator like n1n.ai, developers can leverage Claude 3.5 Sonnet, DeepSeek-V3, and other models under a single API key, ensuring that parallel subagents always have access to the compute they need.

Get a free API key at n1n.ai