O2 Review Loop

o2-loop

Four roles, kept apart on purpose:

The orchestrator does not edit code and does not review code. If it finds itself doing either, it is breaking the loop.

Preconditions

• The plan was discussed with the user and confirmed.
• A reviewer backend is reachable. review.sh picks one (--backend auto, the default): Codex when its CLI is present (codex on PATH or bundled in ChatGPT.app), otherwise a sandboxed claude -p with a loud warning. Pass --backend claude only when the user asks. --backend both runs Codex and Claude on the same commit in parallel and merges their verdicts: request_changes if either says so, findings numbered CX<round>-<n> and CL<round>-<n> (near-duplicates merged and marked with both sources), and every finding goes to both reviewers in the next round so each verifies the other's. Use it when the user asks for a cross-check or when the change is risky enough to pay for two reviews (roughly the cost of a Claude round plus a Codex round, wall time of the slower one). The Claude backend needs macOS sandbox-exec; --unsandboxed overrides only when the user says so. If no backend exists, stop and tell the user.
• The ledger lives outside the repo at ~/.claude/o2-loop/<repo>/<branch-slug>/; the scripts derive it. Nothing from it is ever committed.
• One loop per checkout and branch at a time. Two sessions working on the same repository each use their own git worktree; the loop does not lock anything.

Ledger layout

~/.claude/o2-loop/<repo>/<branch-slug>/
  spec.md                        orchestrator: the confirmed plan the coder implements and the reviewer checks against
  round-N/evidence.md            coder: gates run, results, what was fixed this round
  round-N/coder.log              coder: one line per step, written live
  round-N/commit, backend        review.sh: the WIP commit reviewed and by which backend
  round-N/progress.log           review.sh: one line per reviewer action, written live
  round-N/verdict.json           review.sh: the reviewer's structured verdict
  round-N/coder-response.json    coder: fix / dispute / partial / defer per finding
  round-N/also/<repo name>/      review.sh and that repository's coder: commit, path, diff.patch, delta.patch, evidence.md, coder.log, coder-response.json
  round-N/prompt.md, diff.patch, delta.patch, candidates.md, events.jsonl, reviewer.err   review.sh
  round-N/codex/, round-N/claude/  review.sh (--backend both): each reviewer's own prompt, events, verdict and stderr; round-N/verdict.json is the merge
  report.md                      orchestrator: written when the loop ends

Scripts, all under <skill dir>/scripts/ (this SKILL.md's directory):

• review.sh --round N [--backend auto|codex|claude|both] [--also <checkout> ...]: freezes the tree (and every --also checkout) as wip(o2-loop): round N, runs one reviewer round in disposable worktrees (two reviewers in parallel with both), writes verdict.json. Exit 0 approve, 10 request_changes, 1 failure. --help lists every flag.
• loop-state.py [--cap 5]: reads the ledger and prints ACTION: with the single next step. Run it after every step; do not decide the next step yourself.
• selftest.py: regression cases for the state machine and the verdict merge; run it after editing either script.

Procedure

0. Spec. Write <ledger>/spec.md: what the change does, what it must not do, the files or areas it touches, the tests that should cover it, and any constraints from the discussion. One page at most. For a change that spans repositories (openobserve plus o2-enterprise, say), the spec opens with a Contract section, the part every repository must agree on: function and type signatures, feature gates, wire formats, the shared branch name (paired PRs need the same branch name in both repos). Then one section per repository with its own checkout path. Tell the user the loop is starting and which backend review.sh --help would pick.

1. Spawn the coder. Agent with subagent_type: o2-coder, run_in_background: true. The brief is only: the ledger path, "round 1", and "read spec.md". Agent definitions load at session start, so if the harness answers that o2-coder is not found, spawn general-purpose instead with the body of .claude/agents/o2-coder.md prepended to the same brief; the rules are identical, only the packaging differs. Do not paste the discussion; the spec is the contract. Before spawning, start a Monitor on <ledger>/round-1/coder.log (create it with touch first) so the coder's steps land in the chat:

L=<ledger>/round-N/coder.log; while IFS= read -r line; do echo "$line"; case "$line" in *" question: "*|*" step: finished"*) pkill -f "^tail -n 0 -f $L"; break ;; esac; done < <(tail -n 0 -f "$L")

The watcher ends only on the coder's fixed last line step: finished or on a question: line; a looser pattern such as done matches ordinary step lines ("edits done; running fmt") and ends the watch early. If it does end early, start it again with the same command. The pkill sits before the break on purpose: Monitor runs the command in the user's login shell, and zsh waits for the <(tail ...) process after the loop, so a pkill placed after the loop never runs there and the watch hangs until its timeout; bash does not wait, and the form above works in both. When the coder reports back, post its summary to the user in one short paragraph. If it wrote a question: line, take the question to the user, answer it via SendMessage to the coder, and continue.

1b. Paired repositories. One coder per repository, spawned the same way with its own checkout path in the brief, each writing to its own ledger slot (round-N/evidence.md and coder.log for the primary repository; round-N/also/<repo name>/evidence.md, coder.log, coder-response.json for a paired one, where <repo name> is the checkout directory's name as review.sh derives it). Run them in parallel only when the contract in the spec is settled; when one side depends on an interface the other side has not written yet, run that side first and the dependent side after it reports. Coders never spawn agents themselves: splitting work is the orchestrator's job. Use real sibling checkouts for the paired repositories, not .claude/worktrees/ paths, which other sessions may overwrite. One Monitor per coder.log.

2. Review. Run loop-state.py; it should say review. Start a Monitor on <ledger>/round-N/progress.log (touch it first):

L=<ledger>/round-N/progress.log; while IFS= read -r line; do echo "$line"; case "$line" in *" done: "*|*" error: "*) pkill -f "^tail -n 0 -f $L"; break ;; esac; done < <(tail -n 0 -f "$L")

then run review.sh --round N in the background. The watcher's shape matters: reading through a process substitution lets the loop see every line, the anchored pkill inside the loop ends the tail before the break (zsh would otherwise wait for it forever, see step 1), and a plain tail | while never returns at all. Add --also <checkout> for every paired repository so one reviewer sees all sides and can report contract mismatches (the schema's repo field on each finding says which side it belongs to). Tell the user round N started and which backend. Relay the monitor lines as they come, in the user's language. On exit 1, read progress.log and reviewer.err, fix the cause if it is ours (missing evidence, no changes vs base, auth), rerun once, else stop and report.

3. Relay the verdict before anything else. As soon as review.sh returns, post: backend, verdict, every finding as one line (id, severity, file:line, title, and with both which reviewers reported it), and each prior finding's status. With both, say when the two reviewers disagreed on a prior finding; the merge keeps it open if either did. The user sees what the reviewer said before seeing what the coder does about it.

4. Hand the findings to the coder. Run loop-state.py; it says respond, or cap when the round cap is already reached with a non-approving verdict, in which case go to step 5 before the coder does any more work. SendMessage to the same coder agent: the path of round-N/verdict.json, "round N+1", and, only if the verdict is approve and the remaining findings are low, "defer the lows". When SendMessage is unavailable in the session (the harness reports it disabled), spawn a fresh o2-coder instead with the same brief plus the checkout path and "read spec.md, every earlier round's evidence.md and coder-response.json, then the verdict"; the ledger carries the context, so the fresh coder loses nothing the reviewer saw. A verdict with no findings and no still_open prior finding needs no coder at all: loop-state.py treats it as answered. With paired repositories, message every coder; each answers the findings whose repo is its own and ignores the rest, and loop-state.py merges the responses. Start a Monitor on round-(N+1)/coder.log first. When the coder reports, post its per-finding decisions to the user (id, action, reason).

5. Decide by the state machine. Run loop-state.py and do exactly what ACTION says:

• agreed: go to Ending the loop.
• next: go to step 2 with round N+1.
• cap: write an interim report.md (outcome paused after N rounds with K open items), then AskUserQuestion: continue for up to 3 more rounds, or stop and hand over. Show the open items. On continue, rerun loop-state.py --cap N+3 and go on; on stop, finish with outcome stopped after N rounds with K open items.
• respond, evidence, review: something is missing; do that step.

loop-state.py judges the last round that has a verdict, so a prepared next round (its coder.log or evidence.md) never hides agreed or cap. Agreement, as it computes it: the last verdict is approve, no finding with original severity critical, high, or medium is open, every open low is answered with defer, the coder's open_items is empty, and HEAD equals the reviewed commit with a clean tree. Any edit after an approve invalidates it and needs another round.