# obra/superpowers architecture

> Architecture diagram of the GitHub repository obra/superpowers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/obra/superpowers
- Repository: https://github.com/obra/superpowers
- Video tour (about a minute): https://gitdiagram.com/obra/superpowers/video

## Overview

Superpowers is a set of composable software-development skills and harness integrations for coding agents. Its primary workflow turns a user’s request into an agreed design, a stepwise plan, and agent-led implementation with inspection and review. The broader skill library also covers debugging, TDD, code review, verification, and related engineering practices. Platform adapters expose the skills in supported coding-agent harnesses; the sampled sources show OpenCode’s directory entry point and package metadata, but not the internals of most adapters or skills.

Main entry points: [`skills/subagent-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md) (Subagent development), [`skills/brainstorming`](https://github.com/obra/superpowers/tree/main/skills/brainstorming) (Brainstorming), [`skills/brainstorming/scripts/server.cjs`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/server.cjs) (Companion server), [`skills/writing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md) (Writing plans)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Development workflow"]
  node_brainstorm["Brainstorming"]
  node_plan["Writing plans<br/>[SKILL.md]"]
  node_execute["Plan execution<br/>[SKILL.md]"]
  node_sdd["Subagent development<br/>[SKILL.md]"]
end

subgraph group_practices["Engineering practices"]
  node_tdd["Test-driven development<br/>[SKILL.md]"]
  node_debug["Systematic debugging<br/>[SKILL.md]"]
  node_review["Code review<br/>[SKILL.md]"]
  node_receive["Review response<br/>[SKILL.md]"]
  node_verify["Completion verification<br/>[SKILL.md]"]
  node_branch["Branch finishing<br/>[SKILL.md]"]
  node_worktrees["Git worktrees<br/>[SKILL.md]"]
  node_dispatch["Parallel agents<br/>[SKILL.md]"]
end

subgraph group_integration["Agent integration"]
  node_bootstrap["Skill bootstrap<br/>[SKILL.md]"]
  node_claude["Claude integration<br/>[plugin.json]"]
  node_opencode["OpenCode plugin<br/>[superpowers.js]"]
  node_opencode_entry["OpenCode entry<br/>[index.js]"]
  node_pi["Pi extension<br/>[superpowers.ts]"]
  node_hermes["Hermes integration<br/>[.hermes-plugin]"]
end

subgraph group_companion["Brainstorm companion"]
  node_visual["Visual companion"]
  node_server["Companion server<br/>[server.cjs]"]
  node_browser["Browser helper<br/>[helper.js]"]
  node_screen["Design screens"]
end

node_user(("Developer"))
node_agent(("Coding agent"))

node_user -->|"requests work"| node_agent
node_agent -->|"clarifies request"| node_brainstorm
node_brainstorm -->|"presents design"| node_user
node_user -->|"approves design"| node_plan
node_plan -->|"guides implementation"| node_agent
node_agent -->|"executes plan"| node_execute
node_agent -->|"delegates tasks"| node_sdd
node_sdd -->|"inspects work"| node_review
node_sdd -.->|"uses practice"| node_tdd
node_agent -.->|"diagnoses faults"| node_debug
node_agent -.->|"handles feedback"| node_receive
node_agent -.->|"checks completion"| node_verify
node_agent -.->|"finishes branch"| node_branch
node_agent -.->|"isolates work"| node_worktrees
node_sdd -.->|"uses agents"| node_dispatch
node_agent -->|"loads skills"| node_bootstrap
node_bootstrap -->|"triggers skill"| node_brainstorm
node_opencode_entry -->|"re-exports"| node_opencode
node_agent -.->|"loads plugin"| node_opencode
node_agent -.->|"loads plugin"| node_claude
node_agent -.->|"loads extension"| node_pi
node_agent -.->|"loads plugin"| node_hermes
node_brainstorm -.->|"offers companion"| node_visual
node_visual -.->|"starts server"| node_server
node_server -.->|"frames content"| node_screen
node_server -.->|"serves helper"| node_browser

click node_brainstorm "https://github.com/obra/superpowers/tree/main/skills/brainstorming"
click node_plan "https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md"
click node_execute "https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md"
click node_sdd "https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md"
click node_tdd "https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md"
click node_debug "https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md"
click node_review "https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/SKILL.md"
click node_receive "https://github.com/obra/superpowers/blob/main/skills/receiving-code-review/SKILL.md"
click node_verify "https://github.com/obra/superpowers/blob/main/skills/verification-before-completion/SKILL.md"
click node_branch "https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md"
click node_worktrees "https://github.com/obra/superpowers/blob/main/skills/using-git-worktrees/SKILL.md"
click node_dispatch "https://github.com/obra/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md"
click node_bootstrap "https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md"
click node_claude "https://github.com/obra/superpowers/blob/main/.claude-plugin/plugin.json"
click node_opencode "https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js"
click node_opencode_entry "https://github.com/obra/superpowers/blob/main/index.js"
click node_pi "https://github.com/obra/superpowers/blob/main/.pi/extensions/superpowers.ts"
click node_hermes "https://github.com/obra/superpowers/tree/main/.hermes-plugin"
click node_visual "https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md"
click node_server "https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/server.cjs"
click node_browser "https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/helper.js"
click node_screen "https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/frame-template.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_brainstorm,node_plan,node_execute,node_sdd toneBlue
class node_tdd,node_debug,node_review,node_receive,node_verify,node_branch,node_worktrees,node_dispatch toneAmber
class node_bootstrap,node_claude,node_opencode,node_opencode_entry,node_pi,node_hermes toneMint
class node_visual,node_server,node_browser,node_screen toneRose
class node_user,node_agent toneIndigo
```

## Components

### Development workflow

- [Brainstorming](https://github.com/obra/superpowers/tree/main/skills/brainstorming): `skills/brainstorming`
- [Writing plans](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md): `skills/writing-plans/SKILL.md`
- [Plan execution](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md): `skills/executing-plans/SKILL.md`
- [Subagent development](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md): `skills/subagent-driven-development/SKILL.md`

### Engineering practices

- [Test-driven development](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md): `skills/test-driven-development/SKILL.md`
- [Systematic debugging](https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md): `skills/systematic-debugging/SKILL.md`
- [Code review](https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/SKILL.md): `skills/requesting-code-review/SKILL.md`
- [Review response](https://github.com/obra/superpowers/blob/main/skills/receiving-code-review/SKILL.md): `skills/receiving-code-review/SKILL.md`
- [Completion verification](https://github.com/obra/superpowers/blob/main/skills/verification-before-completion/SKILL.md): `skills/verification-before-completion/SKILL.md`
- [Branch finishing](https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md): `skills/finishing-a-development-branch/SKILL.md`
- [Git worktrees](https://github.com/obra/superpowers/blob/main/skills/using-git-worktrees/SKILL.md): `skills/using-git-worktrees/SKILL.md`
- [Parallel agents](https://github.com/obra/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md): `skills/dispatching-parallel-agents/SKILL.md`

### Agent integration

- [Skill bootstrap](https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md): `skills/using-superpowers/SKILL.md`
- [Claude integration](https://github.com/obra/superpowers/blob/main/.claude-plugin/plugin.json): `.claude-plugin/plugin.json`
- [OpenCode plugin](https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js): `.opencode/plugins/superpowers.js`
- [OpenCode entry](https://github.com/obra/superpowers/blob/main/index.js): `index.js`
- [Pi extension](https://github.com/obra/superpowers/blob/main/.pi/extensions/superpowers.ts): `.pi/extensions/superpowers.ts`
- [Hermes integration](https://github.com/obra/superpowers/tree/main/.hermes-plugin): `.hermes-plugin`

### Brainstorm companion

- [Visual companion](https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md): `skills/brainstorming/visual-companion.md`
- [Companion server](https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/server.cjs): `skills/brainstorming/scripts/server.cjs`
- [Browser helper](https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/helper.js): `skills/brainstorming/scripts/helper.js`
- [Design screens](https://github.com/obra/superpowers/blob/main/skills/brainstorming/scripts/frame-template.html): `skills/brainstorming/scripts/frame-template.html`

### Other components

- **Developer**
- **Coding agent**

## Connections

- Developer → Coding agent: requests work (evidence: `README.md`)
- Coding agent → Brainstorming: clarifies request (evidence: `README.md`)
- Brainstorming → Developer: presents design (evidence: `README.md`)
- Developer → Writing plans: approves design (evidence: `README.md`)
- Writing plans → Coding agent: guides implementation (evidence: `README.md`)
- Coding agent → Plan execution: executes plan (evidence: `README.md`)
- Coding agent → Subagent development: delegates tasks (evidence: `README.md`)
- Subagent development → Code review: inspects work (evidence: `README.md`)
- Subagent development → Test-driven development: uses practice
- Coding agent → Systematic debugging: diagnoses faults
- Coding agent → Review response: handles feedback
- Coding agent → Completion verification: checks completion
- Coding agent → Branch finishing: finishes branch
- Coding agent → Git worktrees: isolates work
- Subagent development → Parallel agents: uses agents
- Coding agent → Skill bootstrap: loads skills (evidence: `README.md`)
- Skill bootstrap → Brainstorming: triggers skill (evidence: `README.md`)
- OpenCode entry → OpenCode plugin: re-exports (evidence: `index.js`)
- Coding agent → OpenCode plugin: loads plugin
- Coding agent → Claude integration: loads plugin
- Coding agent → Pi extension: loads extension
- Coding agent → Hermes integration: loads plugin
- Brainstorming → Visual companion: offers companion
- Visual companion → Companion server: starts server
- Companion server → Design screens: frames content
- Companion server → Browser helper: serves helper
