Skip to content

srid/smriti / .claude/skills/codex-debate

codex-debate

Verified

Run 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".

FileKindSize
SKILL.mdskill md10.2 KB
debate.workflow.jsscript12.3 KB
scripts/codex-review.shexecutablescript6.4 KB
scripts/codex-verdict.schema.jsonconfig1.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"
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall