Ping Pong Review

Ping-pong review: autonomous build ↔ adversarial review with a second agent

Two AI coding agents trade a unit of work back and forth over git until a second, independent agent signs off. One builds, the other reviews. Which model plays which role is up to you — flip it when the stronger builder for a domain is the other agent. The deadlock rule is always builder decides.

| Role | Duties | Commits | |---|---|---| | Builder | Code, tests, PR, reconcile every finding, merge on clean, live-verify | product + reconcile() | | Reviewer | Pull tip, run the gate fresh, write findings file, never product code | only the review file, via review() |

• No human is in the loop between rounds — kick off the other agent either by a

one-time paste, or (preferred, zero-paste) by driving it headless (see Driving the reviewer headless).

• Concurrent sessions: never remove/write a worktree you did not create for

this wave. git worktree list before cleanup. If the primary checkout is on another branch, this wave uses its own worktree — don't steal the primary.

Commit protocol (the baton)

Everything travels as git commits on the feature branch.

1. Reviewer, round N: pull tip → run the gate fresh → write

.claude/scratchpads/--review.md with first line ROUND N VERDICT: clean or ROUND N VERDICT: findings. Commit only that file.

1. Builder: on a review() commit, reconcile every finding → re-verify →

append a "Reconcile round N" note → commit reconcile() (may include fixes).

1. Loop until clean → builder ships (see the domain adapter).

Rules: never product code in a review commit; never trust a prior round's gate numbers — always re-run.

If your CI enforces a ticket key in commit subjects, include it on the baton commits too (e.g. review() round N: [TICKET-123]), or they'll fail the commit-message gate.

Setup (before round 1)

1. Build on a feature branch; open a PR.
2. Brief — .claude/scratchpads/-.md: the claim list (what changed),

review focus, deliberate leftovers (things NOT to flag), and the explicit gate commands for this wave.

1. Queue — .claude/scratchpads/REVIEW-QUEUE.md: branch, PR, brief/review paths,

who builds / who reviews, worktree paths, deadlock rule.

1. Kick off the reviewer — preferred is headless (below). Fallback is a one-time

paste of: the roles, the queue + brief paths, the worktree + push recipe, and the rule "never product code for the reviewer". Some terminals can't copy long pastes — if pasting, also write it to tmp/-paste.txt (keep tmp/ gitignored).

1. Arm the watcher (below); stop it on merge.

Driving the reviewer headless (no paste)

If your reviewer agent has a CLI with a headless/single-shot mode, the builder can launch it directly instead of pasting into a live session — fully autonomous: build → launch reviewer → reconcile → relaunch reviewer → until clean → merge.

> ⚠️ Security warning. Running an agent headless/unattended means running it > without per-action approval prompts (many CLIs gate this behind a flag such as > --permission-mode bypassPermissions, --yes, --dangerously-skip-permissions, > or similar). That agent can then run commands and push to your remote with no > human checkpoint. Only do this on an isolated feature branch, scoped to > review-file-only commits, for code you'd let it touch anyway — and understand > you are accepting that risk. Prefer a sandbox/worktree it can't escape. If in > doubt, use the paste flow instead.

Per reviewer round:

1. Push the branch + brief; make the reviewer a detached worktree (never touch

the primary): git worktree add --detach /tmp/-review- origin/

1. Launch the reviewer CLI headless in the background, pointed at that worktree, with

a prompt that says: read the queue + brief; install deps and run the gate FRESH; verify each claim; write .claude/scratchpads/--review.md with ROUND N VERDICT: clean|findings as line 1; commit ONLY that file; push origin HEAD:; never product code; never merge.

1. On process exit, fetch the branch, read the verdict file, reconcile every finding,

push reconcile(), then relaunch the reviewer for round N+1 (a single-shot CLI run reviews one round). Loop until line 1 reads VERDICT: clean.

Gotchas:

• Don't symlink node_modules into the worktree — some bundlers reject

out-of-root symlinks. Run a real install in the worktree (it also proves the lockfile is in sync).

• The builder never authors the clean verdict; only a reviewer commit carries it.
• A "plain" headless output mode may print only a final summary — check the branch

tip / review file for the real result.

Working trees

Two agents on one checkout will collide. Give them separate working trees.

• Default: reviewer works on a linked/detached worktree and pushes

origin HEAD:; the builder keeps the primary checkout.

• When a GUI tool holds the primary checkout (e.g. a desktop app you keep open

on the ship branch): give the reviewer a throwaway detached worktree under /tmp/-review-, edit only the review file there, then:

git worktree add --detach /tmp/-review- origin/
cd /tmp/-review-
git switch -c review-
git add .claude/scratchpads/--review.md
git commit -m "review() round N: "
git push origin HEAD:

After merge: remove only this wave's worktree; delete the feature branch; don't touch other waves' worktrees.

Watcher

A persistent background watcher on the feature branch, filtering baton subjects, so the builder is notified the moment the reviewer pushes:

last=$(git ls-remote origin  | cut -f1)
while true; do
  sleep 60
  cur=$(git ls-remote origin  2>/dev/null | cut -f1) || continue
  [ -z "$cur" ] && continue
  if [ "$cur" != "$last" ]; then
    git fetch -q origin  2>/dev/null || continue
    subj=$(git log -1 --format="%s" "$cur" 2>/dev/null)
    case "$subj" in
      review\(\)*)    echo "REVIEW ROUND: $subj ($cur)";;
      reconcile\(\)*) echo "RECONCILE: $subj ($cur)";;
      *)                    echo "TIP CHANGE: $subj ($cur)";;
    esac
    last=$cur
  fi
done

Kill it on merge. Stale watchers on deleted branches are pure noise. (If you drive the reviewer headless, the process-exit notification is the primary signal and the watcher is a backup that also catches manual reviewer sessions.)

Reconcile (builder)

• Every finding: fix + lock it, or decline with a written reason.
• Deadlock: builder decides, documents, moves on.
• Re-verify fresh; cite new evidence.
• Do not merge until the first line of a reviewer commit's review file reads

VERDICT: clean (the builder never authors the clean verdict).

Clean → ship

1. Run the domain ship step (below).
2. Merge the PR (CI green preferred).
3. Prune the worktree, delete the branch, stop the watcher, move the queue item to

Shipped.

1. Live-verify for real — drive the affected flow, don't just trust a green build.

Adapters

Only three things change per build type: the unit of work, the verification gate (run fresh every round), and what ship means.

• App / website — Gate: lint + typecheck + tests + production build. Ship: merge

→ deploy → live-verify.

• Data / BI (e.g. Power BI / semantic models) — Gate: validate the project files,

a structural/reference check, and a live query for the headline numbers. Ship: publish to the workspace, refresh, verify live. (A structural validator PASS is not an adversarial clean — only a review() verdict is.)

• SQL / data pipelines — Gate: schema/loader discipline + live query checks +

your regression/eval suite. Ship: deploy + post-deploy scan.

• Docs — Gate: build the artifact + verify every figure against source. Ship: the

final artifact + provenance.

Write the chosen gate commands into the brief so the reviewer runs exactly them.

Post-clean deltas

More product after a clean verdict = a new tip and a round N+1. Never reuse the old clean.

When to use

• Use for money/auth/migration/security-sensitive changes and anything a second

agent should adversarially verify before merge.

• Skip trivial mechanical edits.
• A small wave ≈ one findings round + one reconcile → clean.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Streamline-Analytics
• Source: Streamline-Analytics/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.