superpowers

Superpowers

A structured software development framework that transforms how coding agents approach development—preventing the "write code immediately" antipattern.

When to Use This Skill

• Complex feature development
• Multi-file refactoring
• Test-driven development
• Code review processes
• Systematic debugging
• Team collaboration with AI

The Philosophy

Traditional AI coding:

User: "Add auth to the app"
AI: *immediately writes 500 lines of code*

Superpowers approach:

User: "Add auth to the app"
AI: "Let me understand requirements first..."
   → Questions → Design → Plan → Execute → Review

Core Workflow

Phase 1: Understanding

1. Ask clarifying questions
2. Explore existing codebase
3. Understand constraints
4. Validate assumptions

Phase 2: Design

1. Create isolated workspace (git branch)
2. Break work into 2-5 minute tasks
3. Define exact specifications
4. Get approval before coding

Phase 3: Execution

1. RED: Write failing test
2. GREEN: Minimum code to pass
3. REFACTOR: Clean up
4. Review before next task

Phase 4: Review

1. Specification compliance check
2. Code quality review
3. Integration verification
4. Branch completion decision

Key Principles

1. Design Before Code

Never write code without understanding:

• What problem are we solving?
• What are the constraints?
• How does it fit existing code?
• What are the edge cases?

2. Small, Focused Tasks

Each task should be:

• Completable in 2-5 minutes
• Single responsibility
• Independently testable
• Clear success criteria

3. Test-First Development

RED → GREEN → REFACTOR

• Write test first
• Minimum code to pass
• Clean up afterward
• Never skip this cycle

4. Systematic, Not Ad-hoc

┌─────────────────────────────────────┐
│ Systematic          vs.    Ad-hoc  │
├─────────────────────────────────────┤
│ Plan then execute   │ Jump in      │
│ Verify with tests   │ Hope it works│
│ Review each step    │ Review at end│
│ Evidence-based      │ Assumption   │
└─────────────────────────────────────┘

5. Evidence Over Assumption

• Don't assume code works—verify
• Don't assume understanding—validate
• Don't assume completion—prove

Skills Library

Testing

• Unit test patterns
• Integration testing
• Test coverage analysis
• Mocking strategies

Debugging

1. Reproduce the issue
2. Isolate the cause
3. Root cause analysis
4. Verify the fix
5. Prevent regression

Collaboration

• Brainstorming: Explore options
• Planning: Structure approach
• Parallel execution: Multiple agents
• Review: Quality gates

Meta-Skills

• Extending the framework
• Custom skill creation
• Workflow optimization

How to Use

Starting a Feature

I want to add user authentication.

Help me think through:
1. What auth mechanism?
2. Session vs JWT?
3. Where to store credentials?
4. What existing code to modify?

During Development

I'm implementing the login endpoint.

Current state:
- User model exists
- Password hashing ready

Next: Create POST /login endpoint

Tests first, then implementation.

Code Review

Review my changes:
[paste diff]

Check against:
- Original spec
- Test coverage
- Code quality
- Security concerns

Example: Adding a Feature

1. Discovery

User: "Add forgot password feature"

Agent: "Before we start, let me understand:
1. How should the reset link be delivered? (email?)
2. What's the token expiry? (1 hour?)
3. Should we rate limit attempts?
4. Any existing email infrastructure?"

2. Planning

Tasks:
1. Create password_reset_tokens table
2. Add POST /forgot-password endpoint
3. Add POST /reset-password endpoint
4. Create email template
5. Add rate limiting middleware

3. Execution (Task 1)

## Task: Create password_reset_tokens table

### Test (RED)
- Test migration creates table
- Test table has correct columns

### Implementation (GREEN)
- Create migration file
- Define schema

### Verify
- Run migration
- Check table exists

4. Review

## Task 1 Complete

✓ Migration runs successfully
✓ Table has: id, user_id, token, expires_at
✓ Foreign key constraint works

Ready for Task 2?

Best Practices

1. Don't Rush: Speed comes from fewer mistakes
2. Ask Questions: Clarify before implementing
3. Small Steps: Easier to verify and debug
4. Test Everything: Trust comes from evidence
5. Review Often: Catch issues early

Integration

Available for:

• Claude Code: Via marketplace
• Codex: Plugin installation
• OpenCode: Direct integration

Anti-Patterns to Avoid

• Writing code without understanding requirements
• Skipping tests "to save time"
• Large PRs with multiple concerns
• Assuming code works without verification
• Declaring done without evidence