Superpowers — What It Does & How It Orchestrates Skills

Superpowers — What It Does & How It Orchestrates Skills

1. What this repo is

Superpowers is a complete software-development methodology for coding agents, packaged as a
zero-dependency plugin. It is not application code — it ships a library of skills (markdown
playbooks) plus a single session-start hook that bootstraps the agent into using them.

The core idea: when you tell your agent “let’s build X”, it shouldn’t jump straight to writing code.
Instead it should step back, brainstorm a spec, write a plan, execute the plan task-by-task with
fresh subagents and review gates, then verify and integrate. Superpowers encodes that whole loop as
auto-triggering skills so you get the discipline “for free”.

It targets many harnesses from one source: Claude Code, Codex CLI/App, Factory Droid, Gemini CLI,
OpenCode, Cursor, GitHub Copilot CLI (see .claude-plugin/, .codex-plugin/, .cursor-plugin/,
.opencode/, gemini-extension.json).

2. The building blocks

The skill catalog

using-superpowers ………… Bootstrap: how to find & invoke every other skill
brainstorming ……………. Idea → approved design spec (gate before any code)
writing-plans ……………. Spec → bite-sized TDD implementation plan
subagent-driven-development .. Execute plan in-session via fresh subagent per task
executing-plans ………….. Execute plan in a separate session (no-subagent fallback)
dispatching-parallel-agents .. Fan out 2+ independent tasks concurrently
test-driven-development …… Red/green TDD discipline for each task
systematic-debugging ……… Root-cause-first bug investigation
requesting-code-review ……. Spawn reviewer subagent to check work
receiving-code-review …….. Evaluate review feedback with rigor, not blind agreement
verification-before-completion Run real verification before claiming "done"
finishing-a-development-branch Decide merge / PR / cleanup at the end
using-git-worktrees ………. Isolated workspace for feature work
writing-skills …………… Meta-skill: author & pressure-test new skills

3. How orchestration actually works

There is no central scheduler. Orchestration is emergent from three mechanisms:

Bootstrap sequence

UserAgentsession-start hookHarness (Claude Code / Codex / …)UserAgentsession-start hookHarness (Claude Code / Codex / …)#mermaid-svg-6YAnScCJ5gJgZ8kJ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .error-icon{fill:#552222;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .marker.cross{stroke:#333333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-6YAnScCJ5gJgZ8kJ p{margin:0;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-6YAnScCJ5gJgZ8kJ text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-6YAnScCJ5gJgZ8kJ .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .sequenceNumber{fill:white;}#mermaid-svg-6YAnScCJ5gJgZ8kJ #sequencenumber{fill:#333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .messageText{fill:#333;stroke:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .labelText,#mermaid-svg-6YAnScCJ5gJgZ8kJ .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .loopText,#mermaid-svg-6YAnScCJ5gJgZ8kJ .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-6YAnScCJ5gJgZ8kJ .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .noteText,#mermaid-svg-6YAnScCJ5gJgZ8kJ .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .actorPopupMenu{position:absolute;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-6YAnScCJ5gJgZ8kJ .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-6YAnScCJ5gJgZ8kJ .actor-man circle,#mermaid-svg-6YAnScCJ5gJgZ8kJ line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-6YAnScCJ5gJgZ8kJ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}Now knows the "1% rule":invoke a skill before respondinghandoff chain begins →SessionStart (startup/clear/compact)read using-superpowers/SKILL.mdJSON-escape + pick per-harness fieldinject as additionalContext"Let's build X"match request to a skill descriptioninvoke brainstorming (Skill tool)

The end-to-end development loop

#mermaid-svg-fES37lyJJwOLYEvx{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-fES37lyJJwOLYEvx .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-fES37lyJJwOLYEvx .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-fES37lyJJwOLYEvx .error-icon{fill:#552222;}#mermaid-svg-fES37lyJJwOLYEvx .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-fES37lyJJwOLYEvx .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-fES37lyJJwOLYEvx .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-fES37lyJJwOLYEvx .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-fES37lyJJwOLYEvx .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-fES37lyJJwOLYEvx .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-fES37lyJJwOLYEvx .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-fES37lyJJwOLYEvx .marker{fill:#333333;stroke:#333333;}#mermaid-svg-fES37lyJJwOLYEvx .marker.cross{stroke:#333333;}#mermaid-svg-fES37lyJJwOLYEvx svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-fES37lyJJwOLYEvx p{margin:0;}#mermaid-svg-fES37lyJJwOLYEvx .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-fES37lyJJwOLYEvx .cluster-label text{fill:#333;}#mermaid-svg-fES37lyJJwOLYEvx .cluster-label span{color:#333;}#mermaid-svg-fES37lyJJwOLYEvx .cluster-label span p{background-color:transparent;}#mermaid-svg-fES37lyJJwOLYEvx .label text,#mermaid-svg-fES37lyJJwOLYEvx span{fill:#333;color:#333;}#mermaid-svg-fES37lyJJwOLYEvx .node rect,#mermaid-svg-fES37lyJJwOLYEvx .node circle,#mermaid-svg-fES37lyJJwOLYEvx .node ellipse,#mermaid-svg-fES37lyJJwOLYEvx .node polygon,#mermaid-svg-fES37lyJJwOLYEvx .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-fES37lyJJwOLYEvx .rough-node .label text,#mermaid-svg-fES37lyJJwOLYEvx .node .label text,#mermaid-svg-fES37lyJJwOLYEvx .image-shape .label,#mermaid-svg-fES37lyJJwOLYEvx .icon-shape .label{text-anchor:middle;}#mermaid-svg-fES37lyJJwOLYEvx .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-fES37lyJJwOLYEvx .rough-node .label,#mermaid-svg-fES37lyJJwOLYEvx .node .label,#mermaid-svg-fES37lyJJwOLYEvx .image-shape .label,#mermaid-svg-fES37lyJJwOLYEvx .icon-shape .label{text-align:center;}#mermaid-svg-fES37lyJJwOLYEvx .node.clickable{cursor:pointer;}#mermaid-svg-fES37lyJJwOLYEvx .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-fES37lyJJwOLYEvx .arrowheadPath{fill:#333333;}#mermaid-svg-fES37lyJJwOLYEvx .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-fES37lyJJwOLYEvx .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-fES37lyJJwOLYEvx .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fES37lyJJwOLYEvx .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-fES37lyJJwOLYEvx .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fES37lyJJwOLYEvx .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-fES37lyJJwOLYEvx .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-fES37lyJJwOLYEvx .cluster text{fill:#333;}#mermaid-svg-fES37lyJJwOLYEvx .cluster span{color:#333;}#mermaid-svg-fES37lyJJwOLYEvx div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-fES37lyJJwOLYEvx .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-fES37lyJJwOLYEvx rect.text{fill:none;stroke-width:0;}#mermaid-svg-fES37lyJJwOLYEvx .icon-shape,#mermaid-svg-fES37lyJJwOLYEvx .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fES37lyJJwOLYEvx .icon-shape p,#mermaid-svg-fES37lyJJwOLYEvx .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-fES37lyJJwOLYEvx .icon-shape .label rect,#mermaid-svg-fES37lyJJwOLYEvx .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fES37lyJJwOLYEvx .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-fES37lyJJwOLYEvx .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-fES37lyJJwOLYEvx :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

HARD GATE: user approves design

yes, same session

no / separate session

more tasks

invoked on any bug/test failure

fan out independent tasks

Per task loop

Dispatch implementer subagent

test-driven-developmentred → green → refactor

spec-compliance review subagent

code-quality review subagent

mark task complete

User: build a feature

using-superpowersinjected at session start

brainstormingexplore intent → design spec

using-git-worktreesisolate workspace

writing-plansspec → bite-sized TDD plan

subagentsavailable?

subagent-driven-development

executing-plans

requesting-code-review

receiving-code-reviewevaluate feedback with rigor

verification-before-completionrun real checks, evidence not claims

finishing-a-development-branchmerge / PR / cleanup

Integrated, verified work

systematic-debugging

dispatching-parallel-agents

Decision logic baked into using-superpowers

#mermaid-svg-AhDqSkQiFLardFdw{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-AhDqSkQiFLardFdw .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-AhDqSkQiFLardFdw .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-AhDqSkQiFLardFdw .error-icon{fill:#552222;}#mermaid-svg-AhDqSkQiFLardFdw .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-AhDqSkQiFLardFdw .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-AhDqSkQiFLardFdw .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-AhDqSkQiFLardFdw .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-AhDqSkQiFLardFdw .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-AhDqSkQiFLardFdw .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-AhDqSkQiFLardFdw .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-AhDqSkQiFLardFdw .marker{fill:#333333;stroke:#333333;}#mermaid-svg-AhDqSkQiFLardFdw .marker.cross{stroke:#333333;}#mermaid-svg-AhDqSkQiFLardFdw svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-AhDqSkQiFLardFdw p{margin:0;}#mermaid-svg-AhDqSkQiFLardFdw .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-AhDqSkQiFLardFdw .cluster-label text{fill:#333;}#mermaid-svg-AhDqSkQiFLardFdw .cluster-label span{color:#333;}#mermaid-svg-AhDqSkQiFLardFdw .cluster-label span p{background-color:transparent;}#mermaid-svg-AhDqSkQiFLardFdw .label text,#mermaid-svg-AhDqSkQiFLardFdw span{fill:#333;color:#333;}#mermaid-svg-AhDqSkQiFLardFdw .node rect,#mermaid-svg-AhDqSkQiFLardFdw .node circle,#mermaid-svg-AhDqSkQiFLardFdw .node ellipse,#mermaid-svg-AhDqSkQiFLardFdw .node polygon,#mermaid-svg-AhDqSkQiFLardFdw .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-AhDqSkQiFLardFdw .rough-node .label text,#mermaid-svg-AhDqSkQiFLardFdw .node .label text,#mermaid-svg-AhDqSkQiFLardFdw .image-shape .label,#mermaid-svg-AhDqSkQiFLardFdw .icon-shape .label{text-anchor:middle;}#mermaid-svg-AhDqSkQiFLardFdw .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-AhDqSkQiFLardFdw .rough-node .label,#mermaid-svg-AhDqSkQiFLardFdw .node .label,#mermaid-svg-AhDqSkQiFLardFdw .image-shape .label,#mermaid-svg-AhDqSkQiFLardFdw .icon-shape .label{text-align:center;}#mermaid-svg-AhDqSkQiFLardFdw .node.clickable{cursor:pointer;}#mermaid-svg-AhDqSkQiFLardFdw .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-AhDqSkQiFLardFdw .arrowheadPath{fill:#333333;}#mermaid-svg-AhDqSkQiFLardFdw .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-AhDqSkQiFLardFdw .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-AhDqSkQiFLardFdw .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-AhDqSkQiFLardFdw .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-AhDqSkQiFLardFdw .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-AhDqSkQiFLardFdw .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-AhDqSkQiFLardFdw .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-AhDqSkQiFLardFdw .cluster text{fill:#333;}#mermaid-svg-AhDqSkQiFLardFdw .cluster span{color:#333;}#mermaid-svg-AhDqSkQiFLardFdw div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-AhDqSkQiFLardFdw .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-AhDqSkQiFLardFdw rect.text{fill:none;stroke-width:0;}#mermaid-svg-AhDqSkQiFLardFdw .icon-shape,#mermaid-svg-AhDqSkQiFLardFdw .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-AhDqSkQiFLardFdw .icon-shape p,#mermaid-svg-AhDqSkQiFLardFdw .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-AhDqSkQiFLardFdw .icon-shape .label rect,#mermaid-svg-AhDqSkQiFLardFdw .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-AhDqSkQiFLardFdw .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-AhDqSkQiFLardFdw .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-AhDqSkQiFLardFdw :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

definitely not

yes

yes

no

no

yes

User message received

Might any skillapply? even 1%

Respond / ask clarifications

Invoke Skill tool

Announce: Using SKILL to PURPOSE

Skill haschecklist?

Create one TodoWrite item per step

Follow skill exactly

About to enterplan mode?

Alreadybrainstormed?

Invoke brainstorming first

4. Why it’s built this way

• Skills are code, not prose. They shape agent behavior, so the repo treats wording (Red Flag
  tables, “your human partner” phrasing, rationalization lists) as carefully tuned and gated behind
  eval evidence (see CLAUDE.md and writing-skills).
• Hard gates prevent premature coding. brainstorming refuses to touch code until a design is
  approved — even for “trivial” projects.
• Fresh subagent per task keeps each task’s context clean and preserves the orchestrator’s
  context for coordination; two-stage review (spec → quality) catches drift.
• Zero dependencies, multi-harness. One skill library + one hook, re-targeted to every supported
  agent runner. New-harness support is judged by one acceptance test: does “Let’s make a react todo
  list” auto-trigger brainstorming?

5. TL;DR

A session-start hook injects one bootstrap skill that teaches the agent to auto-invoke skills.
Each skill’s description is its trigger; each skill’s body hands off to the next. Together they
form a disciplined loop — brainstorm → plan → TDD execute with subagent review → verify →
finish — with debugging and parallelization woven in on demand. No orchestrator process; the
orchestration is the skills calling each other.