Run a structured multi-round architecture debate between Claude and Codex to converge on a hard technical decision

SKILL.md

name

description

arch-debate

Run a structured multi-round architecture debate between Claude and Codex to converge on a hard technical decision. Claude writes a position, Codex challenges it, back and forth until AGREED. All rounds saved as markdown files for audit trail and reuse. Use when facing a non-obvious architecture choice with real tradeoffs, when you want a second opinion stress-tested rather than just accepted, or when building a PRD collaboratively. Triggers on "arch debate", "debate the architecture", "get codex to challenge", "architecture decision", "PRD loop".

arch-debate

Structured back-and-forth between Claude and Codex to stress-test an architecture decision. All rounds live in a debate/ subdirectory. Loop runs until one side opens a round with AGREED:.

Worked example

E015 Sprites hosting — 4 rounds, 1 fatal flaw found: .planning/epics/e015-sprites-hosting/debate/

Round 0: Claude proposed shared tmux (simple, one process)
Round 1: Codex rejected — one PartyKit connection = broken identity
Round 2: Claude conceded, proposed per-connection fork + source-verified socket path
Round 3: Codex found bridge zombie risk (retry on socket-gone), otherwise agreed
Round 4: AGREED — wrote final architecture + one required code fix scoped

---

Start a new debate

.claude/skills/arch-debate/scripts/new-debate.sh <path> "<question>"
# e.g.
.claude/skills/arch-debate/scripts/new-debate.sh \
  .planning/epics/e016-foo/debate \
  "Should we use Redis or SQLite for session state?"

Creates:

<path>/
  DEBATE-PROTOCOL.md   ← auto-generated with your question + context slots
  round-0-claude.md    ← stub for your opening position

---

Loop mechanics

Round 0 — write your position (Claude)

Fill in round-0-claude.md:

• State your recommended architecture concisely
• Name the failure modes you already see
• Flag what you're least confident about

Round N (odd) — run Codex

.claude/skills/arch-debate/scripts/codex-round.sh <debate-dir> <round-number>
# e.g.
.claude/skills/arch-debate/scripts/codex-round.sh \
  .planning/epics/e015/debate 1

The script feeds Codex: DEBATE-PROTOCOL.md + all previous rounds + the prompt. Output goes to round-N-codex.md.

If Codex is rate-limited, Claude writes the Codex round as devil's advocate (mark the file with > NOTE: written by Claude playing devil's advocate).

Round N (even) — write your rebuttal (Claude)

Read Codex's response. Update your position in round-N-claude.md:

• Concede points you lost
• Push back with new evidence from the codebase (run rg, sed to verify claims)
• Narrow the disagreement

Convergence

When you're ready to agree — or when Codex opens with AGREED: — write round-N-agreed.md with:

1. The settled architecture (diagram + key decisions)
2. Any required code changes scoped
3. Open questions that are implementation-level (not architecture-level)

Then update the epic brief from the agreed doc.

---

Codex prompt template (used by codex-round.sh)

EFFICIENCY: Use targeted commands, not full-file dumps.

You are in round N of a structured architecture debate.

1. Read <debate-dir>/DEBATE-PROTOCOL.md — rules + full context
2. Read ALL previous rounds in <debate-dir>/ — this is your memory
3. Investigate codebase claims you want to challenge (rg, sed)
4. Write your response to <debate-dir>/round-N-codex.md

Rules:
- Max 500 words
- Challenge the weakest point in the previous round
- Be concrete — name specific failure modes
- Propose alternatives, don't only critique
- Start with AGREED: if you agree, then write the final brief

---

Rules for each round

Rule	Detail
Max 500 words	Stay sharp. Long rounds lose focus.
Challenge ONE thing	Pick the weakest point, go deep on it
Verify with source	Run rg/sed before claiming something about the code
Propose, don't just criticise	Every objection needs an alternative
AGREED: prefix	Opens with this → write final brief instead of rebuttal
4–6 rounds max	If not converged by round 6, you're stuck on values not facts — decide

---

When to use this

✅ Non-obvious tradeoff (at least 2 plausible options with real costs)
✅ Architecture that will be hard to change later
✅ PRD that needs pressure-testing before implementation starts
✅ You want an audit trail of why a decision was made

❌ Trivial decisions ("which variable name")
❌ When you already know the answer and just need someone to agree
❌ When Codex credits are depleted and you're in a hurry

---

File naming convention

debate/
  DEBATE-PROTOCOL.md       ← context + rules (read every round)
  round-0-claude.md
  round-1-codex.md
  round-2-claude.md
  round-3-codex.md
  round-N-agreed.md        ← final settled architecture

Always commit the full debate — it's the decision record.

/scripts/codex-round.sh

#!/usr/bin/env bash
# arch-debate/scripts/codex-round.sh
# Run a Codex round in the debate loop.
# Usage: ./codex-round.sh <debate-dir> <round-number>
#
# Feeds Codex: DEBATE-PROTOCOL.md + all previous rounds + task prompt.
# Output file: <debate-dir>/round-N-codex.md
# Logs to: .codex-logs/

set -euo pipefail
REPO_ROOT="$(git rev-parse --show-toplevel)"
DEBATE_DIR="${1:?Usage: codex-round.sh <debate-dir> <round-number>}"
ROUND="${2:?Provide round number}"
OUT_FILE="$DEBATE_DIR/round-${ROUND}-codex.md"

# Absolute path for codex
ABS_DEBATE="$REPO_ROOT/$DEBATE_DIR"
[[ "$DEBATE_DIR" = /* ]] && ABS_DEBATE="$DEBATE_DIR"

# ── Build the transcript ──────────────────────────────────────────────────────
TRANSCRIPT=""
for f in "$ABS_DEBATE"/round-*.md; do
  [[ -f "$f" ]] || continue
  TRANSCRIPT+="### $(basename $f)\n"
  TRANSCRIPT+="$(cat $f)\n\n---\n\n"
done

# ── Build the Codex prompt ────────────────────────────────────────────────────
PROMPT="DEVNOTE: Files inside .codex-logs/ are run logs — ignore them completely.
EFFICIENCY: Use targeted commands not full-file dumps. Prefer rg -n -C3 or sed -n for reading files.

You are in round $ROUND of a structured architecture debate.

## Your task
1. Read the DEBATE-PROTOCOL (below) — this is your rulebook and full context
2. Read ALL previous rounds (transcript below) — this is your memory
3. Investigate any codebase claims you want to verify (rg, sed — be targeted)
4. Write your round $ROUND response to: $DEBATE_DIR/round-${ROUND}-codex.md

## Rules
- Max 500 words
- Challenge the WEAKEST point in the previous round
- Verify code claims before asserting them
- Propose alternatives, don't only criticise
- Start with AGREED: if you agree → write the final brief instead

---

## DEBATE-PROTOCOL
$(cat "$ABS_DEBATE/DEBATE-PROTOCOL.md")

---

## All previous rounds
$TRANSCRIPT"

# ── Run Codex ─────────────────────────────────────────────────────────────────
echo "▸ Running Codex round $ROUND..."
echo "  Output → $OUT_FILE"
echo "  Log    → .codex-logs/$(date +%F)/"
echo ""

cd "$REPO_ROOT"
codex exec \
  --approval-policy never \
  "$PROMPT" 2>&1 | tee /tmp/arch-debate-codex-round-${ROUND}.log

echo ""
if [[ -f "$OUT_FILE" ]]; then
  echo "✓ Codex wrote round $ROUND:"
  echo ""
  cat "$OUT_FILE"
else
  echo "✗ Codex did not produce $OUT_FILE"
  echo "  Check log: /tmp/arch-debate-codex-round-${ROUND}.log"
  echo ""
  echo "  If Codex is rate-limited, write the round manually (as devil's advocate)"
  echo "  and mark it: '> NOTE: written by Claude playing devil's advocate'"
fi

/scripts/new-debate.sh

#!/usr/bin/env bash
# arch-debate/scripts/new-debate.sh
# Scaffold a new debate directory with protocol and opening stub.
# Usage: ./new-debate.sh <debate-dir> "<question>"

set -euo pipefail

DEBATE_DIR="${1:?Usage: new-debate.sh <debate-dir> '<question>'}"
QUESTION="${2:?Provide a question as second argument}"
mkdir -p "$DEBATE_DIR"

# ── DEBATE-PROTOCOL.md ────────────────────────────────────────────────────────
cat > "$DEBATE_DIR/DEBATE-PROTOCOL.md" << PROTO
# Architecture Debate Protocol

## Question
$QUESTION

## Purpose
Claude and Codex debate this decision in rounds until one side opens with AGREED:.

## Files
\`\`\`
debate/
  DEBATE-PROTOCOL.md     ← this file (read every round)
  round-0-claude.md      ← Claude's opening position
  round-1-codex.md       ← Codex round 1
  round-2-claude.md      ← Claude round 2
  ...
  round-N-agreed.md      ← final settled architecture
\`\`\`

## Rules for every round
1. Read ALL previous rounds before writing (they are your memory)
2. Challenge the weakest point in the previous round
3. Verify codebase claims with rg/sed before asserting them
4. Propose alternatives — don't only criticise
5. Max 500 words per round
6. Open with \`AGREED:\` to converge → write final brief instead of rebuttal

## Codebase context
<!-- Fill in: repo root, key files, existing constraints, what already works -->

## Options under consideration
<!-- Fill in: the candidate architectures being debated -->

## Open questions
<!-- Fill in: things neither side knows yet that affect the decision -->
PROTO

# ── round-0-claude.md stub ────────────────────────────────────────────────────
cat > "$DEBATE_DIR/round-0-claude.md" << STUB
# Round 0 — Claude's opening position

## Recommended approach
<!-- State your architecture recommendation here -->

## Why this wins
<!-- Key reasons — be concrete, not general -->

## Failure modes I already see
<!-- Name the weaknesses in your own proposal -->

## What I'm least confident about
<!-- Flag uncertainty — this is what Codex will probe -->
STUB

echo "✓ Scaffolded: $DEBATE_DIR"
echo ""
echo "Next steps:"
echo "  1. Fill in DEBATE-PROTOCOL.md — codebase context, options, open questions"
echo "  2. Fill in round-0-claude.md — your opening position"
echo "  3. Run: .claude/skills/arch-debate/scripts/codex-round.sh $DEBATE_DIR 1"