Claude vs Codex Debate

Claude vs Codex debate is a planning workflow for issues where two strong models may reasonably choose different approaches.

Use it for architecture decisions, risky refactors, migration strategy, performance tradeoffs, and release-blocker analysis. Do not use it for routine implementation work where a single focused profile is enough.

Mental Model

A debate has three roles:

Claude planner writes one plan.
Codex planner writes a second plan.
Moderator compares both plans and posts a decision.

All three profiles should be comment-only by default. Debate profiles should not move issue state, create issues, push code, or provide input unless you intentionally grant those actions after reviewing the security boundary.

Current Workaround

Current automations dispatch one profile per trigger. There is no native barrier that says “wait until Claude and Codex are both done, then run the moderator.” The workaround is:

add a label such as needs-debate
run two comment-only planner automations for that label
have each planner post a managed comment with a stable sentinel
run a moderator automation only when both sentinel comments are visible

The moderator step is prompt-governed today. It must inspect issue comments and decide whether both planner outputs exist.

Example Profiles

agent:
  profiles:
    planner-claude:
      command: claude --model claude-opus-4-6
      backend: claude
      allowed_actions: [comment]
      soul_file: .itervox/agents/planner-claude/SOUL.md
      instructions_file: .itervox/agents/planner-claude/INSTRUCTIONS.md

    planner-codex:
      command: codex
      backend: codex
      allowed_actions: [comment]
      soul_file: .itervox/agents/planner-codex/SOUL.md
      instructions_file: .itervox/agents/planner-codex/INSTRUCTIONS.md

    debate-moderator:
      command: claude --model claude-opus-4-6
      backend: claude
      allowed_actions: [comment]
      soul_file: .itervox/agents/debate-moderator/SOUL.md
      instructions_file: .itervox/agents/debate-moderator/INSTRUCTIONS.md

The corresponding profile files:

## Workflow
- You are the Claude planning profile. Do not modify code.
- Post exactly one tracker comment starting with the sentinel `<!-- itervox:debate:claude-plan -->`.
- Include the recommended approach, risks, tests, and rollout plan.

## Workflow
- You are the Codex planning profile. Do not modify code.
- Post exactly one tracker comment starting with the sentinel `<!-- itervox:debate:codex-plan -->`.
- Include the recommended approach, risks, tests, and rollout plan.

## Workflow
- You are the debate moderator.
- Read the Claude and Codex debate comments.
- If either sentinel is missing, post a short "debate incomplete" comment and stop.
- If both are present, compare the plans and post one decision comment starting with `<!-- itervox:debate:decision -->`.

Example Automations

automations:
  - id: debate-claude-plan
    enabled: true
    trigger:
      type: issue_entered_state
      state: "Planning"
    profile: planner-claude
    filter:
      labels_any: ["needs-debate"]
    instructions: |
      Write the Claude side of the debate. Do not change code or move state.

  - id: debate-codex-plan
    enabled: true
    trigger:
      type: issue_entered_state
      state: "Planning"
    profile: planner-codex
    filter:
      labels_any: ["needs-debate"]
    instructions: |
      Write the Codex side of the debate. Do not change code or move state.

  - id: debate-moderator
    enabled: true
    trigger:
      type: tracker_comment_added
    profile: debate-moderator
    filter:
      labels_any: ["needs-debate"]
    instructions: |
      Run only if both debate sentinels are present in the issue comments.
      If both are present, synthesize the decision.

Safety Rules

Keep planner and moderator profiles comment-only.
Do not run debate profiles on untrusted issue comments with broad daemon actions enabled.
Avoid debate on secrets, credentials, customer data, or irreversible operations.
Require a human to approve the final decision before implementation starts.
Use short, stable sentinel comments so the moderator can detect participants reliably.

Failure Modes

Failure	What happens today	Production fix
One planner fails	Moderator must notice missing sentinel	Run-group participant status
Both planners post at once	Latest-comment polling can miss one trigger	Native multi-step workflow join barrier
Moderator loops	Prompt must dedupe by decision sentinel	Run-group idempotency key
Planner writes code	Prevent with comment-only action grants and prompt	Enforced planner profile mode
Debate burns tokens	Manual monitoring today	Cost caps and debate deadlines

Production Target

Native debate should be modeled as a multi-step automation workflow:

automations:
  - id: debate-on-planning
    trigger:
      type: issue_entered_state
      state: "Planning"
    filter:
      labels_any: ["needs-debate"]
    parallel_profiles:
      - planner-claude
      - planner-codex
    join_strategy: all
    moderator_profile: debate-moderator

Production multi-step workflows should store participant artifacts, status, deadlines, failure policy, and moderator output separately from tracker comments. Tracker comments can mirror the final decision, but they should not be the only source of truth.

When Not To Debate

Skip debate when:

the issue is small or mechanical
acceptance criteria already prescribe the solution
a reviewer profile can evaluate the work after implementation
the risk is operational rather than technical
the team needs speed more than a tradeoff matrix

Use a single planner profile instead.