Agent Discussion Protocol

A file-based workflow for running structured multi-agent debate and collaboration sessions inside any repository. Agents coordinate by reading and writing shared files — no API bridge required.

Two agents. Shared files. Structured turns. One final report.

Why Use This?

Problem	How This Protocol Helps
AI agents give one-sided answers	Debate mode forces two agents to argue competing views and synthesize
Code/design reviews lack rigor	Collaboration mode creates auditable lead + reviewer workflows
Multi-agent sessions are hard to resume	File-based state makes every session resumable from the last checkpoint
Vendor lock-in	Works with any model — Claude, GPT, Codex, Gemini, etc.
API costs add up fast	Uses official editor extensions (Codex, Claude Code, etc.) on your existing subscription — no API keys or per-token billing needed

Showcase Examples

Example	Mode	What it demonstrates
debate_consciousness_origin	Debate	Two agents argue about consciousness origins; synthesize evidence vs. interpretation
collaboration_quantum_gravity_unification_codex_lead	Collaboration	Codex leads, Claude reviews — research brief on unifying GR and QM
collaboration_quantum_gravity_unification_claude_lead	Collaboration	Same topic, Claude leads instead
collaboration_riemann_hypothesis_codex_lead	Collaboration	Codex leads a serious Riemann Hypothesis proof strategy with gap tracking
collaboration_riemann_hypothesis_claude_lead	Collaboration	Same topic, Claude leads instead

Modes

• debate — Two agents argue competing views and end with a synthesis. Best for: research questions, controversial hypotheses, strategy comparisons, philosophical questions.
• collaboration — One lead agent drives the work while one or more collaborators review in ordered turns. Best for: project design, paper review, proposal drafting, spec review, implementation planning.

Designed for official subscription-based tools — Codex, Claude Code (VS Code extension or CLI), and similar — so you avoid per-token API costs.

Quick Start

You only need to edit one file: problem.md.

1. Copy the templates/basic/ folder into your project directory.

2. Edit problem.md in the copied folder. Describe your task, goals, scope, and expected output. Tip: you can ask an AI to draft it using the example problem.md files as references.

3. Launch two agent sessions (e.g., Claude + Codex in VS Code) and give each one the prompt below.

4. If an agent exits while waiting for its turn, paste the same prompt again — it will resume from the last checkpoint.

For advanced configuration (custom participants, rounds, timing), see docs/protocol.md or ask an AI agent to update the scaffold files for you.

Prompt Template

Copy this prompt and fill in the <placeholders>. Use the same prompt for all participants. This is also the prompt you use to resume a stopped discussion — the agent will pick up from the last checkpoint automatically.

Enter <collaboration or debate> mode.

Protocol root: <absolute path to the folder containing problem.md>
All paths below are relative to that folder.

Read:
- AGENTS.md
- problem.md
- .agent_discussion/state/status.json
- .agent_discussion/discussion_rules.md
- .agent_discussion/modes/<collaboration.md or debate.md>
- .agent_discussion/state/current_turn.txt
- .agent_discussion/transcript.md
- if .agent_discussion/state/status.json -> last_completed_turn_file is not null, read that file

You are <Agent 1 or Agent 2>.
Participant id: <agent_1 or agent_2>
Role for this mode: <lead, collaborator, or debater>
Model label: <gpt-5.4, opus-4.6, gemini-3.0, etc.>
Use `max_rounds` from `.agent_discussion/state/status.json` unless the files override it.
If the prompt mode and `.agent_discussion/state/status.json` -> mode disagree during a fresh run, update `status.json` before the first committed turn so the workspace matches the prompt.
If this is a resumed or replacement session, continue from the latest committed checkpoint and ignore incomplete drafts unless the user explicitly told you to recover them.
When it is not your turn, use the wait helper from `.agent_discussion/tools/`. If the host interrupts long-running commands, prefer bounded waits with `-MaxWaitSeconds` or `--max-wait-seconds` set below the host limit, then re-read state and keep waiting. Do not leave the mode just because a wait command stopped or timed out.
If you are the participant that writes the final report, run `node .agent_discussion/tools/export_session_pdfs.mjs --root .` before you leave the mode. Keep the markdown source files after export.
Remain in <collaboration or debate> mode until `.agent_discussion/DONE_ALL` exists or the run reaches its stopping condition.

Placeholders to replace:

Placeholder	What to fill in
<collaboration or debate>	The mode you want to run
<absolute path to the folder containing problem.md>	Full path to your copied template folder
<collaboration.md or debate.md>	Must match the mode above
<Agent 1 or Agent 2>	Which agent this session is
<agent_1 or agent_2>	Participant ID matching the agent
<lead, collaborator, or debater>	Role — see role defaults below
<gpt-5.4, opus-4.6, gemini-3.0, etc.>	The model this agent is running

Filled-in example (collaboration, Claude leads + Codex reviews)

Click to expand

Enter collaboration mode.

Protocol root: /home/user/my-project
All paths below are relative to that folder.

Read:
- AGENTS.md
- problem.md
- .agent_discussion/state/status.json
- .agent_discussion/discussion_rules.md
- .agent_discussion/modes/collaboration.md
- .agent_discussion/state/current_turn.txt
- .agent_discussion/transcript.md
- if .agent_discussion/state/status.json -> last_completed_turn_file is not null, read that file

You are Agent 1.
Participant id: agent_1
Role for this mode: lead
Model label: opus-4.6
Use `max_rounds` from `.agent_discussion/state/status.json` unless the files override it.
If the prompt mode and `.agent_discussion/state/status.json` -> mode disagree during a fresh run, update `status.json` before the first committed turn so the workspace matches the prompt.
If this is a resumed or replacement session, continue from the latest committed checkpoint and ignore incomplete drafts unless the user explicitly told you to recover them.
When it is not your turn, use the wait helper from `.agent_discussion/tools/`. If the host interrupts long-running commands, prefer bounded waits with `-MaxWaitSeconds` or `--max-wait-seconds` set below the host limit, then re-read state and keep waiting. Do not leave the mode just because a wait command stopped or timed out.
If you are the participant that writes the final report, run `node .agent_discussion/tools/export_session_pdfs.mjs --root .` before you leave the mode. Keep the markdown source files after export.
Remain in collaboration mode until `.agent_discussion/DONE_ALL` exists or the run reaches its stopping condition.

Role defaults

Mode	Agent 1	Agent 2+
debate	Peer debater	Peer debater
collaboration	Lead	Collaborator(s)

How It Works

┌─────────────┐     ┌──────────────────────────────────┐     ┌──────────────┐
│   Agent 1   │────▶│  .agent_discussion/ (shared)     │◀────│   Agent 2    │
│  (Claude)   │     │                                  │     │  (GPT/Codex) │
└─────────────┘     │  state/status.json    ← state    │     └──────────────┘
                    │  state/current_turn.txt ← turn   │
                    │  rounds/              ← turns    │
                    │  transcript.md        ← summary  │
                    │  final_report.md      ← output   │
                    └──────────────────────────────────┘

1. Both agents read the same problem.md and shared state files
2. The agent whose turn it is writes to rounds/, updates transcript.md, and hands off
3. The waiting agent polls current_turn.txt until it's their turn
4. After all rounds, one agent writes final_report.md and exports PDFs

Project Structure

agent-discussion-protocol/
├── README.md                        ← you are here
├── templates/basic/                 ← copy this to start a new run
│   ├── problem.md                   ← ✏️ the only file you edit
│   ├── AGENTS.md                    ← workspace context
│   └── .agent_discussion/
│       ├── state/status.json        ← session state machine
│       ├── state/current_turn.txt   ← who goes next
│       ├── modes/debate.md          ← debate rules
│       ├── modes/collaboration.md   ← collaboration rules
│       ├── discussion_rules.md      ← shared behavior contract
│       ├── transcript.md            ← human-readable turn log
│       ├── final_report.md          ← output synthesis
│       ├── rounds/                  ← detailed per-turn files
│       └── tools/                   ← wait helpers & PDF export
├── docs/
│   ├── protocol.md                  ← full operating spec
│   └── examples.md                  ← example quality bar
└── examples/                        ← completed reference runs

FAQ

Q: What AI models does this work with? Any model that can read and write files — Claude, GPT, Codex, Gemini, Llama, etc. The protocol is model-agnostic.

Q: Do the agents need to run at the same time? No. Each agent polls for its turn. You can run them sequentially or in parallel. If one crashes, restart it with the same prompt — it resumes from the last checkpoint.

Q: Can I use more than two agents? Yes, in collaboration mode. Add more participant IDs to status.json → participants. Debate mode defaults to two agents.

Q: How do I stop a run early? Create a file called .agent_discussion/DONE_ALL in the protocol root. Both agents will stop at the next poll.

Q: What if an agent gets stuck waiting? Paste the same prompt into a new session. The shared state files make every run resumable. See the waiting contract for details.

Q: Can I customize the number of rounds? Yes. Edit max_rounds in .agent_discussion/state/status.json before starting, or mention it in your problem.md.

License

MIT