# spec-kit-loop

> A Spec Kit extension that engineers safe autonomous agent loops with a maker/checker split, externalized state, and human-in-the-loop guardrails.

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.

## Features
- Maker/checker split — maker can never self-grade its own output
- Checkable done-criteria contract written before the loop runs
- Independent adversarial checker run in a fresh session
- Comprehension-debt ledger that gates the done state
- Human sign-off gate via /speckit.loop.guard
- max_iterations hard ceiling to force human review
- Session-immortal state stored as plain markdown files
- Worktree isolation for each iteration
- Durable memory.md for decisions and dead ends across runs
- Structured verdicts with method and confidence per criterion
- Read-only /speckit.loop.status for session resume
- after_tasks and after_implement hooks for Spec Kit integration
- YAML-based configuration with environment variable overrides
- No external services, MCP servers, or network access required
- Diffable audit trail committed alongside the feature branch

## Integrations
Spec Kit, Claude Code, GitHub Copilot, Cursor, Gemini CLI

## Platforms
API, CLI

## Pricing
Open Source

## Version
v1.0.0

## Links
- Website: https://github.com/formin/spec-kit-loop
- Repository: https://github.com/formin/spec-kit-loop
- EveryDev.ai: https://www.everydev.ai/tools/spec-kit-loop