# Start Here — The Superpowers Methodology

> Introduction to the Superpowers mental model: a transition from ad-hoc coding to a structured, evidence-based development cycle that prioritizes design before implementation.

- Repository: obra/superpowers
- GitHub: https://github.com/obra/superpowers
- Human wiki: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85
- Complete Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/llms-full.txt

## Source Files

- `README.md`
- `skills/using-superpowers/SKILL.md`
- `AGENTS.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [skills/using-superpowers/SKILL.md](skills/using-superpowers/SKILL.md)
- [AGENTS.md](AGENTS.md)
- [skills/brainstorming/SKILL.md](skills/brainstorming/SKILL.md)
- [skills/writing-plans/SKILL.md](skills/writing-plans/SKILL.md)
- [skills/test-driven-development/SKILL.md](skills/test-driven-development/SKILL.md)
- [skills/systematic-debugging/SKILL.md](skills/systematic-debugging/SKILL.md)
</details>

# Start Here — The Superpowers Methodology

Superpowers is more than a collection of tools; it is a complete software development methodology designed specifically for coding agents. It facilitates a fundamental transition from ad-hoc, "guess-and-check" coding to a structured, evidence-based development cycle that prioritizes deep design and rigorous verification over immediate implementation.

By adopting the Superpowers mental model, agents stop jumping directly into code. Instead, they step back to define intent, establish a shared understanding of the problem with their human partner, and follow a disciplined execution path that ensures high-quality, maintainable results.

Sources: [README.md:1-19](README.md#L1-L19), [skills/using-superpowers/SKILL.md:42-47](skills/using-superpowers/SKILL.md#L42-L47)

## The Core Philosophy

The methodology is built upon four pillar principles that guide every interaction and technical decision:

| Principle | Description |
| :--- | :--- |
| **Test-Driven Development** | Write tests first, always. If you didn't watch it fail, you didn't verify the test. |
| **Systematic over Ad-hoc** | Follow established processes rather than guessing or taking "shortcuts." |
| **Complexity Reduction** | Simplicity is the primary goal; avoid over-engineering (YAGNI). |
| **Evidence over Claims** | Verify success through concrete evidence (tests/logs) before declaring completion. |

Sources: [README.md:198-204](README.md#L198-L204), [skills/test-driven-development/SKILL.md:7-10](skills/test-driven-development/SKILL.md#L7-L10)

## The Superpowers Development Cycle

The development cycle follows a linear, gated progression from idea to completion.

```mermaid
stateDiagram-v2
    [*] --> Brainstorming: User Request
    Brainstorming --> Worktree: Approved Design
    Worktree --> Planning: Project Setup
    Planning --> Implementation: Approved Plan
    state Implementation {
        direction LR
        TDD --> Review: Task Complete
        Review --> TDD: Feedback
    }
    Implementation --> Finishing: All Tasks Done
    Finishing --> [*]: Merge/PR
```

Sources: [README.md:154-169](README.md#L154-L169)

## Phases of the Methodology

### 1. Socratic Design (Brainstorming)
Before a single line of code is written, the agent must engage in Socratic design. This involves asking clarifying questions to tease out a full specification, exploring alternatives, and presenting the design in digestible chunks for user approval. There is a **Hard Gate** on this phase: implementation skills cannot be invoked until the user signs off on the design.

Sources: [README.md:156-157](README.md#L156-L157), [skills/brainstorming/SKILL.md:14-19](skills/brainstorming/SKILL.md#L14-L19)

### 2. Task Atomicity (Planning)
Once the design is approved, work is broken down into bite-sized tasks, typically 2-5 minutes each. These plans must be explicit enough for an engineer with zero project context to follow, including exact file paths, complete code snippets, and specific verification steps.

Sources: [README.md:160-161](README.md#L160-L161), [skills/writing-plans/SKILL.md:7-12](skills/writing-plans/SKILL.md#L7-L12)

### 3. Disciplined Implementation (TDD)
Implementation follows the strict Red-Green-Refactor cycle. Agents write a failing test, watch it fail to ensure validity, and then write the minimal code necessary to pass. Any code written before its corresponding test is considered technical debt and should be deleted.

Sources: [README.md:164-165](README.md#L164-L165), [skills/test-driven-development/SKILL.md:7-15](skills/test-driven-development/SKILL.md#L7-L15)

### 4. Systematic Debugging
When bugs or unexpected behaviors occur, the **Iron Law** applies: no fixes are attempted without a root-cause investigation first. Symptom fixes are treated as failures; the methodology demands finding and fixing the underlying cause to prevent regression.

Sources: [README.md:179-181](README.md#L179-L181), [skills/systematic-debugging/SKILL.md:12-20](skills/systematic-debugging/SKILL.md#L12-L20)

## Skill Discipline and Rationalizations

The most critical rule in Superpowers is the **1% Rule**: If there is even a 1% chance a skill might apply, it **MUST** be invoked. Skills represent the distilled wisdom of the methodology, and bypassing them is the most common cause of "slop" PRs.

### Red Flags: Avoiding Rationalization
Agents must watch for internal rationalizations that lead to skipping workflows:

- *"This is just a simple question"* → Questions are tasks. Check for skills.
- *"I need more context first"* → Skill check comes **BEFORE** clarifying questions.
- *"The skill is overkill"* → Simple things become complex; use the process.
- *"This feels productive"* → Undisciplined action wastes time; skills provide discipline.

Sources: [skills/using-superpowers/SKILL.md:10-16](skills/using-superpowers/SKILL.md#L10-L16), [skills/using-superpowers/SKILL.md:78-96](skills/using-superpowers/SKILL.md#L78-L96)

## Hierarchy of Authority

Superpowers operates under a strict hierarchy of instructions to ensure the user remains in control while maintaining methodology standards:

1.  **User's explicit instructions** (e.g., AGENTS.md, direct requests) — Highest priority.
2.  **Superpowers skills** — Overrides default behavior where they conflict.
3.  **Default system prompt** — Lowest priority.

Sources: [skills/using-superpowers/SKILL.md:18-27](skills/using-superpowers/SKILL.md#L18-L27)

## Summary

The Superpowers Methodology transforms agent behavior from reactive coding to proactive engineering. By enforcing a rigorous cycle of design, planning, and test-driven implementation, it protects the human partner from low-quality "slop" and ensures that every contribution is a result of intentional, verified effort.

Sources: [AGENTS.md:3-19](AGENTS.md#L3-L19)