Loop Engineering Kit

Two reusable skills for making agent-assisted delivery less lossy:

• idea-to-spec turns a rough idea into a reviewed, durable spec: frame → research → grill → draft → review → revise → optional peer review (best via other models) → verdict. The grill is a required interview step that challenges the idea instead of transcribing it — the guard against an agent drafting confidently on a shaky premise. Peer review runs on the review-ready spec and adds an independent second model or human when you have one; skipping it is fine, faking it is not.

  

• spec-to-done picks up the accepted spec and drives it to shipped work with evidence-backed closure: intake grill → decompose → build per item → per-item merge gate → evidence ledger → integrated done gate → close or repair. The intake grill is the supervisor proving it understands the spec — every question the artifact answers is not asked; the rest go to the decision owner. "Done" means the integrated whole is proven against the acceptance criteria — a task going green is supporting evidence, never closure.

  

These are loops, not pipelines — the dashed arrows are where the quality lives. Review routes thin evidence back to research and unresolved intent back to the grill; the merge gate rejects items into rework; a red done gate dispatches a repair item and runs both gates again. And when the only gaps left need evidence that only the decision owner can produce, the done gate closes conditionally and escalates — it never stretches evidence to claim a full close. The real record below ends exactly that way.

Both loops came out of running an agent team unattended and repeatedly hitting the same failure: work that looks done — green tasks, merged branches, confident handoffs — while the original spec was never actually closed. The kit packages the two loops that fixed that, as they actually run, hardening lessons included.

The Ideas

"Done" is an evidence claim, not a status update. Every claim in the loop names something a reader can open — a commit, test, check run, artifact, review, trace, or recorded waiver. Gates read evidence against criteria; they do not read narratives, confidence, or effort.

Protocol, not procedure — but with teeth at the critical stages. Teams carry the messages in JSON, markdown, issues, or PR comments. Six invariants hold 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 is supervisor judgment. The enforcement sits exactly where trust enters: the grills are required, the reviewer is never the drafter, strict mode returns malformed records unread, six escalation triggers stop the loop for a human, and the done gate closes fully, repairs, or closes conditionally — it never stretches evidence into a full close.

Contracts are a shared language, not a file format. The bundled JSON Schemas define the loop's semantic vocabulary — dispatch, handback, gate verdict, escalation, ledger row, closure note. The schema is canonical; the carrier is flexible; strict mode (for public records, evals, regulated work, many-agent runs) validates exactly.

The supervisor reviews process, not just results. Every handback carries a work trace — significant actions in order, failures and their resolutions, deviations from the dispatch — because the result evidence says what was achieved, and the trace says whether to trust it. A claimed check that predates the last change proves nothing.

Quick Start

The skills use the open Agent Skills format (SKILL.md + YAML frontmatter), supported by Claude Code, Codex, Cursor, Gemini CLI, and dozens of other tools.

1. Install: copy skills/idea-to-spec/ and skills/spec-to-done/ into your tool's skills directory (for example ~/.claude/skills/ for Claude Code).
2. Run the front loop: give the agent a rough idea and ask it to run idea-to-spec. Answer the grill questions when they come — that interview is the point, not a formality. The grill composes with Matt Pocock's popular grill-me skill as the interview engine when you have it installed — referenced, not vendored, so you always run whatever version you have and upstream improvements flow to you. Without it, the step still runs from the rules in the skill.
3. Run the back loop: hand the accepted spec to spec-to-done. Expect a criterion-to-evidence ledger and an integrated done-gate verdict, not just "all tasks complete."

No skills support? Each SKILL.md is plain markdown — paste it into any capable agent's context, or follow it yourself as a facilitator/tech-lead checklist. Real run records live in examples/.

How This Relates to Spec-Driven Development

Spec-driven development tools (GitHub Spec Kit, AWS Kiro, BMAD, OpenSpec, …) formalize the middle of the pipeline: spec → plan → generated code. This kit is method, not tooling, and it concentrates on the two ends most SDD flows underweight:

• Before the spec: the grill. Most flows accept the initial prompt as intent. This loop makes the agent interrogate the idea after research — when its questions can be specific about real trade-offs — and forces unanswered questions to surface as flagged assumptions rather than silent defaults.
• After the tasks: the integrated done gate. Most flows end when generated tasks complete. This loop ends when every blocking criterion maps to bounded evidence and an integrated check proves the pieces work together.

Use it standalone, or alongside any SDD tool as the intent-sharpening front door and the closure-proving back door.

Borrowed From Academic Practice

The front loop is deliberately shaped like the research lifecycle — these mechanisms have survived a century of adversarial use:

In the kit	Academic ancestor
Research with a source audit, named prior art, and graded confidence	Literature review discipline: systematic-review audit trails (PRISMA-style), related-work sections, evidence grading (GRADE-style)
The grill — pointed questions after research, including a kill question	The thesis proposal defense: the committee challenges the plan before the work starts, and "don't do this" is a legitimate outcome
Acceptance criteria with evidence expectations, fixed before building	Pre-registration / registered reports: commit to the evaluation method before results exist, so the criteria can't quietly bend to fit the outcome
Independent review, plus an optional peer-review stage (second model or human) with panels and recorded rebuttals	Peer review: reviewers are not the authors, panels read with distinct lenses, and revise-and-resubmit is a loop, not an insult. Baseline independence (a fresh session) is always required; the stronger stage is optional because not everyone has a second reviewer
Flagged assumptions carried in the spec by name	Threats-to-validity sections: name what could invalidate the work instead of hoping nobody asks
The evidence ledger and integrated done gate (back loop)	Artifact evaluation and reproducibility badging: the claim only counts when an independent check can reproduce it
Work traces in every handback — how the result was produced	The lab notebook and methods section: results without methods are anecdotes

What's In The Kit

Path	Purpose
skills/idea-to-spec/	The idea-to-spec workflow, bundling its research-packet schema.
skills/spec-to-done/	The spec-to-done workflow — supervisor-led, evidence-first, with enforced human escalation — bundling its delivery-contracts schema (dispatch, handback, gate verdict, escalation, ledger row, closure note).
templates/base-template.html	Generic durable-document template carrying the common chrome: left navigation, badges, Why/What/How/Why Not shape, inline comments. Start here for any new document type.
templates/spec-template.html	Durable single-file spec template: TL;DR, linked index, Why/What/How/Why Not, operating model, test coverage — with inline comments.
templates/research-report.html	Bounded research-report template — summaries, source audit, limitations; never raw dumps — with inline comments.
examples/travel-expense-prep-agent/	Real loop run: the full spec (rendered · source) and research report (rendered · source) from idea-to-spec, plus a curated spec-to-done delivery record with dispatches, handbacks, gate verdicts, integrated evidence, and conditional closure.
assets/loop-idea-to-spec.svg, assets/loop-spec-to-done.svg	The animated loop diagrams above.

This is deliberately not a runtime, orchestration service, or eval harness. The value is the workflow and the evidence contract, not another tool to install.

The Templates: Inline Comments, No Server

Every HTML template in this kit is a durable single-file artifact with a built-in review workflow — this is the feature that makes the review and peer-review stages practical without any infrastructure:

• Inline comments: open the file in a browser, select any text, click Add Comment. Comments are stored inside the HTML file itself (as embedded JSON), so the document and its review travel together — mail it, commit it, open it years later.
• Save writes the file back: Save (or ⌘/Ctrl+↩) writes the updated HTML — comments included — straight back to disk via the browser's file picker, with a download fallback. Esc closes the panel.
• Works anywhere: plain file://, no server, no build step, no network.
• Left navigation: at wide viewports the index docks as a fixed nav bar (base and spec templates), so long documents stay scannable.

Open them rendered, straight from this repo's GitHub Pages: base template · spec template · research report template — select text and try the comment widget right there. The real run's prep-pack evidence renders too.

All templates share one identical comment-widget block, marker-fenced as loop-kit:comment-widget. Because the files must stay self-contained, reuse is enforced duplication, not a shared script: edit the block in one template, copy it verbatim to the others — the kit's upstream test fails if the copies drift. To build your own document type, start from base-template.html, which already carries the full common chrome.

Reuse Terms

First-party content is released under the Apache License, Version 2.0 — use, copy, modify, distribute, and sublicense per LICENSE. Third-party names, trademarks, and logos are not included in that grant.

The kit was extracted from a private agent-farm setup. Internal ids, local paths, raw logs, runtime wiring, and operator-only artifacts were stripped because they are not portable and can expose private execution context; the loops, templates, and contracts here are the reusable parts.