Superpowers: Agentic Framework for Coding Agents That Actually Work

Introduction

Have you ever used an AI coding assistant like Claude Code or Cursor, but the results were messy? The code it writes doesn't match expectations, testing gets ignored, or it even makes your project more complicated? You're not alone.

Superpowers is here as the solution. This is not just another plugin—it is an agentic skills framework that changes how coding agents work. Instead of immediately writing code when asked, an agent with Superpowers will:

1. Ask first what you actually want to build
2. Help you create clear specifications
3. Create a detailed implementation plan
4. Execute with a strict TDD methodology
5. Review its own code before giving it to you

The result? A coding agent that works like a disciplined senior engineer, not a junior who rushes to run code.

Fun fact: Superpowers has already been starred 93.9k+ times on GitHub and forked 7.4k+ times. This isn't a small project—this is a proven methodology!

---

Prerequisites

Before starting, make sure you have:

• Supported coding agents:
  • Claude Code (CLI from Anthropic)
  • Cursor (IDE with AI)
  • OpenAI Codex
  • OpenCode
  • Gemini CLI
• Git installed on your system
• Basic understanding of TDD (Test-Driven Development)
• A project you want to work on

---

Core Concepts

What are "Skills" in Superpowers?

Think of skills as "work guides" that are automatically activated when the agent detects a certain context. Similar to a checklist that must be followed before moving to the next stage.

Example: When you ask the agent to "build a new feature", the brainstorming skill will activate automatically and start asking about implementation details instead of coding immediately.

Superpowers Main Workflow

[IDEA] → [BRAINSTORMING] → [DESIGN DOC] → [PLAN] → [IMPLEMENT] → [REVIEW] → [FINISH]
            ↓                  ↓            ↓           ↓            ↓          ↓
         Questions        Validated      Tasks       TDD         Quality     Merge/PR
         & Options        Document       List        Cycle       Check       Options

Superpowers Philosophy

There are 4 core principles:

1. Test-Driven Development - Tests first, always
2. Systematic over Ad-hoc - Process, not guessing
3. Complexity Reduction - Simplicity as the main goal
4. Evidence over Claims - Verify before claiming success

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     SUPERPOWERS FRAMEWORK                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ PLANNING    │  │ CODING      │  │ QUALITY     │             │
│  │ SKILLS      │  │ SKILLS      │  │ SKILLS      │             │
│  ├─────────────┤  ├─────────────┤  ├─────────────┤             │
│  │ brainstorming│  │ test-driven │  │ requesting- │             │
│  │ writing-     │  │ development │  │ code-review │             │
│  │ plans        │  │ executing-  │  │ systematic- │             │
│  │ using-git-   │  │ plans       │  │ debugging   │             │
│  │ worktrees    │  │ subagent-   │  │ verification│             │
│  └─────────────┘  │ driven-dev  │  │ -before-    │             │
│                   └─────────────┘  │ completion  │             │
│                                    └─────────────┘             │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   META SKILLS                            │   │
│  │  writing-skills | using-superpowers                      │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌─────────────────────────────────────────┐
        │         SUPPORTED PLATFORMS              │
        ├─────────────────────────────────────────┤
        │  Claude Code │ Cursor │ Codex │ Gemini │
        └─────────────────────────────────────────┘

---

Step-by-Step: Installing Superpowers

1. Claude Code (Official Marketplace)

The easiest way for Claude Code:

/plugin install superpowers@claude-plugins-official

Or via marketplace:

# Register marketplace dulu
/plugin marketplace add obra/superpowers-marketplace

# Install plugin
/plugin install superpowers@superpowers-marketplace

2. Cursor IDE

In Cursor Agent chat:

/add-plugin superpowers

Or search for "superpowers" in the Cursor plugin marketplace.

3. OpenAI Codex

Tell Codex:

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

4. OpenCode

Same as Codex:

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

5. Gemini CLI

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

To update:

gemini extensions update superpowers

---

Step-by-Step: Using Superpowers

Scenario: Building a New Feature

Let's look at a concrete example. Suppose you want to add a "user authentication" feature to your app.

Step 1: Start with a Normal Request

User: Help me add user authentication to my Express.js app

Instead of writing code immediately, an agent with Superpowers will activate the brainstorming skill:

Agent: Before I start coding, I want to understand what you really need.

1. What authentication method do you prefer? (JWT, Session, OAuth?)
2. Do you need social login? (Google, GitHub, etc.)
3. Should users be able to reset passwords?
4. Any specific security requirements?

This is Socratic design refinement—the agent helps you think through details that might be missed.

Step 2: Design Document

After discussion, the agent will create a design document and present it in easy-to-read chunks:

## Authentication Design

### Chosen Approach
- JWT-based authentication
- Password hashing with bcrypt
- Email verification flow

### API Endpoints
- POST /auth/register
- POST /auth/login
- POST /auth/logout
- POST /auth/refresh-token

### Security Measures
- Rate limiting on login
- Secure password storage
- Token expiration (15 min access, 7 days refresh)

Step 3: Implementation Plan

After you approve the design, the writing-plans skill activates:

## Implementation Plan

### Task 1: Setup Dependencies
- Install jsonwebtoken, bcryptjs
- Add types for TypeScript
- **Verification**: npm install succeeds, types resolve

### Task 2: Create User Model
- File: src/models/User.ts
- Fields: email, passwordHash, verified, createdAt
- **Verification**: TypeScript compiles

### Task 3: Write Auth Service Tests
- File: src/services/auth.test.ts
- Test cases: register, login, token refresh
- **Verification**: Tests FAIL (expected, TDD!)

### Task 4: Implement Auth Service
- File: src/services/auth.ts
- Implement all methods
- **Verification**: Tests PASS

[... dan seterusnya]

Notice: every task has a clear verification step.

Step 4: Subagent-Driven Development

When you say "go", the subagent-driven-development skill activates:

1. Spawn a subagent for Task 1
2. Review the result (spec compliance + code quality)
3. If OK, continue to Task 2
4. If there is an issue, fix it first

The agent can work 2+ hours autonomously without deviating from the plan!

Step 5: Code Review

Between tasks, the requesting-code-review skill activates automatically:

## Code Review Report

### Task 3: Auth Service Tests

✅ Spec Compliance: All test cases match design
✅ Code Quality: Good coverage (95%)

### Issues Found:
- ⚠️ Minor: Missing edge case for empty email
- ⚠️ Minor: Should test concurrent login attempts

### Verdict: PASS with minor fixes

Step 6: Finishing Branch

After all tasks are complete, the finishing-a-development-branch skill activates:

All tasks completed! Tests passing. Here are your options:

1. Merge to main
2. Create Pull Request
3. Keep branch for review
4. Discard changes

What would you like to do?

---

Deep Dive: Key Skills

Test-Driven Development (TDD)

Superpowers enforces the RED-GREEN-REFACTOR cycle:

// Step 1: RED - Write failing test
describe('AuthService', () => {
  it('should register new user', async () => {
    const result = await authService.register({
      email: 'test@example.com',
      password: 'SecurePass123!'
    });
    expect(result.user).toBeDefined();
    expect(result.token).toBeDefined();
  });
});

// Run test → FAIL (method doesn't exist yet)

// Step 2: GREEN - Write minimal code to pass
async register(userData) {
  const user = await this.userRepo.create(userData);
  const token = this.generateToken(user);
  return { user, token };
}

// Run test → PASS

// Step 3: REFACTOR - Improve code quality
// Add validation, error handling, etc.

Anti-patterns that are avoided:

• Writing code before tests
• Skipping tests "because you're already sure"
• Tests that are not independent

Systematic Debugging

When there's a bug, the systematic-debugging skill activates with a 4-phase process:

Phase 1: REPRODUCE
- Document exact steps to trigger bug
- Verify it's not environment-specific

Phase 2: ISOLATE
- Binary search the codebase
- Create minimal reproduction case

Phase 3: ROOT CAUSE
- Trace the execution flow
- Identify exact point of failure

Phase 4: FIX & VERIFY
- Implement fix
- Add regression test
- Verify fix works
- Check no side effects

Git Worktrees for Parallel Development

The using-git-worktrees skill lets you work on multiple features at once:

# Main repo: /project
# Feature A: /project/.worktrees/feature-auth
# Feature B: /project/.worktrees/feature-api

# Masing-masing punya branch terpisah
# Tidak ada conflict antar development

---

Best Practices

1. Let the Agent Ask Questions

Don't answer with "just code it". The more detailed the brainstorming, the better the result.

2. Review the Design Document

Take time to read the design doc. It's easier to correct at this stage than after code is written.

3. Trust the Process

TDD may feel slow at first, but bugs prevented during development are cheaper than bugs in production.

4. Regular Checkpoints

For large projects, use executing-plans with checkpoints:

"Execute the plan with checkpoints after every 5 tasks"

5. Custom Skills

You can create your own skills! See skills/writing-skills/SKILL.md in the Superpowers repo.

---

Common Mistakes

❌ Mistake 1: Skipping Brainstorming

User: Just implement authentication, don't ask questions

Result: Code that doesn't match requirements, needs rewrite.

Solution: Always follow the brainstorming process.

❌ Mistake 2: Ignoring Test Failures

Agent: Test failed. Should I fix it?
User: Skip for now, I'll fix later

Result: Technical debt that keeps piling up.

Solution: Always fix test failures before continuing.

❌ Mistake 3: Not Reading the Plan

Agent: Here's the implementation plan [long document]
User: Looks good, go ahead

Result: Surprises when the result doesn't match expectations.

Solution: Read the plan in detail. Request changes if needed.

❌ Mistake 4: Working on the Main Branch

User: Let's implement this directly on main

Result: No rollback path if something goes wrong.

Solution: Use worktrees or at least a separate branch.

---

Advanced Tips

Parallel Agent Dispatch

For independent tasks, use the dispatching-parallel-agents skill:

"Implement tasks 1-5 in parallel with separate subagents"

This leverages parallel processing to accelerate development.

Custom Skill Creation

Create skills for patterns you use often:

# skills/my-custom-pattern/SKILL.md

## Trigger
When user asks to implement a new API endpoint

## Steps
1. Check if route exists
2. Validate request schema
3. Write integration test
4. Implement handler
5. Add API documentation

Integration with CI/CD

Superpowers can be integrated with the CI pipeline:

# .github/workflows/superpowers-check.yml
name: Superpowers Quality Check
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Superpowers Review
        run: |
          # Agent akan melakukan code review otomatis
          # dengan standar Superpowers

---

Summary & Next Steps

Key Takeaways

1. Superpowers = Framework + Methodology - Not just a plugin, but a new way of working
2. Skills Auto-Activate - The agent knows when to use which skill
3. TDD is Mandatory - Tests first, always
4. Human in the Loop - Checkpoints for approval at every important stage
5. Works Everywhere - Claude Code, Cursor, Codex, Gemini

Next Steps

1. Install Superpowers in your favorite coding agent
2. Try a small feature to experience the workflow
3. Explore the skills library in the GitHub repo
4. Join the community on Discord
5. Create your own skills for patterns you use often

---

References

• GitHub Repository: https://github.com/obra/superpowers
• Official Blog Post: https://blog.fsck.com/2025/10/09/superpowers/
• Discord Community: https://discord.gg/Jd8Vphy9jq
• Marketplace: https://github.com/obra/superpowers-marketplace
• License: MIT

---

Superpowers is built by Jesse Vincent and the team at Prime Radiant.