Superpowers

Overview

Superpowers is a complete software development methodology that provides AI agents with a structured, repeatable workflow. Ported from the obra/superpowers project, it breaks down the software development process into 7 core phases, each with dedicated skills and checkpoints to ensure high-quality, maintainable code output.

Core Workflow

Superpowers follows a strict 7-phase workflow. Each phase is mandatory and cannot be skipped:

1. Brainstorming

Trigger: Automatically activates at the start of any development task. Goal: Clarify the user's real needs through questioning, explore alternatives, and produce a verifiable design document. Key Actions:

Ask what the user really wants to achieve (not just surface requirements)
Explore multiple design approaches and trade-offs
Break design into readable chunks (max 200 words each)
Generate design document and save to design.md
Get user sign-off on the design

2. Design Validation

Trigger: After Brainstorming completes. Goal: Ensure the design is complete, feasible, and meets user expectations. Key Actions:

Present design chunks for user review
Ask "Is this section clear?"
Confirm technical feasibility and constraints
Record feedback and update design

3. Implementation Planning

Trigger: After design validation passes. Goal: Decompose the design into executable, fine-grained development tasks. Key Actions:

Create detailed task list, each task taking 2-5 minutes
Each task includes: exact file paths, complete code, verification steps
Follow YAGNI (You Aren't Gonna Need It) and DRY (Don't Repeat Yourself)
Generate plan document and save to plan.md

4. Test-Driven Development (TDD)

Trigger: Automatically activates during implementation. Goal: Enforce the Red-Green-Refactor cycle. Key Actions:

Write a failing test first (Red)
Write minimal code to pass the test (Green)
Refactor to keep code clean
Delete any code written before tests
Follow this cycle for every feature

5. Subagent-Driven Development

Trigger: After plan approval. Goal: Use subagents to execute tasks in parallel or sequentially. Key Actions:

Create fresh subagent per task
Two-stage review: spec compliance, then code quality
Set human checkpoints during batch execution
Stop and report immediately if subagent deviates from plan

6. Code Review

Trigger: Between tasks or upon completion. Goal: Ensure code meets plan and quality standards. Key Actions:

Review code against the plan
Report issues by severity: Critical (blocking), Major, Minor
Critical issues must be fixed before proceeding
Generate review report and save to review.md

7. Finishing Development Branch

Trigger: After all tasks complete. Goal: Cleanly finish the development cycle. Key Actions:

Verify all tests pass
Present options: merge, create PR, keep branch, discard
Clean up workspace
Generate final report

Core Principles

1. Test-Driven Development

Always write tests first
Red-Green-Refactor cycle
Tests serve as documentation and design tools

2. Systematic over Ad-Hoc

Follow process rather than guessing
Every decision has a rationale
Document all assumptions and decisions

3. Complexity Reduction

Simplicity is the primary goal
Remove unnecessary code
Prefer the simplest viable solution

4. Evidence over Claims

Verify rather than declare success
Use tests to prove functionality
Use data to support decisions

Skill Trigger Mechanism

Superpowers is a mandatory workflow, not an optional suggestion. When any of the following is detected, the corresponding skill must activate:

User mentions development/programming -> Start Brainstorming
Design complete -> Start Implementation Planning
Starting to write code -> Start TDD
Tasks need parallelism -> Start Subagent-Driven Development
Code complete -> Start Code Review
Project complete -> Start Finishing

Deliverables

Each phase produces documentation to ensure traceability:

| Phase | Output File | Purpose | |-------|------------|---------| | Brainstorming | design.md | Complete design document | | Planning | plan.md | Detailed implementation plan | | Development | code/ | Source code | | Review | review.md | Code review report | | Finish | final_report.md | Project summary |

Example Workflow

User Request: "Build me a todo app"

Brainstorming: Ask about requirements (Web/Mobile? Auth needed? Data storage?)
Design: Generate UI design, architecture diagram, API design
Planning: Break down into: create project structure, implement auth, build CRUD, add frontend
TDD: Write tests for each feature first
Subagent: Dispatch subagents to develop different modules in parallel
Review: Review code quality of each module
Finish: Merge code, generate deployment docs

Troubleshooting

Issue: Subagent deviates from plan Solution: Stop immediately, analyze the deviation, adjust plan or re-dispatch

Issue: Tests failing Solution: Return to Red phase, analyze failure cause, fix tests or code

Issue: Requirements change Solution: Return to Brainstorming phase, re-evaluate design

Reference Resources

For detailed workflow guides and best practices, see references/workflow.md and references/best_practices.md.

Resources

This skill includes bundled resource directories for organizing different types of content:

scripts/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Examples from other skills:

PDF skill: fill_fillable_fields.py, extract_form_field_info.py - utilities for PDF manipulation
DOCX skill: document.py, utilities.py - Python modules for document processing

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

references/

Documentation and reference material intended to be loaded into context to inform the agent's process and thinking.

Examples from other skills:

Product management: communication.md, context_building.md - detailed workflow guides
BigQuery: API reference documentation and query examples
Finance: Schema documentation, company policies

Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information to reference while working.

assets/

Files not intended to be loaded into context, but rather used within the output produced.

Examples from other skills:

Brand styling: PowerPoint template files (.pptx), logo files
Frontend builder: HTML/React boilerplate project directories
Typography: Font files (.ttf, .woff2)

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

Any unneeded directories can be deleted. Not every skill requires all three types of resources.