Skip to content

gozhang2/loop-engineering-kit / skills/spec-to-done

spec-to-done

Verified

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.

FileKindSize
SKILL.mdskill md21.0 KB
references/delivery-contracts.v1.jsonconfig17.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."
          }
        }
      ]
    }
  }
}
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall