codex-peer-review

What this skill does

# Codex Peer Review

Symmetric two-AI peer review using OpenAI Codex CLI. Both AIs review independently, then debate per-issue with terminal states until convergence — not a one-shot validation.

**Core principle:** Asymmetric "validate my answer" loops anchor on the proposer's framing. Symmetric blind passes catch ~2x as many issues because each AI examines the work without priming. The debate phase then resolves conflicts deterministically via per-issue terminal states.

This is the **single source of truth** for the peer review protocol. The agent file is a thin dispatcher that loads this skill.

## Reference Files

@discussion-protocol.md — debate mechanics (round-by-round prompts)
@escalation-criteria.md — when to skip the debate and go to external research
@common-mistakes.md — anti-patterns and recovery

## Modes

| Mode | Command | When |
|------|---------|------|
| **blind-debate** (default) | `/codex-peer-review` | Symmetric blind pass + structured debate. Best signal. |
| **classic** (deprecated) | `/codex-peer-review --mode classic` | Old single-pass validation. Cheap, weaker signal. Will be removed. |

Auto-trigger (proactive validation before presenting plans/designs/reviews) always uses **blind-debate**.

## Codex CLI Compatibility

Tested against `codex-cli 0.136.0`. Hard requirements:

- `codex exec` for ALL machine-readable output (`codex review` exposes only `--base` — no `--json`, `-o`, or `--output-schema` — so it cannot drive parseable workflows)
- `jq` (fail fast if missing — required for session ID extraction and JSONL parsing)
- A configured `peer-review` profile **file** at `~/.codex/peer-review.config.toml`, layered via `--profile peer-review` (see "Codex Profile Setup" below)

**Schema is enforced via prompt template, parsed with `jq`** — not via `--output-schema`. (`codex exec` does expose `--output-schema <FILE>`, but the prompt-template + jq path is version-stable and avoids depending on its behavior.)

## Codex Profile Setup

Model selection lives in per-profile files under `~/.codex/`, not in this plugin. Codex CLI (profile-v2) resolves `--profile <name>` by layering `~/.codex/<name>.config.toml` on top of the base `~/.codex/config.toml`. This keeps CLI flags out of prompts and lets users tune without editing the plugin or touching `config.toml`.

Run this once per machine (the plugin's `init` flow does this automatically if the files are missing):

```bash
cat > ~/.codex/peer-review.config.toml <<'EOF'
model = "gpt-5.4"
model_reasoning_effort = "high"
EOF

cat > ~/.codex/peer-review-summarizer.config.toml <<'EOF'
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
EOF
```

The plugin invokes Codex as `codex exec --profile peer-review ...` — the file is layered automatically. **Never hardcode `-m gpt-5.x-...`** in agent prompts.

`gpt-5.4-mini` is the durable cheap-workhorse choice for the summarizer profile.

> **Legacy note:** Pre-0.12 Codex used `[profiles.peer-review]` tables inside `config.toml`. Those are inert under profile-v2 — remove them by hand if you upgraded from an older plugin version. The plugin never writes to or edits `config.toml`.

## The Workflow

```dot
digraph blind_debate {
    rankdir=TB;
    node [shape=box];

    start [label="User invokes /codex-peer-review\nOR Claude is about to present\na plan/design/review" shape=ellipse];
    blind [label="ROUND 0: Blind pass\nClaude review  ‖  Codex review\n(neither sees the other)"];
    canon [label="Canonicalize issues\nid = sha1(file + normalized claim)\nMerge duplicates\nDrop severity:style"];
    states [label="All issues start in state: proposed"];
    debate [label="ROUND N (N≥1): Per-issue debate\nEach side responds: concede/defend/dismiss\nNew issues allowed (also start as proposed)"];
    transition [label="Transition states based on responses"];
    converged [label="All issues in terminal state?\n(accepted/rejected/merged/escalated/deferred)" shape=diamond];
    cap [label="Round count >= cap?" shape=diamond];
    extend [label="Ask user: extend cap?" shape=diamond];
    synth [label="Verdict synthesis\nCritical / Important / Contested / Dismissed" shape=ellipse];

    start -> blind;
    blind -> canon;
    canon -> states;
    states -> debate;
    debate -> transition;
    transition -> converged;
    converged -> synth [label="yes"];
    converged -> cap [label="no"];
    cap -> debate [label="no"];
    cap -> extend [label="yes"];
    extend -> debate [label="yes"];
    extend -> synth [label="no — escalate remaining"];
}
```

**Default cap:** 3 rounds total (1 blind + 2 debate). The peer review found that 5 (the dg default) is too expensive for serious code review and risks rationalization loops. Allow extension only when new evidence appears in the final round.

## Round 0: Blind Pass

Both AIs review the **same scope** with the **same prompt**, neither seeing the other's work.

### Scope determination

| User input | Scope |
|------------|-------|
| `/codex-peer-review` (no args) | Use `AskUserQuestion` to select: changes vs branch / uncommitted / specific commit |
| `/codex-peer-review --base X` | `git diff X...HEAD` |
| `/codex-peer-review --uncommitted` | Staged + unstaged + untracked |
| `/codex-peer-review --commit SHA` | Single commit |
| `/codex-peer-review <question>` | Question text — no diff, validate the answer |
| Auto-trigger from Claude's plan | Plan text + affected files |

**Never guess the base branch.** Always ask via `AskUserQuestion` if not specified.

### The blind-pass prompt template

Both Claude and Codex receive this exact template (variables filled in):

```
You are performing an independent code review. Another AI is reviewing the same
work in parallel. You will not see their findings until after this pass.

## Scope
{scope_description}

## Files / Diff
{files_or_diff}

## Review lenses (apply BOTH)

1. CRITIC LENS: For each issue you raise, you MUST provide ONE of:
   - A concrete exploit path or attack scenario
   - A failing test case (input + expected vs actual)
   - A specific failure mode (e.g., "concurrent writes to map at handler.go:42 will panic under load")
   Vague concerns ("could be improved", "might be fragile") are REJECTED.

2. DEFENDER LENS: Before raising an issue, check whether:
   - An existing test covers it
   - A codebase invariant or convention makes it impossible
   - It is intentional per a comment, ADR, or commit message
   If yes, do not raise it.

## Output format (strict)

Emit a single fenced code block tagged `findings` containing JSONL — one finding per line:

```findings
{"id":"<sha1(file+claim)>","file":"path:line","severity":"critical|high|medium|low|style","claim":"<one sentence>","evidence":"<exploit/test/failure mode>","category":"security|correctness|performance|maintainability|style"}
{"id":"...","file":"...","severity":"...","claim":"...","evidence":"...","category":"..."}
```

If you find no issues, emit an empty `findings` block.

After the block, write a 2-3 sentence summary of the work's overall quality and your confidence level.
```

### Codex invocation

```bash
codex exec --profile peer-review --sandbox read-only \
  -o /tmp/codex_round0.txt \
  --json 2>&1 | tee /tmp/codex_round0.jsonl <<'EOF'
[blind-pass prompt above]
EOF
```

`-o` writes the final assistant message only — that is what we parse for the `findings` block. The JSONL stream is for progress polling and session ID extraction.

### Issue canonicalization

After both sides emit findings, normalize and merge:

```bash
# Concatenate both findings blocks
jq -s '.' /tmp/claude_findings.json /tmp/codex_findings.json > /tmp/all_findings.json

# Merge by id; if both AIs reported the same id, mark source="both"
jq '
  group_by(.id)
  | map({
      id: .[0].id,
      file: .[0].file,
      severity: .[0].severity,
      claim: .[0].claim,
      evidence: (map(.evidence) | unique | join(" || ")),
      category: .[0].category,
      source: (if length == 2 then "both" else .[0]._source end),
      sta