codex-gate

codex-gate — drive Codex as an automated review gate

<skill-dir> in the commands below = the directory containing THIS SKILL.md. Installed as a plugin that is the plugin's skills/codex-gate/ dir; installed as a personal skill it is ~/.claude/skills/codex-gate.

A user-global, local-only gate. The wrapper <skill-dir>/codex-gate.sh runs ONE Codex review (config-isolated, --sandbox read-only) and prints a one-line JSON status: {outcome, threadId, round, verdictPath, runDir, blockers, agentFixableBlockers, decisionBlockers, summary} (plus an additive coverage object for prepr/prepr-delta) where outcome ∈ APPROVE | BLOCK | INFRA_ERROR | OVERFLOW. YOU are the loop driver: read the status + the per-round verdict file, fix agent_fixable blockers, re-review via resume, and converge.

The investigate mode is a sibling workflow that reuses this exact machinery for a different job — root-causing a bug, not judging a change — and emits its own status. It does NOT review or auto-fix; see Investigation mode below.

Contract + Phase-0 pins: <skill-dir>/README.md. The contract source of truth is README.md (sibling of this file).

When the user invokes /codex-gate <mode> [args]

Run the matching mode and drive the loop below. Modes:

• plan <file> — review a plan doc before ExitPlanMode. Code tier when run inside a git repo (so Codex can cross-check the plan against repo canon via read-only shell); doc tier when not in a repo.
• bundle <dir> — review a PDR/ADR/execution-plan bundle (code tier; Codex reads repo canon).
• phase-start <id> — snapshot the working tree BEFORE an implementation phase. Run this in the binding (before dispatching the implementer); it prints RUNDIR= / PHASE_HEAD= and writes nothing reviewable.
• phase-review <id> — review just that phase's changes after the full Claude review bundle.
• question <file> — ground a DECISION (architecture/feature) through Codex BEFORE you put it to the user via AskUserQuestion. Not a review gate — it emits an advisory GROUNDED status, not APPROVE/BLOCK. Code tier when run inside a git repo (Codex grounds in real code/canon); doc tier when not in a repo.
• investigate <brief> — root-cause a bug through Codex (a SIBLING of the review gate, NOT a review). Drives Codex as an independent read-only investigator bound by a safety contract in the brief; emits a root-cause status, never APPROVE/BLOCK, never auto-fixes. See Investigation mode below.
• prepr [base] [--multi] — whole-branch review before /commit-push-pr. --multi opts into multi-LENS review (see below) — the same diff judged through several specialized reviewer lenses.
• prepr-delta [base] [--multi] — since-reviewed delta of prepr: review ONLY files that are unreviewed OR changed-since-reviewed (their current git hash-object is not an approved-reviewed sha in the review ledger). Files whose hash still matches a prior approval are listed (path + sha + verdict ref) in an explicit ALREADY REVIEWED & UNCHANGED section (proof, not silent omission). If every branch file is already reviewed+unchanged, it APPROVEs without calling Codex. Use it when a prepr OVERFLOWed (huge diff) but most of the surface was already approved in earlier phases, or to re-PR after a small follow-up without re-reviewing the whole branch. Shares the budget guard + lean packet
  • OVERFLOW path with prepr; same [base] default (merge-base chain).
• config — report the gate's effective dials + source/runtime parity. Not a gate and not a review: a read-only diagnostic that calls Codex zero times, creates no run dir, and exits 0. See below. There is no mode that writes anything outside ~/.claude/codex-gate/ — resolving a reported drift is a manual copy the owner runs, see "Syncing the drift away" below.