# Debate

> Use when the user wants a structured debate between this agent and one other AI agent running on a Kolu terminal — set the stance and end-state, exchange turns via the kolu skill, and optionally converge on a ratified ledger of agreed facts. With --orchestrate, this agent steps out of the debate and only coordinates N≥2 external agents on N terminals. Triggers on "debate <topic> with the agent on terminal …", "have Codex/opencode debate me", "start a debate", "run an LLM debate", "argue this back and forth with another agent", "orchestrate a debate between terminals …".

- Skill: `srid/debate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add srid/debate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/srid/debate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: srid (https://skillmd.com/u/srid)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/srid/debate

---


# Debate

Run a structured debate between this agent and **one external agent** running on
another Kolu terminal. Each debate is a directory of numbered turn-files.

With **`--orchestrate`** this agent does **not** debate — it only coordinates
**N ≥ 2** external agents on N terminals, shuttling arguments between them. See
[Orchestrate mode](#orchestrate-mode) below; the rest of this section describes
the default two-party mode where this agent is itself a debater.

## Start

1. **Ask the user** (AskUserQuestion tool) two setup questions:
   - **End-state** — converge on a ratified ledger of agreed facts, or open-ended exploration?
   - **Stance** — assigned opposing standpoints + steelman, or neutral collaborative inquiry?
2. Get the **topic** and the external agent's **terminal ID**.
3. Create `debates/<label>/01.md` and state the topic at the top.

## Layout

```
debates/<label>/
  README.md      # plain-language, heavily-formatted front page (GitHub renders this on the folder)
  concepts.svg   # optional hand-authored SVG diagram, referenced by README.md (see Conduct)
  01.md          # opening turn (topic stated at the top)
  02.md          # other agent's turn
  03.md          # ...
  conclusion.md  # agreed ledger — faithful & precise (only when converging)
```

`<label>` names the debate; turns are numbered files in order.

## Turns

- Reach the external agent with the kolu skill's **`kaval-tui send <terminalID> …`**
  (the agent type running there is auto-detected by snapshotting the terminal).
  Any agent CLI qualifies — not just Codex.
- Each turn is the **next numbered file**; never rewrite another participant's file.
- **Hand off explicitly:** after taking a turn, ping the other terminal with
  `kaval-tui send` so it knows to proceed. Do **not** use `pulam-tui` or any
  done-signal polling — the agents prompt each other directly with `kaval-tui send`.
- Keep prompts to the other agent **short and unbiased** — don't leak your own
  argument when asking for theirs.
- Cite grounding sources inline when the topic has an authoritative reference.

## Conduct

- Steelman before rebutting; concede what's genuinely true; forge new insight.
- End per the chosen end-state. When converging, write **two** files:
  - `conclusion.md` — the faithful ledger: every agreed claim, every amendment, and every
    open question, in precise wording. This is the record.
  - `README.md` — a plain-language, scannable **front page** for the debate folder (GitHub
    renders it when someone opens the directory). It introduces the debate — a one-line
    orientation linking the turns and `conclusion.md` — and restates the result for a
    general reader. It changes *presentation only* — never alter, weaken, or drop a
    conclusion or open item from `conclusion.md`. Three standing conventions:
    - **Plain language.** Translate jargon and terms of art into everyday words (gloss or
      footnote any that must stay); short sentences, concrete examples, a practical voice.
      No arcane prose.
    - **Liberal Markdown for glanceability.** Use the full toolkit — a metadata table, an
      at-a-glance summary table, GitHub alerts (`> [!TIP]`/`[!NOTE]`/`[!WARNING]`/
      `[!IMPORTANT]`), bold lead-ins, ordered/unordered lists, blockquotes, horizontal
      rules, and footnotes for citations — so a reader can grasp it at a glance.
    - **Visual explanation with SVG (when it helps).** Where a flow or set of relationships
      is clearer shown than told, hand-author an **SVG diagram**, commit it as a file in the
      debate folder (e.g. `concepts.svg`), and reference it from the README as a markdown
      image (`![…](concepts.svg)`). GitHub strips inline `<svg>` from markdown, so link a
      committed `.svg` file rather than pasting raw SVG into the page. Give it an explicit
      background and high-contrast labels so it reads in both light and dark themes, keep it
      legible at normal width, and make it agree with `conclusion.md` — a diagram adds no new
      claims.
- Debates are not published externally.

## Orchestrate mode

Opt in with **`--orchestrate`**. In this mode **this agent never contributes an
argument** — it is purely a turn-coordinator for **N ≥ 2** external agents, each
on its own terminal. The terminals share this repo's working directory, so each
agent **reads the others' turn-files and writes its own** by path; this agent
only sequences the rounds with the kolu loop (`kaval-tui send` → settle →
`snapshot`) and verifies each turn-file landed. The two setup questions
(end-state, stance) and the whole **Conduct** section still apply.

### Setup

1. Ask the two setup questions (end-state, stance) as usual.
2. Collect the **N terminal IDs** and give each agent a short **identifier**
   (e.g. `foo`, `bar`, or the agent CLI's name). Identifiers must be unique and
   filename-safe.
3. Write `debates/<label>/topic.md` (the shared prompt, stance assignments, and
   any grounding sources) and `debates/<label>/participants.json` mapping each
   identifier to its terminal ID and a human label.

### Layout

```
debates/<label>/
  participants.json   # identifier → { terminal, label }
  topic.md            # shared prompt + stance assignments + grounding sources
  01.foo.md           # round 1, agent "foo"
  01.bar.md           # round 1, agent "bar"
  02.foo.md           # round 2, agent "foo"
  02.bar.md           # round 2, agent "bar"
  ...
  conclusion.md       # agreed ledger (only when converging)
  README.md           # front page (see Conduct)
```

Turn files are **`<NN>.<identifier>.md`** — two-digit round number, then the
agent's identifier. A **round** is complete once all N agents have written their
`<NN>.*` file.

### Round cycle

For each round `k` (`01`, `02`, …):

1. **Prompt each agent.** Round 1: point the agent at `topic.md` and its assigned
   stance, and tell it to write its opening turn to `debates/<label>/01.<id>.md`.
   Round `k>1`: tell the agent to **read the N−1 other agents' round `k−1`
   files** (`debates/<label>/<k−1>.*.md`, excluding its own) so it sees every
   opposing argument, then write its reply to `<k>.<id>.md`. Pass file paths, not
   pasted argument text — the agents read and write the shared directory directly.
2. **Drive and confirm.** `kaval-tui send` the prompt, send `--key Enter`, wait
   for the screen to settle, then `snapshot` to confirm the agent finished and
   **verify `<NN>.<identifier>.md` now exists** on disk (see the kolu skill's
   *Acceptance*). Each agent owns its own file; never write another's.
3. Advance to round `k+1` once all N round-`k` files exist.

- Keep every prompt **short and unbiased** — point agents at each other's files,
  but inject **none of your own** argument. As orchestrator you sequence turns,
  you don't take part.
- Drive the N terminals within a round **independently** (they don't need each
  other's *current*-round turn, only the previous round's), so a round can fan
  out concurrently and only barrier at the round boundary.
- End per the chosen end-state. When converging, you may synthesize
  `conclusion.md` and `README.md` from the recorded turns — that synthesis is
  scribe work (a faithful summary of what the agents agreed), not a new argument.

## Deferred

- A **converging-tree** topology (agents splitting into sub-debates that merge),
  modelled as dotted-path turn-files (`01.01-foo.md`). Orchestrate mode keeps a
  flat round structure; the tree is not yet implemented.