A structured debate protocol for AI coding agents. Two agents independently diagnose a problem, critique each other's work, and iterate toward consensus — producing better solutions than either agent alone.
The included implementation uses Claude Code and Codex CLI as the two agents, but the protocol is framework-agnostic and can be adapted to any combination of AI coding assistants.
A single AI agent can miss things. Two agents reviewing each other's work catch more bugs, surface edge cases, and build confidence in the final fix — the same way human code review works. The structured protocol ensures agents engage critically rather than rubber-stamping each other's proposals.
- Independent Diagnosis — Both agents independently investigate the problem, identify root causes, and propose fixes.
- Cross-Review — Each agent critically reviews the other's work, identifying agreements, disagreements, and missed issues.
- Iterative Revision — Agents revise their proposals based on critique, defending or updating their positions with evidence.
- Consensus or Escalation — The loop continues until both agents agree (consensus) or max rounds are reached (you decide).
- Implementation — The agreed-upon fix is implemented automatically.
All agent outputs are saved to a .debate/ workspace for full auditability.
The debate follows a structured loop with clear prompt templates for each phase:
| Phase | What Happens |
|---|---|
| Diagnose | Both agents independently read code and propose a root cause + fix |
| Review | Each agent critiques the other's proposal |
| Check | Facilitator checks if disagreements remain |
| Revise | Agents update proposals based on critique (or defend their position) |
| Loop | Repeat review → check → revise until consensus or max rounds |
| Implement | Consensus fix is applied; unresolved debates escalate to you |
The orchestrator acts purely as a facilitator — it passes outputs between agents and checks for consensus without injecting its own technical opinions.
See debate.md for the complete protocol specification, including prompt templates, session management, and execution rules.
The included debate.md is a ready-to-use implementation for Claude Code with Codex CLI as the second agent.
- Claude Code installed and configured
- Codex CLI installed and configured
Copy debate.md into your project's Claude Code commands directory:
mkdir -p .claude/commands
cp debate.md .claude/commands/debate.mdFrom within Claude Code, run:
/debate <problem description>
Options:
--rounds Nor-r N— Set the maximum number of debate rounds (default: 5)
Examples:
/debate The config cache proxy returns stale data after a commit
/debate --rounds 3 Users report 502 errors when accessing the API
/debate https://github.com/your-org/your-repo/issues/42
GitHub issue URLs are automatically fetched and expanded.
Each debate session creates a workspace at .debate/<session-id>/ containing:
.debate/<session-id>/
├── problem.md # Problem statement
├── proposals/ # Each agent's diagnosis and fix per round
├── reviews/ # Cross-reviews between agents
├── raw/ # Raw agent output for session management
├── arbiter/ # Disagreement evaluations and final verdict
└── implementation-log.md # What was changed (if consensus reached)
The protocol in debate.md is a structured prompt — the core ideas work with any two AI coding agents that can:
- Read code and produce structured analysis
- Accept prior context (another agent's output) as input
- Be resumed or given conversation history across rounds
To adapt it, replace the Claude Code Task tool calls and Codex CLI commands with equivalent invocations for your preferred agents. The prompt templates (Diagnose, Review, Revise) and the facilitator logic (disagreement checking, consensus detection) are agent-agnostic.
MIT