This skill defines the mandatory workflow when the user requests a debate or cross-validation between agents to draft or test a thesis, document, or architecture strategy.
1. Orchestrator Role and Objective
The primary harness (Gemini/agy) acts as the Orchestrator. The goal is to produce a single consolidated text approved unanimously in the file.
- Infinite Loop Limit: The debate is capped at a maximum of 3 rounds. If divergence persists after the 3rd round, the orchestrator ends the debate, creates an
## Unresolved Divergencesection, summarizes both positions, and escalates to a human (Tech Lead/Human Operator). Robots do not make final strategic decisions on deadlocks.
2. Document Structure (Versioning)
To prevent agents from approving moving targets, the consolidated version must be explicitly versioned (v1, v2). The file follows this mandatory structure:
# [Document Title]
## Current Consolidated Version — v[N]
[Work-in-progress text that agents are refining]
Agent Debate Block
[Round X]
[Agent Name] (Session ID: [SESSION_ID_OR_ONE_SHOT])
Date: YYYY-MM-DD Vote (on v[N]): [Approved / Approved with reservations / Rejected] Comment: [Critiques and suggestions]
## 3. State Management: The File is the Canonical Memory
1. **File First:** Because it is not always possible or reliable to capture and resume a CLI session ID (and passing the wrong ID pollutes context), **the Markdown debate file acts as the Canonical Memory (primary state)**.
2. **Token Economy (Scoped Reading):** From Round 2 onwards, the orchestrator should not ask guests to re-read the entire knowledge base. The prompt should be limited to: *"Read the new Version v[N] and the comment block since your last vote. Cast a vote on v[N]."*.
3. **Opportunistic Session ID:** If the orchestrator successfully captures the ID (e.g., Copilot log or interactive Claude), it uses it (`--resume=[ID]`) only as a secondary optimization.
## 4. Dynamics and Non-Negotiable Rules (Confidentiality and Sources)
1. **Strict Fact-Checking:** It is forbidden to cast an "Approved" vote on texts that invent facts or cite nonexistent rules without checking the original source. If the "Consolidated Version" contains unsupported facts, the agent MUST vote "Rejected" and mark it with `[VERIFY]` or `[NO DOCUMENTARY EVIDENCE]`. Any claims about CLI features must reference official vendor documentation.
2. **Data Exfiltration Alert:** External CLI tools (e.g., `copilot CLI`) transmit data outside. The orchestrator MUST obtain explicit authorization from the human operator before transmitting confidential project data (NDAs, PII) to external harnesses; a warning alone is insufficient.
3. **Consensus with Reservations:** The vote `Approved with reservations` ends the iteration loop only if the reservation is cosmetic. The Orchestrator classifies whether a reservation is cosmetic. If challenged, it defaults to "Rejected". If the reservation requires documentary verification, source checking, or warns of a severe tactical risk, the reservation is considered blocking and equals "Rejected", forcing a new version (v[N+1]).
4. **Voter Roster, Deadlines & Missing Votes:** The Orchestrator must freeze the voter roster and define a response deadline before voting begins. All invoked agents in the roster must cast a vote. A missing vote or timeout is treated as "Rejected" to prevent silent bypasses. Immutable snapshots of each round's votes MUST include the exact hash or copy of the text reviewed.
## 5. Integration with External Agent CLIs (Harnesses)
To invoke external agents as validators and preserve context (token economy), the orchestrator must use the optimized commands of each CLI:
### Claude Code (Anthropic)
- **Single-Shot Invocation:** `claude -p "Read file X and vote..."`.
- **Resuming Session (Economy):** Add `--resume <SESSION_ID>` or the session name if renamed (e.g., `claude -p "Vote v2" --resume "debate-architecture"`).
- **External ID:** Claude **does not** accept arbitrary external UUIDs on creation, **but** allows passing the **absolute path of a local transcript** as a session ID (e.g., `claude --resume /path/to/transcript.jsonl`). This is the native way to inject external context into Claude.
### GitHub Copilot CLI (Standalone)
- **Single-Shot Invocation:** `copilot -p "Read file X and vote..." --allow-tool "fs(read)"`.
- **Resuming Session (Economy):** Add `--resume <SESSION_ID>`. To continue the last active session in the folder, use `--continue`.
- **External ID:** Via direct CLI it is not possible to force an ID on the first call, but **via programmatic SDK** (tool construction) Copilot accepts a custom ID: `client.create_session(session_id="project-id")`.
### OpenAI Codex CLI
- **Single-Shot Invocation:** `codex -p "Read file X and vote..."`.
- **Resuming Session (Economy):** Add `--resume <SESSION_ID>` or `--continue` to pick up the last active context from the `.agents/codex` state directory.
- **External ID:** You can resume an ongoing debate by referencing the active thread or session UUID. Ensure the local state directory is centralized if running across different terminal environments.