loop

/loop

Goal

Run a mission as a bounded series of attempts: pick one idea, make exactly one change, grade it, keep or discard, and stop at a hard cap, a per-attempt timeout, or two consecutive GATE failures (circuit breaker) — never on trust alone. All mechanical enforcement (state, ledger, cap, breaker) lives in core/infra/loop-run.sh; this skill is the iteration protocol that calls it.

Run it from the root of a harness checkout: the default grader (core/tests/grade.sh) replays the harness's own batteries, so a mission in another project has no grader yet.

Relationship to skills/harness-loop

This skill is the generic protocol: fresh context per iteration, exactly one task per iteration, resumable on-disk state, hard budget. /harness-loop is a SPECIALIZATION of it for one fixed mission — improving this harness's own reviewer prompts under §5's rules (fixed TARGET regex, GATE floor, branch convention). If the mission is "improve the harness itself", follow /harness-loop instead of the generic steps below — its numbered procedure is the maintained regulation for that mission.

Steps

1. Mission intake. From the request, determine: a slug (short, kebab-case), a TARGET file-path regex the loop may edit, a base ref (the mission's starting commit — usually HEAD), an attempt cap (default 5), and a per-attempt timeout in seconds (default 600). Confirm any ambiguous one with the user — a loop whose edit scope isn't pinned down is not this skill's contract.

2. Initialize.

   bash core/infra/loop-run.sh init <slug> --target '<regex>' --base <ref> \
     [--cap N] [--timeout-s N] --mission "<one-line description>"
   

   This creates the SQLite goal row (supervisor-goal.sh, attempts modeled as waves), the JSON state file, and the active-loop flag that arms core/hooks/loop-write-guard.py for the rest of the session.

3. Iterate. Each iteration is a fresh context turn — start a new conversation turn or subagent dispatch per iteration rather than carrying the previous iteration's reasoning forward, so each attempt is judged on its own diff, not on accumulated history — doing exactly one task: a. Pick one improvement idea within the declared TARGET. b. Edit only TARGET files. c. git commit the change. d. Grade it:

   bash core/infra/loop-run.sh attempt <slug> --desc "<=80 char idea summary>"
   

   e. Read the LOOP: line at the end of the output — the only line to act on:

   • LOOP: continue — the same output's ATTEMPT: status=… line says whether to keep this commit or git reset --hard back to the pre-attempt commit; then start the next iteration.
   • LOOP: stop(cap) or LOOP: stop(circuit-breaker) — the loop ended on its own; go to step 5.