srid/smriti / .claude/skills/codex-debate
codex-debate
VerifiedRun an automated code-review debate between the codex CLI (reviewer) and a Claude subagent (author) on the current diff, looping until they reach consensus — no round cap, no deadlock exit. Use when the user types `/codex-debate`, or asks to "have codex review this", "run the codex debate", "review this PR with codex", or "argue this with codex until you agree".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.2 KB |
| debate.workflow.js | script | 12.3 KB |
| scripts/codex-review.shexecutable | script | 6.4 KB |
| scripts/codex-verdict.schema.json | config | 1.9 KB |
scripts/codex-review.sh
View on GitHub#!/usr/bin/env bash
#
# codex-review.sh — the canonical, deterministic codex invocation for the
# codex<->claude review debate. Runs the codex CLI as a READ-ONLY reviewer of
# the current working-tree state against a base branch, constrained to
# codex-verdict.schema.json, and writes the JSON verdict to <out-json>.
#
# Usage:
# codex-review.sh <base-branch> <rebuttal-file|-> <out-json>
#
# <base-branch> branch to diff against (e.g. master)
# <rebuttal-file> path to a file holding CLAUDE's previous response (JSON),
# or "-" on the first round (no rebuttal yet)
# <out-json> path the JSON verdict is written to (also echoed to stdout)
#
# Notes:
# * codex runs under `--sandbox read-only`, which enforces read-only at the
# execution boundary (the kernel sandbox blocks file writes and other
# state-mutating syscalls), NOT merely by prompt text. codex reviews
# arbitrary diffs and could be prompt-injected by file contents, so the
# read-only promise must be enforced, not advertised. codex auto-falls-back
# to its bundled bubblewrap when the system one is absent, so this works in
# containers; `--sandbox read-only` permits read-only command execution
# (git diff/status, reading files) but denies writes. `codex exec` is already
# non-interactive (approval policy "never"), so a command the sandbox blocks
# is denied outright rather than escalating to a prompt that would wedge the
# headless loop.
# * Always emits a schema-valid verdict on stdout, even if codex errors — a
# synthesized error verdict (approved:false) so the loop never wedges.
set -uo pipefail
base="${1:?usage: codex-review.sh <base-branch> <rebuttal-file|-> <out-json>}"
rebuttal_file="${2:?missing rebuttal-file (use - for none)}"
out="${3:?missing out-json path}"
here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
schema="$here/codex-verdict.schema.json"
log="$out.log"
# The out path lives under a per-worktree scratch dir (e.g. .codex-debate/);
# make sure it exists before codex tries to write the verdict there.
mkdir -p "$(dirname "$out")"
# Pull CLAUDE's previous response, if any. Built as a plain string and injected
# below via a simple variable reference so any special characters in the JSON
# (backticks, $, ...) stay literal — heredoc expansion results are not re-scanned.
# Never let a stale verdict from a previous run survive: if the current codex
# invocation fails to write one, the empty-check below must catch it and
# synthesize an error verdict (otherwise a leftover /tmp file reads as a fresh
# pass — a false consensus).
rm -f "$out" "$log"
rebuttal=""
if [ "$rebuttal_file" != "-" ]; then
if [ -s "$rebuttal_file" ]; then
rebuttal="$(cat "$rebuttal_file")"
else
# A rebuttal was expected (path given, not "-") but the file is missing or
# empty — the handoff broke. Proceed without it, but make the failure loud
# so codex's responseToRebuttal isn't silently empty.
echo "WARNING: expected rebuttal file '$rebuttal_file' is missing or empty; proceeding with no rebuttal this round." >&2
fi
fi
rebuttal_block=""
if [ -n "$rebuttal" ]; then
rebuttal_block="
CLAUDE responded to your PREVIOUS review as follows. Take it seriously: where a
fix landed in the working tree, verify it and mark that finding resolved; where
CLAUDE disputes a finding, either concede (mark it resolved) or hold firm with
specific reasoning in responseToRebuttal.
CLAUDE's response (JSON):
$rebuttal
"
fi
# Unquoted heredoc: only $base and $rebuttal_block expand. No backticks and no
# other $/$(...) appear in the body, so there is nothing else to interpret.
prompt="$(cat <<EOF
You are CODEX, a rigorous, fair senior code reviewer in an automated review
debate with another AI engineer ("CLAUDE") who authored the changes.
REVIEW SCOPE — the full current state of the working tree against the base
branch '$base', which includes committed AND uncommitted changes. Run these
yourself:
git diff $base (committed + tracked-but-unstaged changes)
git status --short (find untracked/new files)
Then read every new/changed file plus surrounding context and review the change
as a whole. Untracked new files do NOT appear in 'git diff', so you MUST inspect
'git status --short' and read those files explicitly.
IGNORE the debate's own scratch dir '.codex-debate/' if it shows up — it holds
this process's verdict/rebuttal files, not part of the change under review.
THIS IS READ-ONLY. Do NOT modify, create, or delete any files. Do NOT run any
git write command (add/commit/push/stash/checkout) or any other state-mutating
command. You are only inspecting.
Review for correctness bugs, logic errors, silent error-swallowing, unjustified
fallbacks, security issues, and clear simplicity/efficiency problems. Be
specific and concrete; cite file:line. Do NOT invent issues to look busy — if
the change is sound, approve it.
$rebuttal_block
Return a verdict matching the provided JSON schema:
- approved: true ONLY when no blocking or major issues remain (minor/nits may remain).
- findings: reuse stable ids (F1, F2, ...) across rounds for the same issue; set
status=resolved once adequately addressed, else open.
- responseToRebuttal: address CLAUDE's disputes directly (empty on round 1).
EOF
)"
# model_reasoning_effort=xhigh is scoped to the debate here (via -c) rather than
# relying on the user's global ~/.codex/config.toml — review is the one place we
# always want codex thinking at full depth, regardless of their default.
if ! codex exec \
--sandbox read-only \
-c model_reasoning_effort="xhigh" \
--output-schema "$schema" \
-o "$out" \
"$prompt"</dev/null >"$log" 2>&1; then
echo "codex exec exited non-zero (see $log)" >&2
fi
if [ ! -s "$out" ]; then
# codex produced no verdict — synthesize a schema-valid error verdict so the
# debate loop can surface the failure instead of hanging. The reviewerError
# flag is the machine-detectable signal the workflow uses to abort with a
# terminal failure: a broken/unavailable codex is INFRASTRUCTURE failure, not
# substantive disagreement, so it must NOT be routed to Claude (there are no
# findings to act on) and must NOT spin the loop forever.
tail_log="$(tail -c 2000 "$log" 2>/dev/null || true)"
jq -n --arg log "$tail_log" '{
approved: false,
summary: ("codex produced no verdict this round. Tail of log: " + $log),
findings: [],
responseToRebuttal: "",
reviewerError: true
}' >"$out"
fi
cat "$out"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |