obra/superpowers

A development methodology plus a library of tools for AI coding. 272,000 likes in ten months. I did not adopt the framework — and the reason this piece is worth keeping is what came next: applying the project’s own prescribed method to the project itself collapsed two of my three takeaways.

What it does

Say let’s build this and it stops you jumping straight to code. Instead:

1. Interrogate you until what is being built is settled
2. Break it into a plan
3. Spawn a fresh AI per task to build and review

And this fires on its own. You do not have to say now do that stage. That wiring is what this thing actually is — counting fourteen tools does not show it.

The most instructive part — “judge without stopping”

The hardest problem in running an AI unattended: what to do when something ambiguous comes up.

The common answers	The problem
Stop and ask	You are away, so it sits still all night
Decide and carry on	Later, nobody knows why it did that

This repository’s answer:

Judge and keep going. But record what was decided, why, and what it costs if that judgement is wrong.

And it restricts genuine stopping to four cases — irreversible actions, security, side effects outside the workspace, and when every path is guesswork.

Everything else is judged and carried. So it runs all night and makes progress, and in the morning you can read what it decided.

And the paired rule — gather all of it at the end

There is a companion rule. Before wiping the workspace, every recorded judgement is collected into a section of the final report.

The grounds:

A judgement that dies with the ledger is a decision made in secret.

Recording is not enough. If the record is deleted along with the workspace, it is the same as never recording it.

Another — “a cap on fixing, and a circuit breaker”

When a review raises something, you fix it. But you cannot fix forever.

This caps it at five rounds per task, and changes who does the fixing along the way.

Round	Who fixes	Why
1–3	The original builder continues	They know their own code
4–5	A stronger model, a fresh builder	Three failures means the eyes need to change
After	A circuit breaker drops	Item by item: hold, or minimal fix

A fourth attempt by the same person after three failures is usually pointless. That is written into the rules.

And “do not hand the reviewer the answer”

Small and important.

Putting “do not flag this” into a reviewer’s instructions makes the reviewer stop thinking there.

Even where it looks like a false positive, the reviewer raises it and the judgement happens at the next stage. The filtering seat and the judging seat are separated.

One measurement worth having — “pasted things follow you forever”

The most striking number they measured.

When handing off work, pasting the content in means it stays loaded until the session ends. It is re-read every turn.

One measured handoff was 42,000 characters, of which 99% was pasted past history.

→ Hence the rule: do not paste, pass a file. A file is read only when needed.

And another — “the cheap model can cost more”

A paradoxical measurement.

	Unit price	Actual total
The expensive model	High	Finishes in fewer exchanges
The cheap model	Low	Takes 2–3× the exchanges, costing more overall

Look at the total, not the unit price.

And there is a second trap: omit the model on a task and it inherits the most expensive one. A rule written to save money is silently voided the moment somebody forgets to fill in a field.

But the method this repository taught collapsed my takeaways

The subject of the piece.

In the first pass I wrote down three things to take.

And the repository’s own documents contain a prescribed way to verify things. I turned that method on the repository itself.

Two of the three lost their grounds.

One line was decisive. Their own rule says:

If the control does not exhibit the failure, stop there.

Which means to claim this is better you must first show it is worse without it. Two of my takeaways failed that condition — I was measuring only my own thing, with no control.

And measuring only your own thing confirms what you already believed.

So I stopped there. Three became one.

But what actually changed was not that one

The most important part.

The takeaway count is one. What this analysis actually changed was finding and closing holes in two of my other pipelines.

Not something taken from someone else, but something that surfaced while measuring my own thing by their standard.

The recurring conclusion on this shelf shows up again: counting a teardown’s value by the number of things taken loses half of it.

Why I did not adopt the framework

My pipeline already had the same machinery — model per stage, retry ceilings, machine-judged gates, resuming from where it stopped. And some of mine is more refined.

For reference the always-on cost is about 1,511 tokens — small (0.76% of the budget). I did not reject it over cost.

The detailed record starts here

I rejected the framework wholesale. My test-case pipeline already has the same machinery — per-stage model selection, retry ceilings, deterministic gates, hash-based resume — and in places it is more precise. That much is an ordinary conclusion. What makes this one worth writing is what came next: I had listed three things to take away, then applied the project’s own verification method to the project itself, and the ground under two of them disappeared. One survived. And yet the thing this teardown actually changed wasn’t that one — it was finding and closing a hole in two of my other pipelines.

What it is

A development methodology for coding agents, plus a library of fourteen skills. Say “let’s build X” and it doesn’t jump to code — it interrogates the design into a spec, splits that into a plan, then spawns a fresh agent per task to implement and review. Thirteen agent hosts are supported.

The substance isn’t the skill documents, it’s the wiring. A session-start hook injects 63 lines of preamble into every session, and those lines declare “if there is a 1% chance a skill applies you MUST invoke it / you do not have a choice / you cannot rationalize your way out” — followed immediately by a twelve-row table of rebuttals to rationalizations.

	Measured 2026-08-15
Scale	272,335 stars · 24,345 forks · in ten months
Licence / deps	MIT · zero external packages (the “zero dependency” claim checks out in code)
Contributors	523 commits by one person, 79 by the next — bus factor 1
Pull requests	167 merged / 943 closed unmerged / 182 open
Standing context cost	≈1,511 tokens (0.76% of 200k)
Cost when invoked	the largest single skill is ≈8,084 tokens

The techniques worth reading

The controller machinery is where the value is. It reads like a document written by someone who has already hit every problem that comes with running agents unattended.

Technique	What it says
Rule, don’t stall	A running plan does not wait for a human. Conflicts, ambiguity and ceiling breaches get ruled on and recorded as decision — why — cost if wrong. Only four things stop it: irreversible actions, security, side effects outside the workspace, and a plan where every path is a guess
Roll every ruling up	Before the workspace is deleted, every ruling line is collected into one section of the final report. “A ruling that dies with the ledger is a decision made in secret”
Fix-loop ceiling + breaker	Five rounds per task. Rounds 1–3 resume the original implementer (it knows its own code); 4–5 use a higher tier and a fresh one. After that the breaker trips and each item is parked or minimally ruled
Reviewers may not be pre-judged	If a reviewer prompt contains “don’t flag this”, it halts there. Even if you think it’s a false positive, let the reviewer raise it and rule in the loop
Hand artifacts over as files	Pasted text stays in context to the end of the session and is re-read every turn. One measured dispatch was 42k characters, 99% of it pasted history
Omit the model and you inherit the priciest one	Leave the model out of a dispatch and it inherits the session’s, silently voiding your cost rules. At the same time, turn count beats unit price — the cheapest model burns 2–3× the turns and costs more overall

And the star of this piece is in the skill-authoring methodology — match the form to the failure. Classify the baseline failure before writing any guidance, because a form that is bulletproof against one failure backfires measurably against another.

Baseline failure	Right form	Wrong form
Breaks a rule knowingly	prohibition + rebuttal table	soft advice
Complies, but the output shape is wrong	a positive recipe — state what the output is, in order	a list of prohibitions
Omits required elements	required slots in a template	prose reminders near the template
Should vary by condition	conditionals on observable predicates	absolute rule plus exceptions

What broke — two of the four criticisms were themselves wrong

Quoting the community criticism as-is would have been a mistake.

• “Installing it costs 22k tokens permanently” — stale. That issue is eight months old. Measuring the current version directly, the standing cost is 1,511 tokens. Reading the hook code, it injects exactly one file. Cite a criticism without pinning the version and the citation itself becomes the error.
• “Commits have collapsed lately” — my own misread. Weekly commits read 4,1,0,1, which looks like stagnation. But main is the release branch here and every PR targets the dev branch, where activity is dense. Judge activity without looking at the branch layout and you will be wrong.
• “272k stars with 0.38% watchers is abnormal” — normal for the cohort. Contemporary AI-tooling repositories all sit around 0.6%. A low watch ratio isn’t a manipulation signal, it’s what bookmark-stars look like.
• “A 69% reduction with no regression was rejected” — true, but consistent with stated policy: “content that shapes behaviour is code.”

Three real weaknesses survive the adversarial pass. Bus factor 1. A backlog of 334 with an 85% rejection rate — and the open issues point at logic defects inside the methodology, not wiring bugs. And ⚠ the reproduction path for the performance claims lives outside the repository — “we don’t change it without evidence” is the policy, but that evidence sits in a separate org, so the claims can be neither verified nor refuted.

Held against my own setup — and my verdict flipped

I took match the form to the failure and ran it over my own rule documents. Prohibitions outnumbered recipes 12.6 to 28.6 times over, with recipes at effectively 0%. So I wrote “my corpus is abnormal” and adopted it as the top item.

Then I found that the project’s own rule already decided how to handle this.

Always include a no-guidance control. If the control doesn’t exhibit the failure, there is nothing to fix — stop, and don’t author the guidance.

My control is the reference implementation. I ran the same script over it.

Verdict

Item	Pass 1 → 2	Why · what would reopen it
Match the form to the failure	adopt → hold	The reference is more skewed. Reopen when a concrete shape failure is actually observed, and then only for that one rule
Roll every ruling up	adopt, held	Attacked and didn’t break. Nothing equivalent existed, and the cost is one section in a report
Add a no-guidance control arm	adopt → hold	⚠ Both target tools have never actually been run. Attaching an arm to something never run is debt, not cost. Reopen on the first real run
Adopt the framework	rejected, still	The reasoning changed — below

⚠ I withdrew one of my rejection grounds. In the first pass I wrote that the hard approval gate “collides head-on with my no-auto-plan-mode rule and I can’t turn it off” — but the project states plainly in its closing section that user instructions take precedence over skills. My phrasing was an exaggeration.

The conclusion stands, on different grounds. The precedence sentence is the last of 63 lines; everything above it says “you do not have a choice, this is non-negotiable.” And two of the project’s own measured findings aim squarely at that structure — “a description that summarises the workflow makes the agent follow the description instead of the body”, and “exemption clauses don’t scope.” That precedence line is exactly such an exemption clause.

But what actually changed wasn’t a takeaway

I re-read my own pipelines through the lens of “don’t trust an agent’s success report.”

The test-case pipeline was already covered — deterministic code checks size, reference counts and truncation right after writing, and blocks the start when they disagree. Its two siblings were not. In the game QA server and the game studio, every stage transition is gated by another agent’s review verdict, and a search for any deterministic check that the artifact exists returned zero.

This failure has already happened here once. An attempt to generate 83 rows in one shot burned the output ceiling, exited with status 0, and cost a measured 88.3 minutes — which is why the test-case pipeline grew chunking and gates. ⚠ That lesson never travelled to the siblings. Lose a design artifact the same way and the next stage takes truncated input, and the review after it passes without knowing the original was cut. Status code 0, so nothing stops.

I added handoff gates to both. All 10 failure cases caught, all 12 healthy cases passed, zero false positives.

The lesson I paid for here isn’t a technique, it’s an order of operations — measure only your own side and the number confirms what you already believed. That is exactly how my top-ranked item got built, and it only collapsed once I turned the project’s own method back on the project.

And ⚠ a teardown pays off even when nothing comes across. The real takeaway count is one. What this investigation left behind was gates on two other pipelines. I borrowed the lens, not the tool.