Agent-readable wiki

Superpowers: The First 30 Minutes

A complete software development methodology for AI agents, built on composable skills and automatic workflows that enforce TDD, systematic debugging, and subagent orchestration.

Pages

  1. Start Here — The Superpowers MethodologyIntroduction to the Superpowers mental model: a transition from ad-hoc coding to a structured, evidence-based development cycle that prioritizes design before implementation.
  2. Cross-Harness Installation & AdaptersHow to integrate Superpowers into your preferred environment, including Claude Code, Codex, Gemini, Cursor, and OpenCode, using native plugin mechanisms.
  3. Session Bootstrap & Hook SystemUnderstanding the automatic activation layer that triggers skills at the start of every session, ensuring the agent is immediately oriented to the project's methodology.
  4. Product Discovery & Socratic DesignThe "Ideas" and "Blueprint" phase: using Socratic questioning to refine rough concepts into clear, digestible specifications before a single line of code is written.
  5. Bite-Sized Implementation PlanningThe "Plan" phase: breaking approved designs into 2-5 minute tasks, each with explicit file paths, code changes, and verification steps to ensure predictable progress.
  6. Subagent-Driven Execution & ReviewThe "Page Shape" and "QA Review" phase: dispatching specialized subagents to implement tasks with two-stage automated review for spec compliance and code quality.
  7. Parallel Development with Git WorktreesMaintaining environment isolation by creating dedicated workspaces for each branch, allowing for seamless context switching and a clean main branch.
  8. Evidence-Based Success with TDDEnforcing the RED-GREEN-REFACTOR cycle to ensure every code change is backed by a failing test first, eliminating speculative code and "slop" PRs.
  9. Systematic Root Cause AnalysisThe "Root Cause" process: a 4-phase debugging strategy that prioritizes tracing and defensive implementation over ad-hoc guessing and patch-work.
  10. Plan-Anchored Code Review & FeedbackThe final "QA Review" step: checking implementation against the original plan and spec, reporting issues by severity, and ensuring a high bar for PR acceptance.
  11. The Meta-Layer — Creating Project-Specific SkillsExtending the Superpowers methodology by writing and testing new skills that capture your own project's patterns, constraints, and tribal knowledge.
  12. Mastery & Real-World ApplicationApplying Superpowers beyond the first 30 minutes: handling legacy migrations, complex refactors, and maintaining a high-quality codebase at scale.

Complete Markdown

# Superpowers: The First 30 Minutes

> A complete software development methodology for AI agents, built on composable skills and automatic workflows that enforce TDD, systematic debugging, and subagent orchestration.

## Context Links

- [Agent index](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/llms.txt)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85)
- [GitHub repository](https://github.com/obra/superpowers)

## Repository Metadata

- Repository: obra/superpowers

- Generated: 2026-05-20T00:29:51.615Z
- Updated: 2026-05-21T21:35:33.337Z
- Runtime: Antigravity CLI
- Format: First 30 Minutes
- Pages: 12

## Page Index

- 01. [Start Here — The Superpowers Methodology](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/01-start-here-the-superpowers-methodology.md) - Introduction to the Superpowers mental model: a transition from ad-hoc coding to a structured, evidence-based development cycle that prioritizes design before implementation.
- 02. [Cross-Harness Installation & Adapters](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/02-cross-harness-installation-adapters.md) - How to integrate Superpowers into your preferred environment, including Claude Code, Codex, Gemini, Cursor, and OpenCode, using native plugin mechanisms.
- 03. [Session Bootstrap & Hook System](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/03-session-bootstrap-hook-system.md) - Understanding the automatic activation layer that triggers skills at the start of every session, ensuring the agent is immediately oriented to the project's methodology.
- 04. [Product Discovery & Socratic Design](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/04-product-discovery-socratic-design.md) - The "Ideas" and "Blueprint" phase: using Socratic questioning to refine rough concepts into clear, digestible specifications before a single line of code is written.
- 05. [Bite-Sized Implementation Planning](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/05-bite-sized-implementation-planning.md) - The "Plan" phase: breaking approved designs into 2-5 minute tasks, each with explicit file paths, code changes, and verification steps to ensure predictable progress.
- 06. [Subagent-Driven Execution & Review](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/06-subagent-driven-execution-review.md) - The "Page Shape" and "QA Review" phase: dispatching specialized subagents to implement tasks with two-stage automated review for spec compliance and code quality.
- 07. [Parallel Development with Git Worktrees](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/07-parallel-development-with-git-worktrees.md) - Maintaining environment isolation by creating dedicated workspaces for each branch, allowing for seamless context switching and a clean main branch.
- 08. [Evidence-Based Success with TDD](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/08-evidence-based-success-with-tdd.md) - Enforcing the RED-GREEN-REFACTOR cycle to ensure every code change is backed by a failing test first, eliminating speculative code and "slop" PRs.
- 09. [Systematic Root Cause Analysis](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/09-systematic-root-cause-analysis.md) - The "Root Cause" process: a 4-phase debugging strategy that prioritizes tracing and defensive implementation over ad-hoc guessing and patch-work.
- 10. [Plan-Anchored Code Review & Feedback](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/10-plan-anchored-code-review-feedback.md) - The final "QA Review" step: checking implementation against the original plan and spec, reporting issues by severity, and ensuring a high bar for PR acceptance.
- 11. [The Meta-Layer — Creating Project-Specific Skills](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/11-the-meta-layer-creating-project-specific-skills.md) - Extending the Superpowers methodology by writing and testing new skills that capture your own project's patterns, constraints, and tribal knowledge.
- 12. [Mastery & Real-World Application](https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/12-mastery-real-world-application.md) - Applying Superpowers beyond the first 30 minutes: handling legacy migrations, complex refactors, and maintaining a high-quality codebase at scale.

## Source File Index

- `.claude-plugin/plugin.json`
- `.codex-plugin/plugin.json`
- `.cursor-plugin/plugin.json`
- `AGENTS.md`
- `CLAUDE.md`
- `CODE_OF_CONDUCT.md`
- `gemini-extension.json`
- `GEMINI.md`
- `hooks/hooks-cursor.json`
- `hooks/hooks.json`
- `hooks/run-hook.cmd`
- `hooks/session-start`
- `README.md`
- `RELEASE-NOTES.md`
- `skills/brainstorming/scripts/helper.js`
- `skills/brainstorming/SKILL.md`
- `skills/brainstorming/spec-document-reviewer-prompt.md`
- `skills/brainstorming/visual-companion.md`
- `skills/dispatching-parallel-agents/SKILL.md`
- `skills/executing-plans/SKILL.md`
- `skills/finishing-a-development-branch/SKILL.md`
- `skills/receiving-code-review/SKILL.md`
- `skills/requesting-code-review/code-reviewer.md`
- `skills/requesting-code-review/SKILL.md`
- `skills/subagent-driven-development/code-quality-reviewer-prompt.md`
- `skills/subagent-driven-development/implementer-prompt.md`
- `skills/subagent-driven-development/SKILL.md`
- `skills/subagent-driven-development/spec-reviewer-prompt.md`
- `skills/systematic-debugging/condition-based-waiting.md`
- `skills/systematic-debugging/defense-in-depth.md`
- `skills/systematic-debugging/root-cause-tracing.md`
- `skills/systematic-debugging/SKILL.md`
- `skills/test-driven-development/SKILL.md`
- `skills/test-driven-development/testing-anti-patterns.md`
- `skills/using-git-worktrees/SKILL.md`
- `skills/using-superpowers/SKILL.md`
- `skills/verification-before-completion/SKILL.md`
- `skills/writing-plans/plan-document-reviewer-prompt.md`
- `skills/writing-plans/SKILL.md`
- `skills/writing-skills/anthropic-best-practices.md`
- `skills/writing-skills/persuasion-principles.md`
- `skills/writing-skills/SKILL.md`
- `skills/writing-skills/testing-skills-with-subagents.md`

---

## 01. 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.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/01-start-here-the-superpowers-methodology.md
- Generated: 2026-05-20T00:27:44.629Z

### 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)

---

## 02. Cross-Harness Installation & Adapters

> How to integrate Superpowers into your preferred environment, including Claude Code, Codex, Gemini, Cursor, and OpenCode, using native plugin mechanisms.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/02-cross-harness-installation-adapters.md
- Generated: 2026-05-20T00:24:47.538Z

### Source Files

- `README.md`
- `gemini-extension.json`
- `.claude-plugin/plugin.json`
- `.cursor-plugin/plugin.json`
- `.codex-plugin/plugin.json`

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [gemini-extension.json](gemini-extension.json)
- [.claude-plugin/plugin.json](.claude-plugin/plugin.json)
- [.cursor-plugin/plugin.json](.cursor-plugin/plugin.json)
- [.codex-plugin/plugin.json](.codex-plugin/plugin.json)
- [.opencode/plugins/superpowers.js](.opencode/plugins/superpowers.js)
- [hooks/session-start](hooks/session-start)
- [.opencode/INSTALL.md](.opencode/INSTALL.md)
</details>

# Cross-Harness Installation & Adapters

Superpowers is designed as a portable agentic skills framework that integrates natively with a wide variety of AI coding harnesses. Whether you are using Claude Code, Cursor, Gemini, or OpenCode, Superpowers provides a consistent experience by adapting its delivery mechanism to the native plugin or extension architecture of each environment.

This page details the installation procedures for supported harnesses and explains the underlying adapter logic that ensures the `using-superpowers` bootstrap is correctly injected into your agent sessions.

## Installation by Harness

Installation differs by harness. If you use multiple environments, you must install Superpowers separately for each one to ensure the appropriate native hooks are registered.

| Harness | Installation Command / Method |
| :--- | :--- |
| **Claude Code** | `/plugin install superpowers@claude-plugins-official` |
| **Cursor** | `/add-plugin superpowers` (in Agent chat) |
| **Gemini CLI** | `gemini extensions install https://github.com/obra/superpowers` |
| **Codex CLI** | `/plugins` -> search for `superpowers` -> `Install Plugin` |
| **OpenCode** | Add `superpowers@git+...` to `plugin` array in `opencode.json` |
| **Factory Droid** | `droid plugin install superpowers@superpowers` |
| **Copilot CLI** | `copilot plugin install superpowers@superpowers-marketplace` |

Sources: [README.md:35-153](), [.opencode/INSTALL.md:12-20]()

## Adapters & Session Injection

Superpowers uses a "bootstrap" mechanism to ensure the agent is aware of its capabilities as soon as a session starts. This is implemented via native hooks that inject the `using-superpowers` skill content into the initial conversation context.

### The SessionStart Hook

For most harnesses (Claude Code, Cursor, Codex), the integration relies on a `SessionStart` hook defined in the plugin manifest. This hook executes a script that detects the platform and formats the context injection according to the expected JSON schema.

```bash
# hooks/session-start snippet
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
  # Cursor sets CURSOR_PLUGIN_ROOT
  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
  # Claude Code sets CLAUDE_PLUGIN_ROOT
  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
fi
```
Sources: [hooks/session-start:46-55](), [.cursor-plugin/plugin.json:10-20]()

### OpenCode Adapter Logic

OpenCode uses a more specialized adapter implemented in Javascript. It utilizes the `experimental.chat.messages.transform` hook to inject the bootstrap into the first user message of every session. This approach avoids token bloat from repeated system messages while ensuring the agent always sees the instructions.

```javascript
// .opencode/plugins/superpowers.js
'experimental.chat.messages.transform': async (_input, output) => {
  const bootstrap = getBootstrapContent();
  if (!bootstrap || !output.messages.length) return;
  const firstUser = output.messages.find(m => m.info.role === 'user');
  if (!firstUser || !firstUser.parts.length) return;

  // Guard: skip if already injected
  if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;

  const ref = firstUser.parts[0];
  firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
}
```
Sources: [.opencode/plugins/superpowers.js:120-133]()

### Injection Sequence

The following diagram illustrates how Superpowers injects context across different platforms:

```mermaid
sequenceDiagram
    participant User
    participant Harness as Harness (Claude/Cursor/OpenCode)
    participant Plugin as Superpowers Plugin
    participant Skills as Skills Library

    User->>Harness: Starts Session
    Harness->>Plugin: Triggers SessionStart/Transform Hook
    Plugin->>Skills: Reads using-superpowers/SKILL.md
    Skills-->>Plugin: Returns bootstrap content
    Plugin-->>Harness: Returns formatted injection JSON
    Harness->>User: Agent starts with Superpowers awareness
```

## Tool Mapping for OpenCode

Because OpenCode has a different native toolset than Claude Code, the Superpowers adapter automatically maps skill-referenced tools to their OpenCode equivalents during bootstrap injection.

- `TodoWrite` is mapped to the native `todowrite` tool.
- `Task` tool subagent requests are translated to OpenCode's `@mention` syntax.
- `Skill` tool calls are redirected to OpenCode's native `skill` tool.

Sources: [.opencode/plugins/superpowers.js:76-83]()

## Summary

Superpowers maintains portability by abstracting harness-specific details into dedicated adapters and hooks. By leveraging native plugin mechanisms like Claude Code's `SessionStart` and OpenCode's message transformation hooks, Superpowers ensures that its core software development methodology is available consistently across all major AI coding platforms. For the latest installation updates and specific version pinning, refer to the [README.md:103-153]() and platform-specific manifests like [gemini-extension.json:1-7]().

---

## 03. Session Bootstrap & Hook System

> Understanding the automatic activation layer that triggers skills at the start of every session, ensuring the agent is immediately oriented to the project's methodology.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/03-session-bootstrap-hook-system.md
- Generated: 2026-05-20T00:29:51.613Z

### Source Files

- `hooks/session-start`
- `hooks/hooks.json`
- `hooks/run-hook.cmd`
- `hooks/hooks-cursor.json`

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [hooks/session-start](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start)
- [hooks/hooks.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks.json)
- [hooks/run-hook.cmd](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/run-hook.cmd)
- [hooks/hooks-cursor.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks-cursor.json)
- [skills/using-superpowers/SKILL.md](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/skills/using-superpowers/SKILL.md)
- [docs/windows/polyglot-hooks.md](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/docs/windows/polyglot-hooks.md)
</details>

# Session Bootstrap & Hook System

The Session Bootstrap system is the automatic activation layer that ensures an agent is immediately oriented to the Superpowers methodology at the start of every session. By injecting core instructions and the `using-superpowers` skill into the agent's initial context, the system transforms a generic coding assistant into a disciplined, process-driven engineer before the first line of code is ever discussed.

This system is designed to be platform-agnostic and cross-platform, supporting various agent harnesses (Claude Code, Cursor, Copilot CLI) across Windows, macOS, and Linux. It eliminates the need for manual setup by the user, making "Superpowers" a persistent, zero-configuration upgrade to the development environment.

## Automatic Activation Layer

The bootstrap process is triggered by platform-specific `SessionStart` hooks. These hooks are registered in configuration files that the respective agent harnesses monitor.

| Platform | Configuration File | Trigger Event |
| :--- | :--- | :--- |
| **Claude Code** | [hooks/hooks.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks.json) | `startup`, `clear`, or `compact` |
| **Cursor** | [hooks/hooks-cursor.json](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks-cursor.json) | `sessionStart` |

When these events occur, the harness executes the registered command, which points to the Superpowers hook runner.

Sources: [hooks/hooks.json:3-14](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks.json#L3-L14), [hooks/hooks-cursor.json:3-9](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/hooks-cursor.json#L3-L9)

## Cross-Platform Polyglot Runner

To ensure compatibility across operating systems, Superpowers utilizes a **polyglot wrapper** technique. Since Windows CMD cannot execute `.sh` files directly and may not have `bash` in the `PATH`, the `run-hook.cmd` script acts as a dual-language entry point.

### The Reusable Wrapper Pattern
The `run-hook.cmd` file is valid syntax in both Windows CMD (batch) and Unix shells (bash).

- **On Windows**: CMD sees the initial `: << 'CMDBLOCK'` as a label and ignores the rest of the line. It then executes the batch portion to find and invoke `bash.exe` (typically from Git for Windows).
- **On Unix**: Bash sees `:` as a no-op and `<< 'CMDBLOCK'` as the start of a heredoc, effectively skipping the Windows-specific batch commands and executing the Unix-specific logic at the end.

```cmd
: << 'CMDBLOCK'
@echo off
REM Windows logic to find bash.exe and run the script
...
exit /b 0
CMDBLOCK

# Unix logic to run the script directly
exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
```

Sources: [hooks/run-hook.cmd:1-46](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/run-hook.cmd#L1-L46), [docs/windows/polyglot-hooks.md:18-51](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/docs/windows/polyglot-hooks.md#L18-L51)

## Session Start Logic & Context Injection

The core bootstrap logic resides in the `hooks/session-start` bash script. Its primary responsibility is to construct a JSON object containing the injected context that the agent harness will merge into the session.

### Execution Steps
1. **Environment Detection**: Determines the plugin root directory and detects the current platform (Cursor vs. Claude Code vs. others) via environment variables like `CURSOR_PLUGIN_ROOT` or `CLAUDE_PLUGIN_ROOT`.
2. **Legacy Migration Check**: Checks for the existence of `~/.config/superpowers/skills` and prepares a warning message if found, ensuring users migrate to the modern Claude Code skills directory.
3. **Introduction Injection**: Reads the full content of the `superpowers:using-superpowers` skill. This skill establishes the non-negotiable rule: **Invoke relevant skills BEFORE any response or action**.
4. **JSON Serialization**: Escapes the skill content and warning messages for safe embedding into a JSON response. The script uses high-performance bash parameter substitution for escaping.

Sources: [hooks/session-start:6-35](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start#L6-L35)

## Platform-Specific Integration

Different harnesses expect injected context in different JSON structures. The `session-start` script dynamically adapts its output to match the host platform's requirements.

| Platform | Detection Variable | Output JSON Key |
| :--- | :--- | :--- |
| **Cursor** | `CURSOR_PLUGIN_ROOT` | `additional_context` |
| **Claude Code** | `CLAUDE_PLUGIN_ROOT` | `hookSpecificOutput.additionalContext` |
| **Copilot CLI** | `COPILOT_CLI` | `additionalContext` |

This precise mapping ensures that the orientation instructions are correctly interpreted by the agent, regardless of the IDE or CLI tool being used.

Sources: [hooks/session-start:46-55](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start#L46-L55)

## Summary

The Session Bootstrap & Hook System is the "silent partner" of Superpowers, providing the infrastructure necessary for autonomous, disciplined agent behavior. By leveraging cross-platform polyglot scripts and targeted context injection, it ensures that every session begins with the agent fully aware of its "Superpowers" and the rigorous workflows required to use them effectively.

Sources: [hooks/session-start:35-55](file:///var/folders/_h/3ssd63kx3_j7pxq42wmfq5980000gn/T/grok-wiki-local-cli-workspace-LthjNT/repo/hooks/session-start#L35-L55)

---

## 04. Product Discovery & Socratic Design

> The "Ideas" and "Blueprint" phase: using Socratic questioning to refine rough concepts into clear, digestible specifications before a single line of code is written.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/04-product-discovery-socratic-design.md
- Generated: 2026-05-20T00:24:12.072Z

### Source Files

- `skills/brainstorming/SKILL.md`
- `skills/brainstorming/spec-document-reviewer-prompt.md`
- `skills/brainstorming/scripts/helper.js`
- `skills/brainstorming/visual-companion.md`

> ⚠️ The agent returned an invalid wiki page. This page needs regeneration.
>
> First failure: the page was empty, too short, or placeholder-like
> Retry failure: the page was empty, too short, or placeholder-like

(empty)

---

## 05. Bite-Sized Implementation Planning

> The "Plan" phase: breaking approved designs into 2-5 minute tasks, each with explicit file paths, code changes, and verification steps to ensure predictable progress.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/05-bite-sized-implementation-planning.md
- Generated: 2026-05-20T00:24:29.613Z

### Source Files

- `skills/writing-plans/SKILL.md`
- `skills/writing-plans/plan-document-reviewer-prompt.md`
- `skills/executing-plans/SKILL.md`

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [skills/writing-plans/SKILL.md](skills/writing-plans/SKILL.md)
- [skills/writing-plans/plan-document-reviewer-prompt.md](skills/writing-plans/plan-document-reviewer-prompt.md)
- [skills/executing-plans/SKILL.md](skills/executing-plans/SKILL.md)
- [skills/subagent-driven-development/SKILL.md](skills/subagent-driven-development/SKILL.md)
- [skills/verification-before-completion/SKILL.md](skills/verification-before-completion/SKILL.md)
</details>

# Bite-Sized Implementation Planning

Bite-Sized Implementation Planning is the process of decomposing approved technical designs into atomic, 2-5 minute tasks. This approach ensures that progress remains predictable, verifiable, and resilient to context drift. By shifting the focus from broad feature goals to specific, actionable steps, developers and AI agents can maintain high velocity while adhering to strict quality standards.

The core of this philosophy is that any task that cannot be completed and verified within a few minutes is too large and must be further decomposed. This "bite-sized" granularity allows for continuous integration, rapid feedback loops, and a clear audit trail of verification evidence for every single change.

## The Anatomy of a Bite-Sized Task

A well-defined task is not just a description of work; it is a self-contained unit of execution. Every task in an implementation plan must satisfy specific criteria to be considered "bite-sized" and ready for execution.

### Task Requirements
*   **Time-Boxed:** Each task should ideally take between 2 and 5 minutes to complete.
*   **Explicit Context:** Must name specific file paths and line ranges targeted for modification.
*   **Target Content:** Includes the exact character sequence or logic being replaced.
*   **Verification Steps:** Explicit commands (tests, builds, or linting) that prove the task was successful.

Sources: [skills/writing-plans/SKILL.md:45-60](), [skills/executing-plans/SKILL.md:17-48]()

## The Planning Workflow

The transition from a design specification to a bite-sized plan involves a rigorous extraction and review process. This phase ensures that the plan is not only logically sound but also technically grounded in the current state of the repository.

### Extraction and Review Cycle
1.  **Requirement Extraction:** Breaking the high-level spec into functional blocks.
2.  **Decomposition:** Splitting blocks into 2-5 minute tasks with explicit file citations.
3.  **QA Review:** A dedicated review phase to catch "hallucinated" file paths, missing verification steps, or overloaded task scopes.
4.  **Final Approval:** Ensuring the plan provides a clear, risk-mitigated path to the goal.

Sources: [skills/writing-plans/plan-document-reviewer-prompt.md:7-22](), [skills/writing-plans/plan-document-reviewer-prompt.md:84-118]()

### Task Execution Flow
```mermaid
sequenceDiagram
    participant Controller
    participant Implementer
    participant Reviewer
    
    Controller->>Implementer: Dispatch Task (Context + Spec)
    Note over Implementer: 2-5 Minute Implementation
    Implementer->>Implementer: TDD / Verification
    Implementer->>Controller: Self-Review & Completion Claim
    Controller->>Reviewer: Dispatch for QA (Spec Compliance)
    Reviewer->>Implementer: Request Fixes (if gaps found)
    Reviewer->>Controller: ✅ Approved
    Controller->>Controller: Mark Task Complete
```

## The Iron Law of Verification

A completion claim is considered a "hallucination" unless it is accompanied by fresh verification evidence. This is the "Iron Law" that governs the transition between bite-sized tasks.

### The Gate Function
Before claiming any status or moving to the next task, the agent must follow the Gate Function:
1.  **Identify:** Determine which command proves the claim (e.g., `npm test`).
2.  **Run:** Execute the full, fresh command.
3.  **Read:** Analyze the output for errors or exit codes.
4.  **Verify:** Confirm the output matches the expected result.
5.  **Claim:** Only then state that the task is complete.

Sources: [skills/verification-before-completion/SKILL.md:16-35](), [skills/subagent-driven-development/SKILL.md:36-41]()

## Quality Gates and Subagent Roles

In complex environments, Bite-Sized Implementation Planning is supported by specialized subagent roles that provide automated quality gates.

| Role | Responsibility | Key Output |
| :--- | :--- | :--- |
| **Implementer** | Executing the 2-5 minute task. | Diff + Verification Evidence |
| **Spec Reviewer** | Ensuring code matches the original plan/spec. | Compliance Report |
| **Code Quality Reviewer** | Checking for patterns, style, and regressions. | Approval / Fix Requests |

Sources: [skills/subagent-driven-development/SKILL.md:125-180](), [skills/subagent-driven-development/SKILL.md:36-41]()

Bite-sized planning transforms unpredictable "coding sessions" into a series of small, guaranteed wins. By enforcing 2-5 minute task boundaries and mandatory verification evidence, it eliminates the ambiguity that often leads to regressions and failed implementations.

Sources: [skills/verification-before-completion/SKILL.md:110-118]()

---

## 06. Subagent-Driven Execution & Review

> The "Page Shape" and "QA Review" phase: dispatching specialized subagents to implement tasks with two-stage automated review for spec compliance and code quality.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/06-subagent-driven-execution-review.md
- Generated: 2026-05-20T00:24:08.284Z

### Source Files

- `skills/subagent-driven-development/SKILL.md`
- `skills/dispatching-parallel-agents/SKILL.md`
- `skills/subagent-driven-development/implementer-prompt.md`
- `skills/subagent-driven-development/spec-reviewer-prompt.md`
- `skills/subagent-driven-development/code-quality-reviewer-prompt.md`

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [skills/subagent-driven-development/SKILL.md](skills/subagent-driven-development/SKILL.md)
- [skills/dispatching-parallel-agents/SKILL.md](skills/dispatching-parallel-agents/SKILL.md)
- [skills/subagent-driven-development/implementer-prompt.md](skills/subagent-driven-development/implementer-prompt.md)
- [skills/subagent-driven-development/spec-reviewer-prompt.md](skills/subagent-driven-development/spec-reviewer-prompt.md)
- [skills/subagent-driven-development/code-quality-reviewer-prompt.md](skills/subagent-driven-development/code-quality-reviewer-prompt.md)
</details>

# Subagent-Driven Execution & Review

The execution phase in **superpowers** transitions from a static **Plan** to active implementation through a coordinated swarm of specialized subagents. This process is governed by the **Page Shape** and **QA Review** workflows, ensuring that every code change is not only functional but strictly compliant with the original specification and high-quality standards. By dispatching parallel agents, the system achieves a map-reduce effect for complex features, maintaining a high velocity without compromising the integrity of the codebase.

This multi-stage automation moves beyond simple generation; it enforces a rigorous verification loop where one agent builds, a second verifies spec compliance, and a third audits code quality. This "separation of concerns" among agents mirrors a professional human peer-review process, significantly reducing the "94% PR rejection rate" by catching slop and hallucinations before they ever reach a human maintainer.

## The Three-Stage Implementation Workflow

The implementation follows a strict sequence of handoffs between specialized personas. This workflow ensures that implementation details do not drift from the approved **Blueprint**.

### 1. The Implementer (Execution)
The implementer agent is tasked with the primary coding work. It is instructed to follow the file structure defined in the plan and to prioritize clarity and maintainability. A key feature of this phase is the **Self-Review** requirement, where the agent must verify its own work against completeness, quality, and testing criteria before reporting back.

Sources: [skills/subagent-driven-development/implementer-prompt.md:1-125]()

### 2. Spec Compliance Review (QA Review)
Once an implementer finishes, a separate **Spec Reviewer** is dispatched. This agent operates under the "Do Not Trust the Report" directive. It ignores the implementer's summary and instead performs a line-by-line comparison of the actual code against the task requirements to identify missing pieces or "extra" unrequested work.

Sources: [skills/subagent-driven-development/spec-reviewer-prompt.md:1-50]()

### 3. Code Quality Review (QA Review)
Only after spec compliance is confirmed does the **Code Quality Reviewer** run. This agent focuses on architectural integrity, ensuring units are decomposed, interfaces are well-defined, and the implementation follows established patterns in the codebase.

Sources: [skills/subagent-driven-development/code-quality-reviewer-prompt.md:1-25]()

## Parallel Execution & Dispatch

For multi-file or multi-subsystem tasks, **superpowers** utilizes parallel dispatch to solve independent problems simultaneously. This reduces total wall-clock time and keeps each agent focused on a narrow, manageable context.

```mermaid
sequenceDiagram
    participant C as Controller
    participant I as Implementer
    participant SR as Spec Reviewer
    participant QR as Quality Reviewer

    C->>I: Dispatch Task (Implement)
    I->>I: Code & Self-Review
    I-->>C: DONE (Codebase updated)
    
    C->>SR: Dispatch Review (Spec Compliance)
    Note over SR: Verify Code vs Requirements
    SR-->>C: PASS / FAIL
    
    rect rgb(240, 240, 240)
    Note over C: Only if Spec Pass
    C->>QR: Dispatch Review (Code Quality)
    QR-->>C: Assessment
    end
```
Sources: [skills/dispatching-parallel-agents/SKILL.md:1-20]()

## Review Status and Outcomes

The following table describes the possible states during the subagent-driven execution phase:

| Status | Meaning | Action Required |
| :--- | :--- | :--- |
| `DONE` | Task complete and verified. | Proceed to next task or final review. |
| `DONE_WITH_CONCERNS` | Work finished but agent has doubts. | Human or peer review required. |
| `BLOCKED` | External dependency or ambiguity. | Human intervention or more context. |
| `NEEDS_CONTEXT` | Missing information to start/finish. | Update Plan or provide file access. |

## Verification & Escalation

A critical safety valve in the subagent workflow is the **Escalation Protocol**. Implementers are explicitly instructed to stop and say "this is too hard for me" if they encounter architectural decisions with multiple valid approaches or if the task involves restructuring that the plan didn't anticipate. This prevents "hallucinated fixes" and ensures that complex decisions are bubbled back up to the human partner.

Sources: [skills/subagent-driven-development/implementer-prompt.md:65-80]()

The subagent-driven model transforms the developer experience from manual coding to high-level orchestration, leveraging parallelization and automated QA to build robust, maintainable systems.
Sources: [skills/dispatching-parallel-agents/SKILL.md:25-35]()

---

## 07. Parallel Development with Git Worktrees

> Maintaining environment isolation by creating dedicated workspaces for each branch, allowing for seamless context switching and a clean main branch.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/07-parallel-development-with-git-worktrees.md
- Generated: 2026-05-20T00:24:02.923Z

### Source Files

- `skills/using-git-worktrees/SKILL.md`
- `README.md`
- `skills/finishing-a-development-branch/SKILL.md`

> ⚠️ The agent returned an invalid wiki page. This page needs regeneration.
>
> First failure: the page was empty, too short, or placeholder-like
> Retry failure: the page was empty, too short, or placeholder-like

(empty)

---

## 08. Evidence-Based Success with TDD

> Enforcing the RED-GREEN-REFACTOR cycle to ensure every code change is backed by a failing test first, eliminating speculative code and "slop" PRs.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/08-evidence-based-success-with-tdd.md
- Generated: 2026-05-20T00:23:53.096Z

### Source Files

- `skills/test-driven-development/SKILL.md`
- `skills/test-driven-development/testing-anti-patterns.md`
- `skills/verification-before-completion/SKILL.md`

> ⚠️ The agent returned an invalid wiki page. This page needs regeneration.
>
> First failure: the page was empty, too short, or placeholder-like
> Retry failure: the page was empty, too short, or placeholder-like

(empty)

---

## 09. Systematic Root Cause Analysis

> The "Root Cause" process: a 4-phase debugging strategy that prioritizes tracing and defensive implementation over ad-hoc guessing and patch-work.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/09-systematic-root-cause-analysis.md
- Generated: 2026-05-20T00:23:53.148Z

### Source Files

- `skills/systematic-debugging/SKILL.md`
- `skills/systematic-debugging/root-cause-tracing.md`
- `skills/systematic-debugging/defense-in-depth.md`
- `skills/systematic-debugging/condition-based-waiting.md`

> ⚠️ The agent returned an invalid wiki page. This page needs regeneration.
>
> First failure: the page was empty, too short, or placeholder-like
> Retry failure: the page was empty, too short, or placeholder-like

(empty)

---

## 10. Plan-Anchored Code Review & Feedback

> The final "QA Review" step: checking implementation against the original plan and spec, reporting issues by severity, and ensuring a high bar for PR acceptance.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/10-plan-anchored-code-review-feedback.md
- Generated: 2026-05-20T00:24:38.219Z

### Source Files

- `skills/requesting-code-review/SKILL.md`
- `skills/receiving-code-review/SKILL.md`
- `skills/requesting-code-review/code-reviewer.md`

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [skills/requesting-code-review/SKILL.md](skills/requesting-code-review/SKILL.md)
- [skills/receiving-code-review/SKILL.md](skills/receiving-code-review/SKILL.md)
- [skills/requesting-code-review/code-reviewer.md](skills/requesting-code-review/code-reviewer.md)
- [skills/subagent-driven-development/SKILL.md](skills/subagent-driven-development/SKILL.md)
- [skills/subagent-driven-development/spec-reviewer-prompt.md](skills/subagent-driven-development/spec-reviewer-prompt.md)
- [skills/subagent-driven-development/code-quality-reviewer-prompt.md](skills/subagent-driven-development/code-quality-reviewer-prompt.md)
- [docs/superpowers/specs/2026-01-22-document-review-system-design.md](docs/superpowers/specs/2026-01-22-document-review-system-design.md)
</details>

# Plan-Anchored Code Review & Feedback

Plan-Anchored Code Review is the final "QA Review" stage in the Superpowers workflow, ensuring that every implementation not only meets high technical standards but also aligns perfectly with the original specification and implementation plan. By anchoring reviews to a verified plan, the system prevents "scope creep" and "drift" where an implementation solves the wrong problem or adds unrequested complexity.

This process utilizes specialized subagents to perform objective evaluations. This approach preserves the lead agent's context for coordination while providing a fresh, skeptical perspective on the work product. The primary goal is to catch issues before they cascade into more complex technical debt or architectural failures.

## The Two-Stage Review Process

In subagent-driven development, every task undergoes a mandatory two-stage review process before it is considered complete. This ensures that functional requirements are met before technical polish is evaluated.

### Stage 1: Spec Compliance Review
The first gate focuses exclusively on whether the implementation matches the requested task or specification—nothing more and nothing less. The reviewer is instructed to be skeptical and verify claims by reading the actual code rather than trusting the implementer's report.

| Category | Goal |
| :--- | :--- |
| **Missing Requirements** | Ensure every line-item in the spec was actually implemented. |
| **Extra/Unneeded Work** | Flag over-engineering, "nice-to-haves," or features not in the spec (YAGNI). |
| **Misunderstandings** | Check for misinterpretations of the requirement's intent. |

Sources: [skills/subagent-driven-development/spec-reviewer-prompt.md:5-56]()

### Stage 2: Code Quality Review
Once an implementation is verified as spec-compliant, it moves to the quality gate. This stage evaluates the technical health of the code, its architecture, and its readiness for production.

- **Architecture:** Checks for clean separation of concerns and sound design decisions.
- **Error Handling:** Verifies proper handling of edge cases and failures.
- **Testing:** Ensures tests verify real behavior (avoiding brittle mocks) and that all tests pass.
- **Production Readiness:** Considers backward compatibility and documentation completeness.

Sources: [skills/requesting-code-review/code-reviewer.md:11-64](), [skills/subagent-driven-development/code-quality-reviewer-prompt.md:5-23]()

## Reporting Issues by Severity

Reviewers categorize findings into three distinct severity levels to help the implementer prioritize fixes.

1.  **Critical (Must Fix):** Serious bugs, security vulnerabilities, data loss risks, or fundamentally broken functionality.
2.  **Important (Should Fix):** Architectural issues, missing requested features, poor error handling, or significant test gaps.
3.  **Minor (Nice to Have):** Code style nitpicks, small optimization opportunities, or documentation polish.

Sources: [skills/requesting-code-review/code-reviewer.md:83-90]()

## The Feedback Loop & Reception

Code review is a technical protocol, not a social performance. Superpowers enforces a "Technical Rigor Over Social Comfort" principle.

- **Verify Before Implementing:** The agent must read the feedback, restate the requirement, and check it against codebase reality before acting.
- **No Performative Agreement:** Expressions like "You're absolutely right!" or "Great point!" are forbidden. The agent should acknowledge the fix factually (e.g., "Fixed in [location]") or push back with technical reasoning.
- **Reasoned Pushback:** If a reviewer lacks context or suggests a change that violates project principles (like YAGNI), the agent must push back using technical evidence.

```mermaid
sequenceDiagram
    participant I as Implementer
    participant R as Reviewer (Subagent)
    I->>R: Dispatch with Plan + Code Range
    Note over R: Review Stage 1: Spec Compliance
    R-->>I: Issues (if any)
    I->>I: Fix Spec Gaps
    I->>R: Re-Review Stage 1
    Note over R: Review Stage 2: Code Quality
    R-->>I: Severity-Categorized Issues
    I->>I: Fix Issues (High Severity First)
    I->>R: Final Verification
    R-->>I: Ready to Merge / Approved
```

Sources: [skills/receiving-code-review/SKILL.md:10-128]()

## Workflow Integration

Plan-Anchored review is mandatory at several key checkpoints in the development lifecycle:
- **Task Completion:** Review after every individual task in a plan to catch issues before they compound.
- **Feature Completion:** A final "whole-implementation" review after all tasks are finished.
- **Merge Preparation:** Before any branch is merged into the main codebase.

Sources: [skills/requesting-code-review/SKILL.md:14-23](), [skills/subagent-driven-development/SKILL.md:8-12]()

The system remains provider-neutral and portable, treating review subagents as specialized functions that can be dispatched regardless of the underlying model provider or repository structure.

Sources: [skills/subagent-driven-development/SKILL.md:238-250]()

---

## 11. The Meta-Layer — Creating Project-Specific Skills

> Extending the Superpowers methodology by writing and testing new skills that capture your own project's patterns, constraints, and tribal knowledge.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/11-the-meta-layer-creating-project-specific-skills.md
- Generated: 2026-05-20T00:24:02.975Z

### Source Files

- `skills/writing-skills/SKILL.md`
- `skills/writing-skills/testing-skills-with-subagents.md`
- `skills/writing-skills/anthropic-best-practices.md`
- `skills/writing-skills/persuasion-principles.md`

> ⚠️ The agent returned an invalid wiki page. This page needs regeneration.
>
> First failure: the page was empty, too short, or placeholder-like
> Retry failure: the page was empty, too short, or placeholder-like

(empty)

---

## 12. Mastery & Real-World Application

> Applying Superpowers beyond the first 30 minutes: handling legacy migrations, complex refactors, and maintaining a high-quality codebase at scale.

- Page Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/pages/12-mastery-real-world-application.md
- Generated: 2026-05-20T00:24:42.643Z

### Source Files

- `CLAUDE.md`
- `GEMINI.md`
- `RELEASE-NOTES.md`
- `AGENTS.md`
- `CODE_OF_CONDUCT.md`

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

# Mastery & Real-World Application

Superpowers is designed to evolve from a simple coding assistant into an autonomous engineering partner capable of handling complex, long-running tasks. Mastery of the system involves moving beyond individual file edits and adopting the systematic workflows that enable large-scale refactors, legacy migrations, and high-quality maintenance.

This page outlines the advanced strategies required to apply Superpowers effectively in real-world, high-stakes environments, focusing on protecting your reputation and maintaining codebase integrity.

## Legacy Migrations & Archaeological Debugging

Migrating legacy systems requires a deep understanding of existing (and often undocumented) behavior before a single line of code is changed. Superpowers enforces a "Systematic over ad-hoc" philosophy to prevent the introduction of regressions.

### The Iron Law of Debugging
When dealing with legacy code, the "Iron Law" must be followed: **No fixes without root cause investigation first.** This prevents the "guess-and-check" cycle that often plagues complex migrations.

Sources: [skills/systematic-debugging/SKILL.md:16-20](), [README.md:144-147]()

### Archaeological Instrumentation
For multi-component systems where the failure point is unknown, use Phase 1 of the systematic debugging process to add diagnostic instrumentation. Instead of guessing where a value changes, log data as it enters and exits every component boundary. This "archaeological" approach reveals exactly where the legacy logic deviates from requirements.

Sources: [skills/systematic-debugging/SKILL.md:50-87]()

## Complex Refactors with Subagent-Driven Development (SDD)

Large-scale refactors are too big for a single agent session to track reliably. Superpowers solves this through **Subagent-Driven Development (SDD)**, which decomposes a high-level plan into independent, reviewed tasks.

### Two-Stage Review Process
To maintain quality at scale, SDD uses a two-stage review process for every task:
1.  **Spec Compliance Review**: A reviewer agent verifies the implementation against the original plan independently, without trusting the implementer's report.
2.  **Code Quality Review**: A second review focused on logic, performance, and best practices.

This separation of concerns ensures that the refactor doesn't drift from its architectural goals while maintaining high technical standards.

Sources: [skills/subagent-driven-development/SKILL.md:4-6](), [README.md:110-120]()

### Orchestration and Parallelism
For massive refactors, use `dispatching-parallel-agents` to handle independent tasks concurrently. This is combined with `using-git-worktrees` to ensure that each subagent works in a clean, isolated environment, preventing cross-task interference.

Sources: [README.md:135-138]()

## Maintaining High-Quality at Scale

As a project grows, the cost of "slop" increases exponentially. Superpowers is designed to protect your human partner's reputation by enforcing strict contribution guidelines.

### Protecting Your Human Partner
A core tenet of Superpowers mastery is recognizing that submitting a low-quality PR wastes time and burns reputation. Every change must be a "real problem" that has been verified, rather than a theoretical fix or a "compliance" change.

Sources: [AGENTS.md:9-17]()

### The Red-Green-Refactor Mandate
High-quality codebases are maintained through mandatory TDD workflows. Superpowers enforces a strict cycle:
1.  **RED**: Write a failing test first.
2.  **GREEN**: Write the minimal code needed to pass.
3.  **REFACTOR**: Clean up the code.

Critically, the system is designed to **delete code written before tests** to prevent the accumulation of untested logic.

Sources: [README.md:121-125](), [README.md:144-147]()

## Advanced Workflow Summary

| Workflow Stage | Tooling / Skill | Purpose |
| :--- | :--- | :--- |
| **Discovery** | `brainstorming` | Socratic refinement of complex requirements. |
| **Decomposition** | `writing-plans` | Breaking long tasks into 2-5 minute reviewed chunks. |
| **Execution** | `subagent-driven-development` | Autonomous, parallel task completion with multi-stage review. |
| **Validation** | `verification-before-completion` | Ensuring the fix or feature survives adversarial testing. |

Mastering Superpowers means trusting the process over intuition. By following these systematic phases, an engineer can manage hours of autonomous work without deviating from the initial architectural plan.

Sources: [README.md:103-108](), [skills/systematic-debugging/SKILL.md:46-50]()

---