codex-code-review

# Codex Code Review Iterative code review via Codex CLI on uncommitted changes. Codex reads the plan and runs `git status -s` / `git diff HEAD` to inspect the change set. Review output stays in `state/<key>.review.txt` — not `docs/3-code-review/`. Promotion to `docs/3-code-review/CR_wa_vx.y.z.md` happens after convergence, not per-turn. State persisted under `.claude/skills/codex-code-review/state/<sanitized-target>.{thread,review.txt,events.ndjson}`. Invoke this skill's own wrapper scripts under `.claude/skills/codex-code-review/scripts/` — they pin the correct `STATE_DIR` and delegate to the shared `codex-plan-review` implementation, so there is no `export` to remember (a forgotten export would silently operate on the plan-review thread for the same target). ## Arguments - `<target>` — auto: start if no thread, resume if exists. Usually a plan path (`docs/1-plans/F_*.plan.md`) or a free-form label for unplanned work. - `reset <target>` — drop state, next call starts fresh. - `show <target>` — display latest review without calling Codex. ## Execution 1. **Parse `$ARGUMENTS`**: extract action (`reset`/`show`/auto) and target. 2. **Auto** — try `start.sh` first (exit code 2 = thread exists -> use `resume.sh`): - **Start**: `bash .claude/skills/codex-code-review/scripts/start.sh --prompt-file .claude/skills/codex-code-review/prompts/start.tpl <target> [extra]` - **Resume**: `bash .claude/skills/codex-code-review/scripts/resume.sh --prompt-file .claude/skills/codex-code-review/prompts/resume.tpl <target> [extra]` 3. **Reset**: `bash .claude/skills/codex-code-review/scripts/reset.sh <target>` 4. **Show**: `bash .claude/skills/codex-code-review/scripts/show.sh <target>` 5. **Parse trailing tag**: - `APPROVED` — propose post-convergence steps. - `REQUEST_CHANGES` — surface review verbatim, engage critically (read actual code at `file:line`, fix legitimate ones, push back on incorrect ones), then resume. - `NEEDS_REWORK` — surface to user before mass-editing. 6. **Resume** after addressing findings for incremental re-review. ## Diff Visibility Codex uses `git status -s` / `git diff HEAD` in read-only sandbox. If those fail, pass diff inline: `DIFF="$(git diff --stat HEAD; echo '---'; git diff HEAD)"` as extra context. ## After Convergence 1. Promote `state/<key>.review.txt` to `docs/3-code-review/CR_wa_vx.y.z.md` using `.claude/skills/TRIP-review/cr-template.md`. 2. Continue with `TRIP-3-release`. ## Notes - **Run Codex calls in a background shell.** Invoke `start.sh` / `resume.sh` via the Bash tool with `run_in_background: true` — never as a foreground/inline command. Codex runs at xhigh effort routinely outlast the foreground command timeout; the background task notifies on completion, then read its output. `reset.sh` / `show.sh` are instant and fine in the foreground. - **Set `CODEX_TIMEOUT=1800`** (30 min) when invoking `start.sh` / `resume.sh` — a generous circuit breaker against hung runs, not a performance target; bump higher for unusually large diffs rather than risk killing a legitimate run. Script default is `0` = no timeout. On expiry the script fails through the normal error path with a "timed out" message in the stderr tail. Requires GNU `timeout`/`gtimeout` (macOS: `brew install coreutils`); warns and runs unbounded if neither is present. - Model/effort/tier defaults live in `codex-plan-review/scripts/_common.sh`, derived from `STATE_DIR`: implementation → gpt-6-luna at high effort on the fast service tier; plan review → gpt-6-astra at xhigh on standard routing; code review → gpt-6-sol at xhigh on the fast tier; codex-ask → gpt-6-astra at xhigh on standard routing. Adjust that one file to your preferred models, or override per run via `CODEX_MODEL` / `CODEX_EFFORT` / `CODEX_TIER` env vars; the scripts echo the effective values. - `--sandbox read-only`. Safe to invoke autonomously. - Thread IDs persisted per-target (no `--last`). Concurrent reviews don't collide. - Separate `STATE_DIR` from `codex-plan-review` — same key is fine. - Extra context -> `{{EXTRA_PROMPT}}`. Keep short. ## Loop Shape ``` turn 1: start.sh -> REQUEST_CHANGES (Critical: A, Major: B C) address A B C turn 2: resume.sh -> REQUEST_CHANGES (A B addressed, Minor: C partial, Suggestion: D) address C, optionally D turn 3: resume.sh -> APPROVED -> promote, continue with TRIP-3-release ```