# yanyan-se/superpowers architecture

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

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

## Overview

Superpowers is a skills-based software-development methodology for coding agents, activated through agent-specific plugins, extensions, and hooks. Its principal workflow guides a user from clarifying an idea to an approved design, isolated workspace, implementation plan, task execution, review, and branch completion. The README documents these workflow transitions and the broader skill library; sampled source also shows the brainstorming companion’s browser/server interaction. Most skill implementations and harness adapters were not sampled, so links reflect documented workflow rather than inferred code calls.

Main entry points: [`skills/executing-plans/SKILL.md`](https://github.com/yanyan-se/superpowers/blob/main/skills/executing-plans/SKILL.md) (Plan execution), [`skills/subagent-driven-development/SKILL.md`](https://github.com/yanyan-se/superpowers/blob/main/skills/subagent-driven-development/SKILL.md) (Subagent development), [`skills/brainstorming/scripts/server.cjs`](https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/scripts/server.cjs) (Companion server), [`skills/brainstorming/SKILL.md`](https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/SKILL.md) (Brainstorming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Agent integrations"]
  node_claude["Claude integration<br/>[plugin.json]"]
  node_codex["Codex integration<br/>[plugin.json]"]
  node_opencode["OpenCode plugin<br/>[superpowers.js]"]
  node_pi["Pi extension<br/>[superpowers.ts]"]
  node_session["Session hooks"]
  node_bootstrap["Skill bootstrap<br/>[SKILL.md]"]
end

subgraph group_workflow["Development workflow"]
  node_brainstorm["Brainstorming<br/>[SKILL.md]"]
  node_worktrees["Git worktrees<br/>[SKILL.md]"]
  node_planning["Writing plans<br/>[SKILL.md]"]
  node_execution["Plan execution<br/>[SKILL.md]"]
  node_subagents["Subagent development<br/>[SKILL.md]"]
  node_parallel["Parallel agents<br/>[SKILL.md]"]
  node_finish["Branch completion<br/>[SKILL.md]"]
end

subgraph group_quality["Quality practices"]
  node_tdd["Test-driven development<br/>[SKILL.md]"]
  node_review["Code review<br/>[SKILL.md]"]
  node_receive["Review response<br/>[SKILL.md]"]
  node_debug["Systematic debugging<br/>[SKILL.md]"]
  node_verify["Completion verification<br/>[SKILL.md]"]
  node_writing["Skill authoring<br/>[SKILL.md]"]
end

subgraph group_companion["Brainstorm companion"]
  node_companion_server["Companion server<br/>[server.cjs]"]
  node_companion_helper["Browser helper<br/>[helper.js]"]
  node_screen_files["Brainstorm screens"]
end

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

node_user -->|"starts task"| node_agent
node_claude -->|"provides skills"| node_agent
node_codex -->|"provides skills"| node_agent
node_opencode -->|"provides skills"| node_agent
node_pi -->|"provides skills"| node_agent
node_session -->|"bootstraps session"| node_agent
node_agent -->|"checks skills"| node_bootstrap
node_bootstrap -->|"activates"| node_brainstorm
node_brainstorm -->|"after approval"| node_worktrees
node_brainstorm -.->|"can launch"| node_companion_server
node_companion_server -->|"serves screens"| node_screen_files
node_companion_server -->|"injects helper"| node_companion_helper
node_companion_helper -->|"sends choices"| node_companion_server
node_worktrees -->|"prepares workspace"| node_planning
node_planning -->|"activates"| node_execution
node_planning -->|"dispatches"| node_subagents
node_subagents -.->|"can delegate"| node_parallel
node_execution -->|"uses"| node_tdd
node_subagents -->|"uses"| node_tdd
node_subagents -->|"requests review"| node_review
node_execution -->|"reviews tasks"| node_review
node_review -->|"returns feedback"| node_receive
node_execution -.->|"can invoke"| node_debug
node_execution -->|"verifies result"| node_verify
node_verify -->|"completes work"| node_finish
node_agent -.->|"can author skills"| node_writing

click node_claude "https://github.com/yanyan-se/superpowers/blob/main/.claude-plugin/plugin.json"
click node_codex "https://github.com/yanyan-se/superpowers/blob/main/.codex-plugin/plugin.json"
click node_opencode "https://github.com/yanyan-se/superpowers/blob/main/.opencode/plugins/superpowers.js"
click node_pi "https://github.com/yanyan-se/superpowers/blob/main/.pi/extensions/superpowers.ts"
click node_session "https://github.com/yanyan-se/superpowers/tree/main/hooks"
click node_bootstrap "https://github.com/yanyan-se/superpowers/blob/main/skills/using-superpowers/SKILL.md"
click node_brainstorm "https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/SKILL.md"
click node_worktrees "https://github.com/yanyan-se/superpowers/blob/main/skills/using-git-worktrees/SKILL.md"
click node_planning "https://github.com/yanyan-se/superpowers/blob/main/skills/writing-plans/SKILL.md"
click node_execution "https://github.com/yanyan-se/superpowers/blob/main/skills/executing-plans/SKILL.md"
click node_subagents "https://github.com/yanyan-se/superpowers/blob/main/skills/subagent-driven-development/SKILL.md"
click node_parallel "https://github.com/yanyan-se/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md"
click node_tdd "https://github.com/yanyan-se/superpowers/blob/main/skills/test-driven-development/SKILL.md"
click node_review "https://github.com/yanyan-se/superpowers/blob/main/skills/requesting-code-review/SKILL.md"
click node_receive "https://github.com/yanyan-se/superpowers/blob/main/skills/receiving-code-review/SKILL.md"
click node_debug "https://github.com/yanyan-se/superpowers/blob/main/skills/systematic-debugging/SKILL.md"
click node_verify "https://github.com/yanyan-se/superpowers/blob/main/skills/verification-before-completion/SKILL.md"
click node_finish "https://github.com/yanyan-se/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md"
click node_writing "https://github.com/yanyan-se/superpowers/blob/main/skills/writing-skills/SKILL.md"
click node_companion_server "https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/scripts/server.cjs"
click node_companion_helper "https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/scripts/helper.js"
click node_screen_files "https://github.com/yanyan-se/superpowers/tree/main/skills/brainstorming/scripts"

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_claude,node_codex,node_opencode,node_pi,node_session,node_bootstrap toneBlue
class node_brainstorm,node_worktrees,node_planning,node_execution,node_subagents,node_parallel,node_finish toneAmber
class node_tdd,node_review,node_receive,node_debug,node_verify,node_writing toneMint
class node_companion_server,node_companion_helper,node_screen_files toneRose
class node_user,node_agent toneIndigo
```

## Components

### Agent integrations

- [Claude integration](https://github.com/yanyan-se/superpowers/blob/main/.claude-plugin/plugin.json): `.claude-plugin/plugin.json`
- [Codex integration](https://github.com/yanyan-se/superpowers/blob/main/.codex-plugin/plugin.json): `.codex-plugin/plugin.json`
- [OpenCode plugin](https://github.com/yanyan-se/superpowers/blob/main/.opencode/plugins/superpowers.js): `.opencode/plugins/superpowers.js`
- [Pi extension](https://github.com/yanyan-se/superpowers/blob/main/.pi/extensions/superpowers.ts): `.pi/extensions/superpowers.ts`
- [Session hooks](https://github.com/yanyan-se/superpowers/tree/main/hooks): `hooks`
- [Skill bootstrap](https://github.com/yanyan-se/superpowers/blob/main/skills/using-superpowers/SKILL.md): `skills/using-superpowers/SKILL.md`

### Development workflow

- [Brainstorming](https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/SKILL.md): `skills/brainstorming/SKILL.md`
- [Git worktrees](https://github.com/yanyan-se/superpowers/blob/main/skills/using-git-worktrees/SKILL.md): `skills/using-git-worktrees/SKILL.md`
- [Writing plans](https://github.com/yanyan-se/superpowers/blob/main/skills/writing-plans/SKILL.md): `skills/writing-plans/SKILL.md`
- [Plan execution](https://github.com/yanyan-se/superpowers/blob/main/skills/executing-plans/SKILL.md): `skills/executing-plans/SKILL.md`
- [Subagent development](https://github.com/yanyan-se/superpowers/blob/main/skills/subagent-driven-development/SKILL.md): `skills/subagent-driven-development/SKILL.md`
- [Parallel agents](https://github.com/yanyan-se/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md): `skills/dispatching-parallel-agents/SKILL.md`
- [Branch completion](https://github.com/yanyan-se/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md): `skills/finishing-a-development-branch/SKILL.md`

### Quality practices

- [Test-driven development](https://github.com/yanyan-se/superpowers/blob/main/skills/test-driven-development/SKILL.md): `skills/test-driven-development/SKILL.md`
- [Code review](https://github.com/yanyan-se/superpowers/blob/main/skills/requesting-code-review/SKILL.md): `skills/requesting-code-review/SKILL.md`
- [Review response](https://github.com/yanyan-se/superpowers/blob/main/skills/receiving-code-review/SKILL.md): `skills/receiving-code-review/SKILL.md`
- [Systematic debugging](https://github.com/yanyan-se/superpowers/blob/main/skills/systematic-debugging/SKILL.md): `skills/systematic-debugging/SKILL.md`
- [Completion verification](https://github.com/yanyan-se/superpowers/blob/main/skills/verification-before-completion/SKILL.md): `skills/verification-before-completion/SKILL.md`
- [Skill authoring](https://github.com/yanyan-se/superpowers/blob/main/skills/writing-skills/SKILL.md): `skills/writing-skills/SKILL.md`

### Brainstorm companion

- [Companion server](https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/scripts/server.cjs): `skills/brainstorming/scripts/server.cjs`
- [Browser helper](https://github.com/yanyan-se/superpowers/blob/main/skills/brainstorming/scripts/helper.js): `skills/brainstorming/scripts/helper.js`
- [Brainstorm screens](https://github.com/yanyan-se/superpowers/tree/main/skills/brainstorming/scripts): `skills/brainstorming/scripts`

### Other components

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

## Connections

- Developer → Coding agent: starts task
- Claude integration → Coding agent: provides skills
- Codex integration → Coding agent: provides skills
- OpenCode plugin → Coding agent: provides skills
- Pi extension → Coding agent: provides skills
- Session hooks → Coding agent: bootstraps session
- Coding agent → Skill bootstrap: checks skills
- Skill bootstrap → Brainstorming: activates
- Brainstorming → Git worktrees: after approval
- Brainstorming → Companion server: can launch
- Companion server → Brainstorm screens: serves screens
- Companion server → Browser helper: injects helper
- Browser helper → Companion server: sends choices
- Git worktrees → Writing plans: prepares workspace
- Writing plans → Plan execution: activates
- Writing plans → Subagent development: dispatches
- Subagent development → Parallel agents: can delegate
- Plan execution → Test-driven development: uses
- Subagent development → Test-driven development: uses
- Subagent development → Code review: requests review
- Plan execution → Code review: reviews tasks
- Code review → Review response: returns feedback
- Plan execution → Systematic debugging: can invoke
- Plan execution → Completion verification: verifies result
- Completion verification → Branch completion: completes work
- Coding agent → Skill authoring: can author skills