codex-peer-review

# Codex Peer Review

Peer validation system using OpenAI Codex CLI. Validates Claude's designs and code reviews through structured discussion before presenting to user.

**Core principle:** Two AI perspectives catch more issues than one. When they disagree, structured discussion resolves most issues. External research (Perplexity if available, otherwise WebSearch) arbitrates persistent disagreements.

## Reference Files

@discussion-protocol.md
@escalation-criteria.md
@common-mistakes.md

## Modes of Operation

### Mode 1: Auto-Trigger (Validation Only)

**Triggers before Claude presents:**
- Implementation plans or designs
- Code review results
- Architecture recommendations
- Major refactoring proposals

**Behavior:** Validates existing work, does not create from scratch.

### Mode 2: Slash Command (Full Lifecycle)

```
/codex-peer-review              # Review current changes
/codex-peer-review --base main  # Review against specific branch
/codex-peer-review [question]   # Validate answer to broad question
```

**Behavior:** Can both create and validate reviews/designs.

## Workflow

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

    start [label="Claude forms\nopinion/response" shape=ellipse];
    dispatch [label="Dispatch subagent\nwith Claude's position"];
    cmdselect [label="Select command\nbased on type" shape=diamond];
    codexreview [label="codex review\n--base X"];
    codexexec [label="codex exec\n\"focused prompt\""];
    compare [label="Compare findings" shape=diamond];
    critical [label="Security/Architecture/\nBreaking Change?" shape=diamond style=filled fillcolor=lightyellow];
    agree [label="Synthesize &\npresent result"];
    round1 [label="Discussion Round 1:\nState positions + evidence"];
    resolved1 [label="Resolved?" shape=diamond];
    round2 [label="Discussion Round 2:\nDeeper analysis"];
    resolved2 [label="Resolved?" shape=diamond];
    escalate [label="Escalate:\nPerplexity/WebSearch" style=filled fillcolor=lig