You are running the build beat of the spec-driven loop for this repository. Implement exactly ONE work item, on its OWN branch.

Context to load first:

  • tools/spec-loop/AGENTS.md — operational rules (repo map, validation commands, branch + hard-limit rules). The repo-wide /AGENTS.md also applies (commit trailers, placeholder convention, confidentiality).
  • tools/spec-loop/IMPLEMENTATION_PLAN.md — the prioritised work items.
  • The appended Compact repository inventory block from the runner — use it to route to likely specs/source files before opening full files.
  • The appended Open pull-request context block from the runner.
  • The appended Local work-item branches block from the runner. The loop never pushes, so a work item it already built shows up here, not in the PR context above.
  • Only the spec(s) and source files relevant to the chosen work item — do not read the whole tree.

Steps:

  1. Read the appended Compact repository inventory. Use it as a routing aid for selecting likely relevant specs, skills, tools, and validation commands. It is not proof; verify the selected work item against the plan and exact source files before changing anything.
  2. Read the appended Open pull-request context and Local work-item branches. Treat both open PRs and existing local work-item branches as in-flight work. Pick the single highest-priority work item from IMPLEMENTATION_PLAN.md. If a Tooling source block is appended below, read the plan from the control branch as it shows (git show <ref>:tools/spec-loop/IMPLEMENTATION_PLAN.md), not from the working tree, which is on the integration base and need not carry the plan. Pick an item not already substantially covered by an open PR and not already built as a local work-item branch (the loop never pushes, so a built item lives only as a local branch until a human pushes it). One only.
  3. Create its branch off the integration base, then switch to it: git checkout -b <slug> where <slug> is the work item's branch — the bare slug, no spec/ or other prefix (e.g. pairing-self-review). NEVER commit the work to the integration branch. One branch per work item.
  4. Read only the relevant spec file(s) — from the control branch if a Tooling source block is appended, otherwise from the working tree — plus the relevant .claude/skills/ / tools/ / docs/ files from the working tree. Confirm what already exists before writing — do not assume.
  5. Implement the work item completely — no placeholders, no stubs. Skills: follow the skill format (frontmatter name / description / license, SPDX header, placeholder convention, every state change a confirmed proposal) and ship an eval suite under tools/skill-evals/evals/<skill-name>/ exercising each step with fixture cases (per /AGENTS.md § Reusable skills — a skill without a matching eval suite is incomplete). Tools: ship tests.
  6. Run the work item's Validation command(s) from its spec (the backpressure). Fix until they pass.
  7. Specs and IMPLEMENTATION_PLAN.md live on the control branch. If a Tooling source block is appended, they are not on this work branch — do not create or edit them here; instead note any status or Known gap change in the PR body for a later plan/update beat to reconcile. (If no such block is present, the tooling is on this branch: update only that spec's frontmatter/Known-gaps, and never IMPLEMENTATION_PLAN.md.)
  8. git add -A then git commit with an imperative subject and a Generated-by: <agent> (<model>) trailer, where <agent> and <model> are the actual agent and model you are running as (e.g. Claude (Opus 4.8), OpenCode (Big Pickle)) — do not hardcode either. Never add a Co-Authored-By: trailer for an agent.

Then STOP. Do NOT push and do NOT open a PR — git push and gh pr create are the human's step (they are in .claude/settings.json ask). Print the exact commands the human can run:

git push -u origin <slug>
gh pr create --web --base <integration-base> --head <slug> \
  --title "<subject>" --body-file <prepared-body>

Rules:

  • One work item per iteration. Do not bundle.
  • Do not duplicate in-flight work. If the highest-priority plan item is already covered by an open PR or already exists as a local work-item branch, skip it and choose the next uncovered item. Checking local branches, not just open PRs, is what keeps the loop from rebuilding the same item every iteration.
  • If a work item is blocked, note why in its spec's Known gaps and pick the next item instead.
  • Stay inside the sandbox; never edit .claude/settings.json; never add a new network/filesystem allowance.
  • Single sources of truth — no duplicate logic; extend tools/.