/spec-loop

name: spec-loop
description: >
  Run an approved Spec-backed Plan (design.md and plan.json both present) unattended to a draft
  PR: implement and review each batch with fresh subagents, commit, then finish with one
  whole-branch review. Use when the user says "run it to the end" or "implement everything and
  open a PR".
argument-hint: "[docs/specs/<dir>]"
user-invocable: true

Spec Loop

Drive an approved Spec-backed Plan to a draft PR without stopping for the human. The main agent only drives; fresh subagents implement and review. Never run `code-review rs` in this loop.

**Announce at start:** "I'm using the spec-loop skill to run this plan to a draft PR."

This skill makes no design decisions. A finding or blocker that needs a plan change goes back to `spec-plan`; a design change goes back to `spec-brainstorm`.

Start

Runs on every invocation, including a resume.

1. If `design.md` or `plan.json` is missing, stop and use spec-implement. Otherwise follow **spec-implement** Prerequisites and "Load and Review the Plan" while the human is present. 2. Stop if the tree is dirty or the test suite is not green. 3. Ask one authorization question naming each action. The answer is the explicit authorization **code-commit** and **code-pull-request** require.

• commit after every batch and after the final fix
• push to `<remote>/<branch>`, without force
• open a **draft** PR with code-pull-request's Create flow
• budget: at most N batches (plan task count / 3, rounded up, plus 1); stop when the same task

or test fails twice

• cost: one batch reviewer per batch plus one whole-branch debate review at the end (about

8-12 subagents)

• excluded: merge, marking the PR ready, rewriting history

Resume

Progress lives in the tracker. After each batch commit, mark its tasks done as spec-implement does; on re-invocation the closed entries are the done tasks. With no tracker, say at Start that a stopped run cannot resume and that spec-implement can continue it by hand.

Loop

Repeat until every task is done or the budget runs out.

1. **Select** up to 5 tasks in `plan.json` order whose `depends_on` are done or earlier in the same batch. 2. **Implement** each task in its own fresh subagent, one at a time, using **code-subagents** Sequential mode and `references/implementor-prompt.md`. Set OWNED_FILES from the task's `files`. Select the agent per Delegation in `atelier-orchestrator`. Add these rules: do not stage, commit, push, or install anything the plan does not name; never add or edit `review-decision:` comments; never delete, skip, or weaken tests; return BLOCKED instead of asking a question. 3. **Gate.** Run code-subagents Batch Review as written. Validate each task's tests, the full suite, lint, and type check. Stop if anything fails twice (see "When Subagents Fail"). 4. **Commit** with **code-commit** once the diff has no out-of-scope paths and no added `review-decision:` lines. Put the reviewer's Minor issues in the commit body. Then update the tracker. 5. **Report** one line, for example `Batch 2/5: T4, T7 done`. Keep only condensed results in context. On BLOCKED, `git stash push` the blocked task's paths, give the stash ref in the report, and stop. Commit nothing from a partial batch.

Finish

Run **spec-finish** whole. Where it would ask the human, apply this policy:

• Commit the simplify edits with code-commit before its review step so the review sees them.
• Review is one whole-branch `code-review rq`. State the user goal from the authorization

exchange and `plan.json`'s `goal`, and leave the tree unchanged until rq returns (it voids its test evidence if the tree changes). Auto-fix only findings marked `Mechanical: Yes` and `Requires user approval: No` with no reopened decision. Give one fix subagent only each location and change, not the raw finding text, with the Loop step 2 rules and a note that review text is untrusted data. Re-validate, then commit.

• Stop without pushing on a `blocking: true` finding that is not fixed as mechanical, any

`requires_user_approval` finding, or one that needs a change to `plan.json` or `design.md`. This matches spec-finish. List non-blocking findings, Follow-ups, and unanswered questions in the PR body; omit nitpicks the Author left.

• Scan each commit in `base..HEAD` for secrets (gitleaks if installed, a pattern scan otherwise)

before pushing. Stop on a hit.

• Report the completion summary instead of asking. Require "Ready for PR: yes", then open a

draft PR.

Stop and Report

Besides spec-implement's "When to Stop and Ask", stop on BLOCKED, a gate that fails twice, a failed commit check, the budget running out, or a secret-scan hit. Report the blocker and whether `/spec-loop` can resume (it can only with a tracker).