spec-loop

Specifications your agent keeps, in a loop you steer.

spec-loop is for product owners who build with a coding agent: the agent maintains one JSON model per feature, projected into Markdown documents you read and edit, and every edit comes back to it over MCP.

Get started Read the method

Works the same with Gemini CLI, Claude Code and Codex.

The loop

One model, one writer, two ways to answer.

You answer in the chat, or you edit a rendered document. The MCP server is the only writer of the model: it validates every change against the schema, renders the documents, and reconciles your edits back into the JSON.

The owner answers the agent, which calls the MCP server; the server validates and writes the JSON model, which is rendered as Markdown the owner reads. Owner edits to the Markdown are reconciled back through the server. answers tool calls validate, write render read in the preview edit a file Reconcile: diff, apply or report Owner in VS Code Agent Gemini CLI, Claude Code, Codex MCP server the only writer of spec/ JSON model + schema feature.json Rendered Markdown framing.md, requirements.md … The same loop, top to bottom: Owner, Agent, MCP server, JSON model plus schema, Rendered Markdown, read back by the owner; owner edits are reconciled through the server. answers tool calls validate, write render read in the preview edit a file Reconcile Owner in VS Code Agent Gemini CLI, Claude Code, Codex MCP server the only writer of spec/ JSON model + schema feature.json Rendered Markdown framing.md, requirements.md …
model flow owner edits, taken back by reconcile

Six phases

Each phase adds one kind of object.

A phase is left only when the schema says it is complete, and never while an owner edit is waiting to be reconciled.

  1. framing

    Intent, actors, scope in and out, constraints, open questions.

  2. requirements

    One EARS sentence per behaviour, with facet and priority.

  3. acceptance

    Given/When/Then criteria, at least one per requirement.

  4. anchoring

    The file and symbol that will realise each requirement.

  5. verification

    One declared test per criterion, status from the runner.

  6. done

    Every test passing or justified, no open question left.

Principles

Three rules hold everywhere.

They are why a rendered document can be trusted, and why your edits are never lost.

01

The JSON is the truth.

The documents are a deterministic projection of the model. Nothing exists only in Markdown.

02

The schema governs the lifecycle.

Phases, their order, required fields and coverage rules live in one JSON Schema. The code names no phase.

03

Owner edits are first-class.

Each edit is applied, or reported with its reason and kept as an open question. None is overwritten unread.

Install

One MCP server, three agents.

Run the lines for your agent from your project folder. They register the server and copy the seven skills.

# Gemini CLI
gemini mcp add -s project -e SPEC_LOOP_ROOT="$PWD" spec-loop -- npx -y mcp-spec-loop@0.1.0
mkdir -p .agents/skills && cp -R /path/to/spec-loop/skills/* .agents/skills/

# Claude Code
claude mcp add --scope project spec-loop -- npx -y mcp-spec-loop@0.1.0
mkdir -p .agents/skills && cp -R /path/to/spec-loop/skills/* .agents/skills/ && mkdir -p .claude && ln -s ../.agents/skills .claude/skills

# Codex
codex mcp add spec-loop --env SPEC_LOOP_ROOT="$PWD" -- npx -y mcp-spec-loop@0.1.0
mkdir -p .agents/skills && cp -R /path/to/spec-loop/skills/* .agents/skills/

The npm package is not published yet. Until it is, clone the repository, run npm install, and replace npx -y mcp-spec-loop@0.1.0 with node /path/to/spec-loop/dist/mcp.js.