spec-kit-loop

spec-kit-loop is an open-source community extension for Spec Kit that operationalizes "Loop Engineering" — a pattern described by Addy Osmani — for spec-driven development workflows. It wraps the build-and-verify phase of a Spec Kit project, turning an open-ended implement step into a bounded, independently graded, and human-signed-off loop. The extension is released under the MIT license by the GitHub user formin and requires Spec Kit >=0.2.0.

What It Is

spec-kit-loop is a file-based discipline layer that makes autonomous agent loops safe and reviewable inside Spec Kit. Rather than letting an agent iterate freely and self-certify completion, the extension enforces a maker/checker split: the maker agent produces increments but can never mark its own work done, while an independent checker — run in a fresh session — adversarially grades each increment against explicit, checkable done-criteria. All loop state is stored as plain markdown files in the repository, making it diffable, PR-reviewable, and session-immortal.

The Three Failure Modes It Addresses

The extension is explicitly designed around three failure modes that emerge when coding agents run with high autonomy:

• Unattended verification — the model that wrote the code grades its own homework, with no independent check.
• Comprehension debt — the loop changes more than the human understands, and the gap compounds silently.
• Cognitive surrender — the human starts accepting whatever the loop emits because checking it is effort.

Each command in the extension is a direct countermeasure to one or more of these failure modes.

Commands and Workflow

The extension adds five commands to the Spec Kit workflow:

• /speckit.loop.define — writes the recursive goal plus explicit, checkable done-criteria, a budget (max_iterations), and guardrail policy into a contract before the loop runs. Refuses open-ended criteria like "it works."
• /speckit.loop.run — the maker step: produces one coherent increment toward a criterion, externalizes it to iterations.md and memory.md, marks criteria maker-ready (never done), and stops with an explicit handoff to the checker.
• /speckit.loop.check — the independent checker step, designed to run in a fresh session or as a separate sub-agent. It tries to make each criterion fail at the primary source and records a structured verdict (pass/fail/uncertain, method, confidence) in verdicts.md.
• /speckit.loop.guard — the only path to done: sweeps comprehension debt, flags unattended verifications, asks pointed questions about real changes, and requires a recorded human sign-off. All three gates (checker-pass, no blocking debt, human sign-off) must be satisfied.
• /speckit.loop.status — a read-only snapshot that renders current state and recommends exactly one next action; serves as the session-resume entry point after a context reset.

Two optional hooks integrate with the core Spec Kit flow: after_tasks prompts to run define, and after_implement prompts to run check.

Architecture: File-Based, No External Dependencies

All loop state lives in specs/<feature>/loop/ as ordinary markdown files (loop.md, iterations.md, verdicts.md, debt.md, memory.md). The commands are plain prompt files — no MCP servers, no external APIs, no network access beyond the initial specify extension add download. This means the loop state is fully portable, diffable in pull requests, and shared across every agent and teammate working on the feature. The conversation is disposable; the state is not.

Configuration is managed via a YAML file at .specify/extensions/loop/loop-config.yml, with precedence from extension defaults through config file, environment variables (SPECKIT_LOOP_*), and per-invocation key=value arguments.

Update: v1.0.0 — Initial Release

The repository was created and the first release (v1.0.0 — Loop Engineering for Spec Kit) was published on 2026-06-14. The extension is listed in the Spec Kit community extension catalog and can be installed by name (specify extension add loop) once the community catalog is enabled, or pinned directly from the release URL. It is compatible with any agent Spec Kit supports, including Claude Code, GitHub Copilot, Cursor, and Gemini CLI.