gozhang2/loop-engineering-kit / skills/spec-to-done
spec-to-done
VerifiedDrive 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.0 KB |
| references/delivery-contracts.v1.json | config | 17.3 KB |
references/delivery-contracts.v1.json
View on GitHub{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "delivery-contracts.v1",
"title": "delivery-contracts.v1",
"description": "Message and record contracts for the spec-to-done loop. Four messages (dispatch, handback, gate_verdict, escalation) and two records (ledger_row, closure_note). Evidence is the load-bearing type — covering process as well as result (the handback's work_trace): every claim carries evidence_ref entries pointing at something a reader can open — never a bare assertion. These field names are the loop's semantic base vocabulary: the schema is canonical, the carrier is flexible — markdown, issue templates, PR comments, or task-system fields are acceptable when they map back to the same concepts. Strict mode validates against this schema exactly.",
"oneOf": [
{
"$ref": "#/$defs/dispatch"
},
{
"$ref": "#/$defs/handback"
},
{
"$ref": "#/$defs/gate_verdict"
},
{
"$ref": "#/$defs/escalation"
},
{
"$ref": "#/$defs/ledger_row"
},
{
"$ref": "#/$defs/closure_note"
}
],
"$defs": {
"evidence_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"commit",
"diff",
"test",
"check",
"run",
"artifact",
"screenshot",
"review",
"waiver",
"trace"
],
"description": "What kind of inspectable thing this points at."
},
"ref": {
"type": "string",
"minLength": 1,
"description": "URL, id, path, or command that lets a reader open or reproduce the evidence."
},
"note": {
"type": "string",
"description": "Optional one-line context for the reference."
}
}
},
"dispatch": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"item_id",
"criteria",
"scope_boundary",
"constraints",
"integration_surface"
],
"properties": {
"type": {
"const": "dispatch"
},
"item_id": {
"type": "string",
"minLength": 1
},
"criteria": {
"type": "array",
"minItems": 1,
"description": "The criteria this item owns. An implementer receiving less than this bounces the dispatch back.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"criterion_id",
"statement",
"evidence_expectation"
],
"properties": {
"criterion_id": {
"type": "string",
"minLength": 1
},
"statement": {
"type": "string",
"minLength": 1
},
"evidence_expectation": {
"type": "string",
"minLength": 1
}
}
}
},
"scope_boundary": {
"type": "string",
"minLength": 1,
"description": "What this item must not touch."
},
"constraints": {
"type": "array",
"description": "Constraints inherited from the spec. Explicitly empty beats silently missing.",
"items": {
"type": "string",
"minLength": 1
}
},
"integration_surface": {
"type": "string",
"minLength": 1
}
}
},
"handback": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"item_id",
"criteria_owned",
"changes",
"checks",
"evidence",
"work_trace",
"risks",
"open_questions",
"self_status"
],
"description": "In strict mode, a handback missing or malforming a required field is returned unread; in default mode the gate returns handbacks that are not reviewable against these concepts, and records accepted deviations in the verdict.",
"properties": {
"type": {
"const": "handback"
},
"item_id": {
"type": "string",
"minLength": 1
},
"criteria_owned": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
},
"changes": {
"type": "array",
"minItems": 1,
"description": "What changed: artifact, diff, or file references.",
"items": {
"type": "string",
"minLength": 1
}
},
"checks": {
"type": "array",
"description": "Checks run locally, with exact commands and results.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"command",
"result"
],
"properties": {
"command": {
"type": "string",
"minLength": 1
},
"result": {
"type": "string",
"minLength": 1
}
}
}
},
"evidence": {
"type": "array",
"minItems": 1,
"description": "Evidence mapped per owned criterion — the heart of the handback.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"criterion_id",
"refs"
],
"properties": {
"criterion_id": {
"type": "string",
"minLength": 1
},
"refs": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/evidence_ref"
}
}
}
}
},
"risks": {
"type": "array",
"description": "Known risks or limitations. Explicitly empty beats silently missing.",
"items": {
"type": "string",
"minLength": 1
}
},
"open_questions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"self_status": {
"type": "string",
"enum": [
"ready-for-gate",
"blocked",
"needs-decision"
]
},
"work_trace": {
"type": "object",
"additionalProperties": false,
"required": [
"summary",
"failures_encountered",
"deviations"
],
"description": "Bounded account of HOW the work was done — not a transcript. Result evidence says what was achieved; the work trace says whether to trust it.",
"properties": {
"summary": {
"type": "array",
"minItems": 1,
"description": "The significant actions in order: edits, commands, decisions.",
"items": {
"type": "string",
"minLength": 1
}
},
"failures_encountered": {
"type": "array",
"description": "Failures hit during the work and how each was resolved. Explicitly empty beats silently missing.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"what",
"resolution"
],
"properties": {
"what": {
"type": "string",
"minLength": 1
},
"resolution": {
"type": "string",
"minLength": 1
}
}
}
},
"deviations": {
"type": "array",
"description": "Shortcuts taken, scope touched beyond the dispatch, or anything the dispatch did not anticipate. Explicitly empty beats silently missing.",
"items": {
"type": "string",
"minLength": 1
}
},
"trace_ref": {
"$ref": "#/$defs/evidence_ref",
"description": "Optional pointer to the full raw trace (session log, event stream, CI log) when the runtime keeps one."
}
}
}
}
},
"gate_verdict": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"item_id",
"verdict",
"reasons"
],
"properties": {
"type": {
"const": "gate_verdict"
},
"item_id": {
"type": "string",
"minLength": 1
},
"verdict": {
"type": "string",
"enum": [
"merge",
"send-back",
"non-blocking"
]
},
"reasons": {
"type": "array",
"description": "For send-back: at least one reason tied to a named criterion, with the evidence that will prove the fix.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"criterion_id",
"reason",
"evidence_expected"
],
"properties": {
"criterion_id": {
"type": "string",
"minLength": 1
},
"reason": {
"type": "string",
"minLength": 1
},
"evidence_expected": {
"type": "string",
"minLength": 1
}
}
}
},
"notes": {
"type": "string",
"description": "Optional: what the gate actually checked and why the verdict holds."
},
"rulings": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Optional rulings on the handback's open questions. Rulings are loop memory: carry them into later dispatches as constraints."
}
},
"allOf": [
{
"if": {
"properties": {
"verdict": {
"const": "send-back"
}
}
},
"then": {
"properties": {
"reasons": {
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"verdict": {
"enum": [
"merge",
"non-blocking"
]
}
}
},
"then": {
"required": [
"notes"
],
"properties": {
"notes": {
"minLength": 1
}
},
"description": "A merge or non-blocking verdict must state its basis for trust in notes; a send-back carries its basis in reasons."
}
}
]
},
"escalation": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"trigger",
"ledger_ref",
"decision_needed",
"options",
"recommendation"
],
"properties": {
"type": {
"const": "escalation"
},
"trigger": {
"type": "string",
"enum": [
"scope-change",
"waiver",
"contradiction",
"no-progress",
"irreversible-action",
"policy-uncertainty"
]
},
"ledger_ref": {
"type": "string",
"minLength": 1,
"description": "Where the current ledger state can be read."
},
"decision_needed": {
"type": "string",
"minLength": 1,
"description": "The smallest decision that unblocks the loop."
},
"options": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
},
"recommendation": {
"type": "string",
"minLength": 1
},
"item_id": {
"type": "string",
"minLength": 1,
"description": "Optional: the item that triggered the escalation, for mechanical traceability."
}
}
},
"ledger_row": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"criterion_id",
"required",
"evidence",
"integrated_status",
"notes"
],
"properties": {
"type": {
"const": "ledger_row"
},
"criterion_id": {
"type": "string",
"minLength": 1
},
"required": {
"type": "boolean"
},
"evidence": {
"type": "array",
"items": {
"$ref": "#/$defs/evidence_ref"
}
},
"integrated_status": {
"type": "string",
"enum": [
"open",
"blocked",
"proven",
"waived"
],
"description": "The done gate reads exactly these; do not invent softer ones."
},
"notes": {
"type": "string"
}
},
"allOf": [
{
"if": {
"properties": {
"integrated_status": {
"const": "proven"
}
}
},
"then": {
"properties": {
"evidence": {
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"integrated_status": {
"const": "waived"
}
}
},
"then": {
"properties": {
"evidence": {
"minItems": 1
}
},
"description": "A waived row's evidence points at the recorded waiver decision."
}
}
]
},
"closure_note": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"closure_state",
"spec_ref",
"review_authority",
"integration_ref",
"ledger_ref",
"items_merged",
"integrated_checks",
"escalations",
"follow_ups"
],
"properties": {
"type": {
"const": "closure_note"
},
"spec_ref": {
"type": "string",
"minLength": 1
},
"review_authority": {
"type": "string",
"minLength": 1,
"description": "The supervisor who held both gates; must not be an implementer."
},
"integration_ref": {
"type": "string",
"minLength": 1
},
"ledger_ref": {
"type": "string",
"minLength": 1
},
"items_merged": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
},
"integrated_checks": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"check",
"result"
],
"properties": {
"check": {
"type": "string",
"minLength": 1
},
"result": {
"type": "string",
"minLength": 1
}
}
}
},
"escalations": {
"type": "array",
"description": "Escalations raised and their outcomes. Explicitly empty means none fired.",
"items": {
"type": "string",
"minLength": 1
}
},
"follow_ups": {
"type": "array",
"description": "Remaining non-blocking follow-ups. Explicitly empty means none remain.",
"items": {
"type": "string",
"minLength": 1
}
},
"closure_state": {
"type": "string",
"enum": [
"done",
"conditional",
"not-closed"
],
"description": "'conditional' when proven rows closed but blocking rows remain blocked on decision-owner evidence, with the remaining decision escalated; 'done' only when every blocking criterion is proven or waived."
}
},
"allOf": [
{
"if": {
"properties": {
"closure_state": {
"const": "conditional"
}
}
},
"then": {
"properties": {
"escalations": {
"minItems": 1
}
},
"description": "A conditional close must carry the escalation of the remaining decision."
}
}
]
}
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |