spec-to-done

name	spec-to-done
description	Drive a reviewed spec to evidence-backed, integrated closure — grill the spec at intake until it is fully understood, decompose it into owned work items, build each against targeted criteria, gate every merge per item, maintain a criterion-to-evidence ledger, and close only when an integrated done gate passes. Use when implementing an accepted spec with one agent or a team, and "done" must mean the integrated whole works together, not that an individual task went green.
license	Apache-2.0

Spec To Done

Drive a reviewed spec to delivered, integrated closure. The output is a closure record backed by a criterion-to-evidence ledger and a green integrated check — not a pile of individually green tasks.

This is a portable workflow, not a runtime. It works with one agent building items sequentially or a team of implementers in parallel, on any repository, task system, or none.

Treat it as a protocol, not a procedure: teams may carry the messages in JSON, markdown, issues, or PR comments. Six invariants make the loop trustworthy, whatever the carrier:

• Every worker gets bounded work.
• Every handback is reviewable.
• Every gate decision explains the basis for trust or rejection.
• Every acceptance criterion maps to evidence, a waiver, or a named blocker.
• Every owner-only decision is escalated, never improvised.
• Closure never overclaims.

Everything else — item sizing, ordering, tooling, how hard to inspect a given handback — is supervisor judgment, and good supervisors will invent moves this file does not list. The protocol's job is to make those moves inspectable, not to replace them.

Evidence First

"Done" in this loop is an evidence claim, not a status update. Every part of the loop exists to produce, check, or record evidence:

• Every claim names something inspectable — a commit, diff, test, check, run, artifact, screenshot, review, trace, or recorded waiver. If a reader cannot open it, it is not evidence.
• Evidence covers process as well as result. The result evidence says what was achieved; the work trace — how it was done — says whether to trust it.
• The criterion-to-evidence ledger is the loop's spine. Gates read evidence against criteria; they do not read narratives, confidence, or effort.
• No local evidence, no merge. No integrated evidence, no closure. Task-local green is not done — it is supporting evidence for one item.
• Missing evidence is never papered over: a criterion is open, blocked, or carries a waiver recorded by the decision owner. A waiver is a decision, not missing evidence.

Inputs

• Reviewed spec and acceptance criteria (with stable criterion IDs).
• Required implementation and validation items, or enough context to decompose them.
• Evidence expectations: tests, checks, artifacts, screenshots, review notes, commits, or explicit waivers.
• Integration surface: the branch or equivalent place where items merge and the whole is checked.

Roles

The loop is supervisor-led — that is where its results come from:

• Supervisor (an agent session or a human acting as tech lead): owns the reviewed spec, decomposes it, dispatches items, holds both gates, maintains the ledger, and is the only party that escalates to the decision owner. The supervisor reviews delivered work, never self-reports.
• Implementers (worker agents or humans): build one item at a time against its dispatch. They see their dispatch, not the loop's history, and they never grade their own integrated closure.
• Decision owner (a human): owns scope, waivers, and irreversible calls. The loop pauses for them at the enforced escalation triggers; it never substitutes its own judgment for theirs.

The supervisor's two gates sit at two altitudes: the per-item merge gate asks "did this item earn its merge?", the integrated done gate asks "did the whole earn closure?".

Running solo — one agent building items in sequence — still uses this shape: run the gates as explicit supervisor moves against the handback contract, never as a vibe check on your own memory of the work.

The Loop

intake grill -> decompose -> build per item -> merge gate -> evidence ledger -> integrated done gate -> close or repair

Routing — the gates decide where work goes next:

Gate	Outcome	Route
intake grill	a delivery-blocking ambiguity the spec itself cannot answer	grill the decision owner; record answers as spec addenda
merge gate	pass	merge the item, update the ledger, take the next item
merge gate	fail	send back: rework the same item against its targeted criteria
merge gate	marked non-blocking (spec permits)	record in the ledger as non-required; it does not count toward done-gate blockers
merge gate	handback blocked only by environment or tooling, artifacts inspectable	supervisor verifies and integrates on the worker's behalf, on the record
any dispatch	underspecified for the item's decisions	implementer bounces it back; supervisor re-dispatches
done gate	every blocking criterion proven and integrated check green	close
done gate	red	create a repair item, pass it through the merge gate, rerun the done gate
done gate	remaining blockers are decision-owner evidence only	conditional close: record proven rows, keep blocked rows blocked, escalate the remaining decision
any step	transient failure (rate limit, restart, transport)	bounded wait, retry; do not wedge
any step	an enforced escalation trigger fires	stop; escalate to the decision owner

Contracts: Semantics First, Schema When Needed

Coordination flows through durable, structured messages — not shared context. Workers get the dispatch, not the loop's history; the supervisor reads handbacks, inspects artifacts, and reviews the bounded work trace — it does not re-read raw transcripts. If it is not in the dispatch, the implementer does not assume it; if it is not in the handback, the supervisor does not go fishing for it.

The contracts are what keep the loop from becoming vibes: the dispatch says what the worker owns; the handback says what was done and how to review it; the verdict says why the supervisor trusts or rejects it; the ledger says what evidence proves which criterion; the closure note says what is actually done, blocked, or waived. Their field names are the loop's semantic base vocabulary, defined canonically in references/delivery-contracts.v1.json (bundled with this skill). The schema is canonical; the carrier is flexible — JSON, markdown, issue templates, PR comments, or task-system fields all work when they map back to the same concepts.

Contract	Direction	Carries
Dispatch contract	supervisor → implementer	item id; owned criterion IDs with statements; evidence expectation per criterion; scope boundary; constraints; integration surface
Handback contract	implementer → supervisor	item id; owned criteria; what changed (refs); checks run with exact commands and results; evidence mapped per criterion; a work trace — significant actions in order, failures encountered and their resolutions, deviations from the dispatch, optional ref to the full raw trace; risks; open questions; self-status (ready-for-gate / blocked / needs-decision)
Gate verdict contract	supervisor → implementer	merge, send back, or non-blocking; a send-back names the failed criteria and the evidence that will prove the fix — "not good enough" without a named criterion is not a verdict; a merge or non-blocking verdict states its basis for trust in notes (what the gate actually checked); verdicts may carry rulings on the handback's open questions
Escalation contract	supervisor → decision owner	the trigger; ledger state; the smallest decision needed; options and a recommendation

Rulings are loop memory: carry them into later dispatches as constraints, or later workers will re-decide the same questions differently.

Enforcement comes in two modes:

• Default: a handback that cannot be reviewed against the base contract — what changed, what ran, where the evidence is, what remains risky, what is still open — is returned. A field that is present but malformed is gate discretion: accept it by recording the deviation in the verdict, or send it back. What is forbidden is silent acceptance — the contract is a protocol, not a bureaucracy.
• Strict mode (turn it on for public records, evals and dogfood runs, regulated or security-sensitive work, many-agent coordination, and when debugging a failed loop): validate records against the bundled schema exactly; malformed or incomplete handbacks are returned unread, before any evidence review.

In either mode, an implementer that receives an underspecified dispatch bounces it back instead of guessing, and the merge gate judges what was handed back — it does not reconstruct what the implementer meant.

1. Intake Grill

Before decomposing, the supervisor proves to itself that it understands the spec — misreading it here poisons every dispatch downstream.

• Read the whole spec: criteria, non-goals, constraints, flagged assumptions, and the grill record it carries from its own review.
• Grill the spec before grilling anyone: for every question you have, check whether the artifact already answers it. A question the spec answers is not asked.
• For delivery-blocking ambiguity the spec cannot answer, grill the decision owner — pointed, bounded questions, exactly like the front loop's grill. Use the grill-me skill (from mattpocock/skills) as the interview engine when it is available.
• Do not re-litigate the accepted spec: intake questions resolve ambiguity about what to deliver; they do not reopen decided trade-offs. If an answer would change the contract or criteria, that is a scope-change escalation, not a quiet patch.
• Record every answer as a dated addendum in or linked from the spec — so implementers inherit it through their dispatches, not through memory.

Exit when you can state, from the artifact alone, what done means for every blocking criterion.

2. Decompose

Turn the reviewed spec into owned work items.

• Map every blocking criterion to one or more implementation or validation items. Carry the spec's criterion IDs onto the items: those IDs are the join key across the decomposition, the ledger, and the closure note.
• A criterion that asserts cross-item behavior (a round-trip, an end-to-end flow, a whole-artifact property) becomes its own integrated validation item — it cannot be proven by any single implementation item. Prefer giving that item to an implementer with different failure modes than the builders — a different model family when available; a single-model setup is fine, like skipping peer review is.
• Items may define item-local criteria (e.g. ITEM-03.C1) to make their own merge gate concrete; only the spec's criteria enter the ledger.
• Identify dependencies and required ordering.
• State expected evidence for each item before building it.
• Mark optional or deferred work as non-blocking only when the spec permits it.
• Keep the decomposition small enough that item handbacks can be reviewed against clear criteria.

3. Build Per Item

Each implementer works against its item's dispatch — the targeted criteria and evidence expectations it names.

• Keep changes scoped to the assigned item; respect the dispatch's scope boundary.
• Preserve public/private boundaries from the spec.
• Record local checks and artifacts as supporting evidence while building — evidence is captured, not reconstructed afterward. The same goes for the work trace: keep it as you go (actions, failures and their resolutions, deviations), because a trace written from memory at the end is a narrative, not a trace.
• Hand back per the handback contract.

4. Per-Item Merge Gate

Review each handback before it enters the integration surface.

1. Return a handback that is not reviewable against the base contract; in strict mode, reject missing or malformed required fields unread, before any evidence review.
2. Compare the item against only its targeted criteria.
3. Confirm the recorded checks and evidence match the item's risk.
4. Review the work trace for how, not just what: a claimed check must postdate the last change; thrashing marks a fragile area deserving a harder look at the diff; undeclared shortcuts or deviations are a send-back on their own. Process smells calibrate how deep to inspect.
5. Inspect the diff or artifact for scope creep, missing evidence, and unresolved comments.
6. Deliver a gate verdict: merge, send back, or mark non-blocking if the spec permits that outcome — a non-blocking item is recorded in the ledger as non-required and does not count toward done-gate blockers. Whatever the format, the verdict records the basis for trust: what was inspected, what evidence was relied on, and any ruling or accepted deviation that affects later work.

One recovery route sits between send-back and silent acceptance: when a handback is blocked only by environment or tooling (a sandbox that cannot commit, a broken runner) and the artifacts are inspectable, the supervisor may verify the work and integrate it on the worker's behalf — recording what failed, why it was environmental, and what was inspected. Work blocked on a missing decision, missing evidence, or incomplete implementation still goes back or escalates.

Stop here after merge or send-back. This gate does not prove the full spec.

5. Evidence Ledger

Maintain the proof map as items land — one row per criterion:

Criterion	Required?	Evidence	Integrated status	Notes

• Every proven or waived row names inspectable evidence (see Evidence First) — for a waiver, that is the recorded waiver decision — never a bare claim. Open and blocked rows say what they are waiting on. The row shape is in references/delivery-contracts.v1.json.
• Each row has exactly one integrated status: open (no proof yet), blocked (proof depends on unmerged work), proven (integrated evidence in hand), or waived (recorded decision by the owner). The done gate reads these statuses; do not invent softer ones.
• Update the ledger after every merge, rework, or waiver; track required items separately from optional ones.
• Never treat a green item branch or a local item check as integrated evidence.

6. Integrated Done Gate

Run this gate only after every required implementation and validation item is merged into the integration surface.

1. Confirm no required items remain open, failed, or waiting for repair.
2. Read the ledger: which blocking criteria are proven or waived, which are blocked — and who controls each missing proof.
3. Run or verify the required integrated check after all required items merged. The integrated check is whatever proves the whole works together for this deliverable — a test/build/CI run for code, or a render/lint/link/interaction pass and a boundary scan for docs, templates, or content kits.
4. Inspect integrated evidence for cross-item regressions, missing migrations, broken docs, stale assumptions, and acceptance gaps.
5. Decide the outcome, and only one of these three:
   • Full close — every blocking criterion proven or waived, integrated check green.
   • Repair — missing proof is within the loop's control: create a repair item, rerun both gates.
   • Conditional close — the only remaining gaps are decision-owner evidence: record proven vs blocked, escalate the smallest remaining decision (produce the evidence, or waive per criterion).

"Proven" always means the criterion as written: if the criterion says "for a real trip," synthetic evidence goes in the row's notes and the status stays blocked — never soften a status to force a close.

One more honest outcome exists besides close and repair: when every remaining blocking row is blocked solely on evidence the decision owner must produce, the gate may close conditionally — record what is proven, keep the blocked rows blocked, and escalate the remaining decision (produce the evidence, or waive per criterion) to the owner. A conditional close that says so plainly beats a full close built on stretched evidence.

The done gate lives here, inside the workflow — keep it in the loop rather than in a separate checklist that can drift out of date.

7. Self-Heal And Repair

When a failure is transient, recover before declaring the spec blocked.

• Retry rate-limit, restart, transport, and unavailable-service failures after a bounded wait.
• Re-run checks when the previous result is stale or detached from the final integrated state.
• If integration is red, record the failing criterion, check, or behavior; create a repair item with targeted criteria and expected evidence — scoped to the failure, like any other item.
• Merge the repair through the per-item gate, then rerun the integrated done gate.

Transient failures self-heal; judgment calls escalate — next section.

Human Escalation (Enforced)

The loop MUST stop and escalate to the human decision owner — per the escalation contract — when any of these triggers fires. Pushing through one is a supervisor failure, not initiative:

• Scope change: required work the spec does not cover, or a criterion that must be reworded to be satisfiable.
• Waiver: only the decision owner can waive a criterion.
• Contradiction: the spec is internally inconsistent.
• No progress: the same item fails its gate twice without new information, or a repair loop repeats without progress.
• Irreversible or outward-facing action the spec does not explicitly authorize: publishing, deploying, deleting, spending, or messaging anyone outside the loop.
• Policy, privacy, or security uncertainty: when it is unclear whether an action crosses such a boundary, the answer is the owner's, not the loop's.

Escalating late is a defect. Escalating with the ledger state, the smallest decision needed, and a recommendation is cheap; unwinding an unauthorized irreversible action is not.

Common Failure Modes

Failure	Counter-rule
Closing on task-green: all items merged, so the spec is declared done.	Closure requires the ledger complete and the integrated check green.
Evidence theater: ledger rows cite claims with nothing inspectable behind them.	Every row names a check, artifact, commit, review, or recorded waiver.
Self-grading: an implementer approves its own handback or closure.	The supervisor holds both gates; it reviews delivered work, not self-reports.
Free-form handbacks: the worker returns whatever it wants.	A handback that is not reviewable against the base contract is returned; strict mode validates exactly.
Result-only review: the gate reads the diff but never how it was produced.	The work trace is part of the gate; a check that ran before the final change proves nothing.
Misread spec: decomposition starts from what the supervisor assumed, not what the spec says.	Intake answers every question from the artifact first and grills the owner on the rest; answers land as spec addenda.
Context smuggling: workers coordinate through shared conversation state instead of the contracts.	Dispatches and handbacks are durable, structured, and self-contained.
Stale checks: the integrated check ran before the last merge.	The closing check must postdate the final required merge.
Unbounded repair: a repair item grows into a new feature.	Repair items get targeted criteria and expected evidence, like any item.
Wedging: a transient failure is escalated as terminal.	Bounded retry first; escalate only on repeat-without-progress.
Silent autonomy: the loop pushes through an escalation trigger to keep moving.	The enforced triggers stop the loop; the decision owner decides.
Stretched close: a conditional close presented as a full one.	The closure note names the closure state, the blocked rows, and the escalated decision.
Bypass-by-environment: the environment-blocker route used for incomplete work.	The route applies only when artifacts are inspectable and the blocker is tooling; the verdict records what was inspected.

Closure Note

The final closure note (shape in references/delivery-contracts.v1.json) states:

• Closure state: done or conditional — a conditional close names the blocked rows and the decision escalated to the owner.
• Reviewed spec link.
• Review authority: the supervisor who held both gates (and that it was not an implementer).
• Integration surface reference, and the ledger location.
• Required implementation and validation items merged.
• Integrated checks run and their results.
• Escalations raised and their outcomes, or an explicit statement that none fired.
• Remaining non-blocking follow-ups, or an explicit statement that none remain.

Example

The loop-engineering-kit repository (github.com/gozhang2/loop-engineering-kit) publishes real run records for this skill under examples/ — intake addenda, dispatches, handbacks, verdicts including a send-back, a repair item, the evidence ledger, and a conditional close.