| name | meta-workflow |
| description | Use at the start of any non-trivial task to run it as a closed loop instead of a straight line — classify the task's weight, clarify the real goal, freeze acceptance criteria before building, execute, then independently verify "done AND good enough" before delivering. Orchestrates the step sub-skills and hands execution to superpowers. Skip for chat, lookups, and trivial one-line edits. |
Meta-Workflow — run heavy work as a closed loop
A meta-workflow for AI coding agents: deciding when work is heavy enough to deserve the
loop, defining what "good" looks like before you build, and verifying you got there
without grading your own homework.
It uses superpowers as its execution dependency —
the brainstorm / plan / TDD / review skills — a dependency, not a foundation; the execution
layer could be swapped or self-built.
Why this exists
The default AI workflow is a straight line: understand → build → say done. It ships
plausible-but-wrong work, for two reasons the line never addresses:
- No bar. "It runs end-to-end" gets mistaken for "it's correct." Nothing was frozen up
front to check against, so whatever came out becomes the definition of done.
- Self-grading. The same agent that built it judges it. Confirmation bias here is
structural, not a character flaw — in our own logs a detector self-reported
1.00 recall;
an independent test measured 0.17.
So heavy work runs as a closed loop, and every dispatched sub-agent runs the same loop
inside its own scope:
0 classify ─► ① clarify ─► ② freeze acceptance ─► ③ execute ─► ④ verify (independent) ─► ⑤ remediate
│
└──────────── loop until it passes ◄┘
The loop is not the point — the judgment at each step is. Every step below leads with
why. Strip the why and you are left with bureaucracy.
How to run this — read before you start
This skill orchestrates; it does not execute the steps for you. Three rules separate
running the loop from merely reading about it:
- Invoke each step's sub-skill with the Skill tool. The
▸ Invoke markers below are real
instructions, not decoration. Reading this overview does not count as running a step — the
sub-skills carry detail these summaries deliberately omit. Do not substitute your memory of the
gist for actually loading them.
- Build a TodoWrite checklist first. Turn the steps that apply (per this task's weight) into
a TodoWrite list and tick them off as you go, so a skipped step is visible.
- This bundle has no hooks. Nothing auto-triggers or enforces any of this — if you don't
invoke the steps, they don't happen. That is the accepted trade (see "On enforcement").
The steps
Step 0 — Classify the task (the throttle)
Why: not everything deserves the loop. The cost of process must stay below the cost of the
mistake it prevents. Most messages are chat or one-line edits — running a full loop on those is
its own failure mode.
Do: decide what this is — chat / trivial edit / simple doc / design / build /
exploration — and spend ceremony accordingly. Judge by blast radius, not by how long the
request was: a one-line change to shared infrastructure (hooks, schedulers, data pipelines,
eval) is heavy; a long question is not. When unsure, go heavier.
▸ Invoke task-classification.
Step ① — Clarify what you are really doing
Why: a means is not a goal. "Build an oracle" is a means; "the extractions are accurate" is
the goal — chase the real one. And your measure must not depend on the thing it measures
(don't judge extraction quality by the recall of that same extraction).
Do: pin three things — the real goal, constraints + assumptions (each rated importance ×
certainty), and 1–3 success criteria each tagged measurable or judgment (give judgment ones
a semi-objective anchor). Show them to the human before proceeding.
▸ Invoke clarify-intent. Then invoke superpowers brainstorming for solution exploration.
Step ② — Freeze acceptance criteria
Why: if you set the bar after seeing the result, you will set it wherever the result
landed. Freezing is what makes "lower the bar to pass" detectable.
Do: break the work into stages; for each write expected value × how to verify ×
measurable/judgment. Freeze it (the human confirms). After freezing you may only move the bar
toward truth (the table itself was wrong), never down (it turned out hard) — adjudicate
the difference with a time anchor: was the evidence available when you first set the value?
▸ After brainstorming, invoke superpowers writing-plans for the stage breakdown, then
invoke freeze-acceptance to add the frozen bar. (This respects brainstorming's "the only
skill you invoke next is writing-plans" terminal rule — freeze-acceptance runs after writing-plans,
as the upstream judgment step wrapping the plan, not as a competing next-skill.)
Step ③ — Execute against the table
Why: the frozen table should pull the work the whole way, not sit in a drawer until review.
Do: hand execution to superpowers. Carry each stage's expected value × how to verify into
every sub-agent you dispatch — fractal: each runs the same loop in its scope and returns its
own self-check. That self-check is step ③, not step ④.
▸ Invoke execute-with-spec for the hand-off convention, then delegate the actual work to
superpowers executing-plans / subagent-driven-development / test-driven-development /
systematic-debugging.
Step ④ — Verify "done AND good enough" — independently
Why: the builder cannot be the verifier. Their self-check already happened in ③; reusing it
as the gate is the self-grading failure this whole loop exists to stop.
Do: an independent reviewer (≠ the builder) checks each stage against the frozen table
and issues a per-stage verdict. Metric claims — recall, precision, cost, coverage, latency —
get the stricter gate in references/hard-gates.md: the reviewer recomputes ≥3 samples by hand
and does not read the implementation first.
▸ Invoke independent-verify (it draws on references/hard-gates.md); use superpowers
requesting-code-review / verification-before-completion for the mechanics.
Step ⑤ — Remediate
Why: a failed check has exactly three exits, and none of them is "ship it quietly."
Do: pick one and leave a trace — (1) fix at root cause (don't suppress the symptom to
make the verdict look better), (2) fix the table toward truth (with sign-off), or
(3) accept with a known defect (recorded, with a recovery trigger). Re-verify after fixing.
Default to one fix→recheck cycle; if it still fails, escalate to the human instead of
looping forever. When the root cause is a recurring/process problem, push a prevention layer back
upstream (see references/prevention-layers.md).
▸ Invoke remediation-loop; use superpowers receiving-code-review for the posture.
Decision flow
digraph meta_workflow {
"Task arrives" [shape=doublecircle];
"Heavy enough?" [shape=diamond];
"Just do it" [shape=box];
"① clarify" [shape=box];
"② freeze table" [shape=box];
"③ execute" [shape=box];
"④ independent verify"[shape=box];
"Pass?" [shape=diamond];
"⑤ remediate" [shape=box];
"Deliver" [shape=doublecircle];
"Task arrives" -> "Heavy enough?";
"Heavy enough?" -> "Just do it" [label="no (chat / trivial / touches nothing shared)"];
"Heavy enough?" -> "① clarify" [label="yes (design / build / touches shared infra)"];
"① clarify" -> "② freeze table";
"② freeze table" -> "③ execute";
"③ execute" -> "④ independent verify";
"④ independent verify" -> "Pass?";
"Pass?" -> "Deliver" [label="all gates pass"];
"Pass?" -> "⑤ remediate" [label="any fail"];
"⑤ remediate" -> "④ independent verify" [label="re-check (max 1 cycle, then escalate)"];
}
Red flags — you are rationalizing
| Thought | Reality |
|---|
| "It runs, so it's done." | Running ≠ meeting the bar you froze. Check the table. |
| "I'll know good when I see it." | Then you'll call whatever you see good. Freeze the bar first. |
| "I built it and it looks right." | You can't verify your own work. Get an independent check. |
| "This is just a small change." | Judge by blast radius. Touching shared infra is never small. |
| "The metric hit the target." | Did an independent recompute confirm it? Self-reported metrics lie. |
| "It's basically there, I'll lower the bar." | That's not aligning to truth, that's hiding a miss. |
What's mine vs what's superpowers
Delegated to superpowers (install it; do not reinvent): brainstorming, writing-plans,
executing-plans, subagent-driven-development, test-driven-development, systematic-debugging,
requesting-code-review, verification-before-completion, receiving-code-review.
Added here (the judgment superpowers doesn't cover): task classification (the throttle),
the three-piece intent clarification, frozen acceptance tables with the anti-lowering time
anchor, the hard-gates truth table (especially the metric self-review ban), and the
L1–L5 prevention-layer model for remediation.
How this runs — prompt-driven, not enforced
Meta-Workflow is lightweight by design: it ships no hooks, so nothing auto-triggers or
hard-stops you — the discipline lives in the prompts, and you drive it. A model can read these
skills and still skip a step; staying in the driver's seat is the trade for staying lightweight
and portable. If you want hard enforcement — say, a gate that blocks delivery when a frozen
acceptance table has no independent review — references/prevention-layers.md shows how to build
it on your platform.
