Why superpowers
The problem it solves
Coding agents are capable but undisciplined and amnesiac. Left alone, they exhibit a predictable set of failure modes:
- They jump straight to writing code without understanding what you actually want.
- They skip tests, or write code first and tests after (or never).
- They debug by guessing rather than tracing root cause.
- They declare “done!” without verifying anything works.
- Most importantly: even when the model knows a best practice, it doesn’t reliably apply it under pressure — and every new session starts from zero, so hard-won lessons evaporate.
The core insight is that the bottleneck is not the model’s knowledge but its discipline and procedural memory. Superpowers is essentially an attempt to externalize an expert engineer’s process into something the agent will reliably follow every time.
How it solves it
The architecture has three layers: a bootstrap hook, a skills library, and a self-improvement meta-layer.
#mermaid-svg-0jlpIMPLqg58uq3B{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-0jlpIMPLqg58uq3B .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-0jlpIMPLqg58uq3B .error-icon{fill:#552222;}#mermaid-svg-0jlpIMPLqg58uq3B .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-0jlpIMPLqg58uq3B .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-0jlpIMPLqg58uq3B .marker{fill:#333333;stroke:#333333;}#mermaid-svg-0jlpIMPLqg58uq3B .marker.cross{stroke:#333333;}#mermaid-svg-0jlpIMPLqg58uq3B svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-0jlpIMPLqg58uq3B p{margin:0;}#mermaid-svg-0jlpIMPLqg58uq3B .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-0jlpIMPLqg58uq3B .cluster-label text{fill:#333;}#mermaid-svg-0jlpIMPLqg58uq3B .cluster-label span{color:#333;}#mermaid-svg-0jlpIMPLqg58uq3B .cluster-label span p{background-color:transparent;}#mermaid-svg-0jlpIMPLqg58uq3B .label text,#mermaid-svg-0jlpIMPLqg58uq3B span{fill:#333;color:#333;}#mermaid-svg-0jlpIMPLqg58uq3B .node rect,#mermaid-svg-0jlpIMPLqg58uq3B .node circle,#mermaid-svg-0jlpIMPLqg58uq3B .node ellipse,#mermaid-svg-0jlpIMPLqg58uq3B .node polygon,#mermaid-svg-0jlpIMPLqg58uq3B .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-0jlpIMPLqg58uq3B .rough-node .label text,#mermaid-svg-0jlpIMPLqg58uq3B .node .label text,#mermaid-svg-0jlpIMPLqg58uq3B .image-shape .label,#mermaid-svg-0jlpIMPLqg58uq3B .icon-shape .label{text-anchor:middle;}#mermaid-svg-0jlpIMPLqg58uq3B .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-0jlpIMPLqg58uq3B .rough-node .label,#mermaid-svg-0jlpIMPLqg58uq3B .node .label,#mermaid-svg-0jlpIMPLqg58uq3B .image-shape .label,#mermaid-svg-0jlpIMPLqg58uq3B .icon-shape .label{text-align:center;}#mermaid-svg-0jlpIMPLqg58uq3B .node.clickable{cursor:pointer;}#mermaid-svg-0jlpIMPLqg58uq3B .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-0jlpIMPLqg58uq3B .arrowheadPath{fill:#333333;}#mermaid-svg-0jlpIMPLqg58uq3B .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-0jlpIMPLqg58uq3B .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-0jlpIMPLqg58uq3B .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-0jlpIMPLqg58uq3B .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-0jlpIMPLqg58uq3B .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-0jlpIMPLqg58uq3B .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-0jlpIMPLqg58uq3B .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-0jlpIMPLqg58uq3B .cluster text{fill:#333;}#mermaid-svg-0jlpIMPLqg58uq3B .cluster span{color:#333;}#mermaid-svg-0jlpIMPLqg58uq3B 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-0jlpIMPLqg58uq3B .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-0jlpIMPLqg58uq3B rect.text{fill:none;stroke-width:0;}#mermaid-svg-0jlpIMPLqg58uq3B .icon-shape,#mermaid-svg-0jlpIMPLqg58uq3B .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-0jlpIMPLqg58uq3B .icon-shape p,#mermaid-svg-0jlpIMPLqg58uq3B .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-0jlpIMPLqg58uq3B .icon-shape .label rect,#mermaid-svg-0jlpIMPLqg58uq3B .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-0jlpIMPLqg58uq3B .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-0jlpIMPLqg58uq3B .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-0jlpIMPLqg58uq3B :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
Yes
Critical issues block
Pass
feeds back
Session starts
session-start-hook injectsEXTREMELY_IMPORTANT prompt
Agent detectsyou're building something
Search for relevant SKILL.md
If a skill exists, agent MUST use itnot a suggestion
brainstormingSocratic spec refinement
using-git-worktreesisolated branch + clean baseline
writing-plansbite-sized tasks, exact paths/code
subagent-driven-developmentfresh subagent per task
test-driven-developmentRED → GREEN → REFACTOR
requesting-code-reviewtwo-stage review
finishing-a-development-branchmerge / PR / discard
writing-skillsextract new reusable skills
1. Bootstrap hook. On session start it injects a prompt wrapped in <EXTREMELY_IMPORTANT> tags that teaches the agent three things: you have skills; search for them with a script; if a skill exists for a task, you must use it. This is the trigger mechanism — you don’t run commands, the skills activate automatically based on what you’re doing.
2. Skills as composable markdown. Each “skill” is a self-contained SKILL.md file — externalized procedural knowledge for one activity (TDD, systematic-debugging, brainstorming, writing-plans, etc.). They chain into a full SDLC: brainstorm → worktree → plan → subagent implementation → review → finish. The subagent-driven part matters for your RAG/agent interests: each task gets a fresh subagent with clean context, which both keeps the main context window from bloating and gives a two-stage review (spec compliance, then code quality).
3. Self-improvement meta-layer. The killer feature is writing-skills — a skill for writing skills. You can hand Claude a programming book or a codebase and say “read this, extract the non-obvious reusable lessons as skills.” Jesse even fed it 2,249 markdown files of lessons-learned mined from past conversations. New skills get pressure-tested (“TDD for skills”) against subagents in realistic high-pressure scenarios to confirm they’re actually followed.
The key design principles and philosophy
The repo states four explicitly:
- Test-Driven Development, always — write the failing test first, watch it fail, write minimal code to pass.
- Systematic over ad-hoc — process over guessing.
- Complexity reduction — simplicity as the primary goal (YAGNI, DRY).
- Evidence over claims — verify before declaring success.
But the most intellectually interesting principle is unstated in the README and revealed in the launch post: persuasion engineering. Jesse applied Robert Cialdini’s Influence principles — authority, commitment, scarcity, social proof — to make the agent reliably comply with its own instructions. Concrete examples:
- Authority: the EXTREMELY_IMPORTANT framing, and spinning up a “code-reviewer” subagent as an authority figure.
- Commitment: forcing the agent to announce out loud that it’s using a skill.
- Scarcity / pressure: the skill-testing scenarios deliberately simulate “production is down, $5k/minute” pressure to check whether the agent still stops to consult its skills.
There’s now peer-reviewed research from Wharton/Cialdini confirming these persuasion levers measurably work on LLMs — so this isn’t folklore. The deeper philosophy is: an LLM is less like a deterministic program you configure and more like a very capable junior engineer you have to socially manage — so you manage it with the same psychology that works on humans.
Why it’s so popular
A few factors compounded:
One caveat worth noting: the framework adds real overhead (lots of upfront brainstorming, planning, and review cycles), so it shines on substantial multi-step projects and can feel heavy for quick one-off scripts.
