codex-plan-review

Codex Plan Review

Send a finalized plan/spec/design/ADR to OpenAI Codex (gpt-6-sol, medium effort, read-only sandbox) for adversarial review, with a blind Opus reviewer running the same prompt in parallel for round 1. The script handles mechanics; you handle judgment. Script path (resolve via this skill's base directory): scripts/codex-review.mjs, run with node.

The one non-negotiable prompt rule: the reviewer must never see your self-assessment. The script builds prompts from the file path only — never paste plan content, your confidence, or "tests pass" claims into any codex invocation. (Research: implementer framing degrades Codex review thoroughness 3–4×.)

Flow

1. Announce: "Running Codex plan review (Sol, medium effort) plus a blind Opus reviewer (medium) — round 1." gpt-6-sol needs Codex CLI 0.158+ on a ChatGPT login (older clients do not list it); if a round returns verdict:"error" and its errorDetail says the model is unavailable, close that chain (note --chain <id> --unique 0 --outcome aborted --comment "model unavailable"; an aborted chain does not block a new one), then rerun with --model <available model> and say which. If codex is missing or not logged in (codex login status), say so, skip, and continue without blocking the plan.
2. Preflight: the artifact must be a file. Write conversation-only plans to their canonical path first (docs/superpowers/specs/…, the repo's own plans directory, or scratchpad for throwaways).
3. Round 1: node <skill-dir>/scripts/codex-review.mjs review <file> --auto (use --force only when the user explicitly asked for a re-run). If it refuses with "chain already exists", tell the user this artifact version was already reviewed and stop unless they ask to force. In the same message, start the blind Claude reviewer (see "Blind Claude reviewer" below). Launch the Codex call with run_in_background so both run at once.
4. Merge round 1. Wait for both reviewers. Dedupe their findings by root cause, verify each against HEAD (below), and walk the union. The round-1 verdict is REVISE if either reviewer has a P1/P2 that survives verification. On REVISE: walk findings one at a time. For accepted findings, amend the plan file. Dismissals require a stated reason in your reply — never silent. Then verify fixes: … review <file> --resume <sessionId> --chain <chainId>. Max 3 review rounds total — the script now refuses a 4th before spending any paid call. Plans do reach APPROVED: 12 of 63 review chains in the first 20 days, 9 of them at round 3 (first on 2026-07-16). If still REVISE after folding round-3 findings in, proceed to the audit anyway (see step 5) rather than stopping — the audit is most valuable exactly here, after three rounds of findings have been folded in. Only skip it if the user stops before folding the findings in; then log the note as cap-revise.
5. Run the final audit — after either an APPROVED round or a round-3 REVISE whose findings have been folded in: … audit <file> --chain <chainId> (fresh Codex session, holistic scope; the script refuses a second audit on the same chain before spending any paid call). AUDIT: PASS → done. AUDIT: CONCERNS → surface findings verbatim and block: the plan is not review-complete until the user dispositions each concern. Never re-run the audit; if the user amends in response, the outcome class is audit-concerns-user-approved (user-approved, audit-unverified); if the user dismisses the concerns with reasons instead, it is audit-concerns-dismissed.