Structured protocol for AI coding agents to debate technical decisions via shared markdown

agent-debate

AI agents debate your technical decisions — then you make the call.

Two to four agents (Gemini, Codex, Gemini, Gemini) edit a shared markdown file in-place. They strikethrough to disagree, cite file:line as evidence, track disputes in a log, and must converge or escalate. It's adversarial code review, not a chatbot.

What a debate looks like

Here's a real excerpt from a 3-agent debate on adding OpenRouter support (Gemini vs Codex vs Gemini):

~~Why a wrapper: Dependencies are just `curl` + `jq`, both standard
on macOS/Linux. [A1-R1]~~
Wrapper is correct, but `jq` is unnecessary dependency surface for v1.
Evidence: repo currently has no `jq` dependency, while `python3` is already
required by orchestrator (`orchestrate.sh:139,445,492,753`). Minimum viable
should be a Python wrapper using stdlib `json` + `urllib.request`. [A2-R1]

### Gemini accepts Codex's corrections [A1-R2]

**Python wrapper over bash+jq:** Codex is right. Verified: `orchestrate.sh`
already requires `python3` at 4+ callsites. Adding `jq` as a new dependency
when Python stdlib can do the same job is unnecessary. Conceding. [A1-R2]

Agents propose, disagree with evidence, and concede when wrong. Every claim is grounded in actual code. The full debate converged in 1 round with all disputes closed.

Why not just ask one AI?

• One agent has blind spots. A second agent catches what the first missed — wrong assumptions, unnecessary dependencies, missing code paths.
• Evidence, not vibes. The protocol forces agents to cite file:line, paste log output, and verify each other's claims before agreeing.
• Scope creep dies here. Agents must justify every addition. "Easy to add" is not a reason. Unrelated ideas go to a parking lot.
• You decide, they inform. Age