agent-debate

name

agent-debate

description

Run an automated debate with a live Claude, Codex, or Grok peer until consensus — no round cap, no deadlock exit. Two explicit subcommands: `review` has the selected peer critique the current diff while the invoking agent fixes or disputes findings, committing the trail and optionally posting it to the PR; `answer` has both agents independently answer a prompt, cross-check, and return one confirmed answer. The peer runs in a split terminal driven through /kolu. Use when the user types `/agent-debate`, asks Claude/Codex/Grok to review a change, asks two agents to argue until they agree, or wants a consensus answer from two agents.

Agent debate

Debate a selected Claude, Codex, or Grok peer until consensus, with no round cap and no deadlock exit. Require both an explicit mode and an explicit peer: never infer a mutating review from prose, and never silently prefer one agent over the others.

• review — the selected peer reviews the current diff; you (the author) fix or dispute each finding until both sides agree. Commit each author round and optionally post the compact trail to the PR.
• answer — you and the selected peer independently answer a prompt, cross-check, and return one confirmed answer. This mode is read-only and saves a transcript.

The engine — a live peer in a split terminal beside you

Drive the debate from your own turn: spawn the selected peer as a live split terminal beside you and take turns until consensus. There is no Workflow tool and no subagent — you are one debater, the split session is the other. All terminal mechanics belong to the /kolu skill: split provisioning, send→settle→submit, done-signals, large-paste files, re-key recovery, and teardown. Read it first; this skill adds only the debate protocol.

Require a kolu terminal so you can spawn a sibling split. If the current session is not in kolu, say the skill cannot run and stop.

Select and launch the peer

Parse the required --agent <claude|codex|grok> into PEER before doing any work. Reject a missing or unknown value rather than defaulting.

Never pass a reasoning-effort flag. Each peer runs at its own CLI default — the level its vendor ships as right for the model. Pinning one here meant tracking three different flag spellings and every vendor's supported levels, and guessing at a tier from outside the tool that knows best.

Use the selected peer's exact preflight and interactive launch:

PEER	Preflight	Split command
claude	claude auth status	claude --dangerously-skip-permissions
codex	codex login status	codex --yolo --cd "$REPO"
grok	grok models	grok --always-approve --cwd "$REPO"

Run Claude from a split whose cwd is already $REPO; its CLI has no cwd flag. If preflight reports an authentication failure, name the matching login command (claude auth login, codex login, or grok login) and stop. For any other failure — including network/model discovery failure from grok models — surface the exact error and stop. Do not mislabel it as auth trouble or try another agent.

Provision the peer as a split tile parented to your own terminal, never as a detached terminal. Use /kolu's split-with-parent create (lifecycle_create with placement: {kind: "child-of", parentId} first; kolu create --parent <id> only as its documented fallback — both faces REQUIRE a stated placement, so there is no spelling that leaves the peer detached by accident). The unrestricted flag is required: the peer must write its verdict file and ping the author's unix socket, so a sandboxed session cannot run this protocol.

Boot-check the chosen TUI. create returning does not mean the peer is ready. Snapshot the split and confirm the selected TUI is at its input prompt in unrestricted mode (YOLO mode for Codex; bypass-permissions/always-approve for Claude/Grok). A launch may update and fall back to a shell; never dispatch until the expected TUI is visible.

Keep both terminal references restart-safe and unambiguous. Create a per-run label such as agent-debate:<timestamp>-<pid>. On the MCP path, read your author record from the terminals resource. Record its current id and a unique restart-safe recovery key: prefer a non-empty unique intent; otherwise use the exact (agent.sessionId, cwd) pair when both fields exist and identify one terminal. Stop only when no available key identifies exactly one terminal. Create the peer with unique intent <run-label>:<peer> and record its id plus that intent. If send or snapshot reports "no terminal matching", list the resource and re-resolve the author by its recorded recovery key or the peer by exact intent, requiring one match. On the CLI fallback, apply the same one-match rule to stable titles; if either side lacks a unique title, stop rather than guess. Put the author id plus its recovery key in every peer ask.

Keep one warm peer session for the whole debate. Round 1 receives the full ask; later rounds receive lean follow-ups and rely on the session's context.

Make the reverse ping executable. Put this exact protocol in every ask: after writing and validating its output file, the peer calls kolu lifecycle_sendInput on the author terminal with text AGENT-DEBATE <run-label> VERDICT-WRITTEN <round>, waits for that terminal with wait_outputSettled { idleMs: 250, timeoutMs: 10000 }, then calls lifecycle_sendInput again with key: "Enter". If the author id is stale, list terminals, require exactly one match for the recorded author recovery key, and use its new id. This full text→settle→Enter sequence avoids the dropped-submit race; the per-run payload cannot be confused for an ordinary prompt.

Exchange files, not rendered screen text. Write each round's instructions to $REPO/.agent-debate/ask-NNN.md and send only a short pointer to that file. Never paste the diff or a rebuttal. Require the peer to write its structured result to disk, print VERDICT-WRITTEN, then ping the author terminal. Read the file byte-for-byte. If it is missing or malformed, ask the peer to rewrite it; never infer a verdict from the TUI.

Tear down only the split you spawned. Re-resolve its recorded title after a kaval re-key if needed. Never use a pattern kill (pkill -f, pgrep, ps | grep | kill, or any marker/substring match). Report unrelated agent processes by pid and args; never hunt them.

The core loop — symmetric pings to consensus

End each side's turn by pinging the other terminal:

author → send peer the round ask (file + pointer)      → END TURN
peer   → inspect, write verdict, ping author           → end turn
author → read, fix/dispute, write section, commit      → ping peer → END TURN
 … until the peer verdict is approved

Treat the incoming ping as the primary done-signal. The verdict is durable because the peer writes it before pinging. A lost ping can still stall an ended turn, so whenever you wake without a fresh ping, perform one bounded wait --until match:'VERDICT-WRITTEN'/snapshot per /kolu and read the file. If the environment cannot re-invoke you, keep that bounded wait alive instead of ending the turn. The debate ends only on consensus.

Run autonomously like /be-review: make the author-side fix/dispute decisions without asking the human between rounds. If an orchestrator is driving you, escalate a genuinely human decision through its reporting channel; otherwise decide and continue.

Parse the mode

Inspect the first whitespace-delimited token of $ARGUMENTS:

• review → read REVIEW.md and follow it.
• answer → read ANSWER.md and follow it.
• Anything else, including no arguments → ask for the explicit mode and --agent <claude|codex|grok>, then stop.

For either mode, reject a missing --agent. Never add a bare review alias: /agent-debate deliberately does not encode or default its peer.

Read only the mode you're running — they share this engine and nothing else.

Files

Keep all ephemeral state in the gitignored per-worktree .agent-debate/ and clear it at the start of every run:

• review mode: ask-NNN.md, verdict-NNN.json, section-NNN-author.md
• answer mode: answer-author-N.md, answer-peer-N.md, answer-verdict-N.json, candidate-author-N.json, candidate.md, answer-<slug>.md
• both: comment.md

None of the scratch feeds a PR comment except the compact generated comment.md. There are no workflow or headless-agent scripts; the engine is this protocol plus /kolu.

This skill is generated from agents/.apm/skills/agent-debate/; edit the source there and keep generated .claude/ and .agents/ copies identical in the same commit (see .claude/rules/apm-workflow.md).