Codex Review Checkpoint Skill

Codex Review Checkpoint

Code review checkpoint that runs codex review on the current worktree.

Note: The gate-runner script runs this automatically for issues with gate:codex-review label. This skill documents the process for manual use.

Quick Start

# Review uncommitted changes
codex review --uncommitted --title "My Review"

# Review branch changes against main
codex review --base main --title "Feature Review"

# Review a specific commit
codex review --commit abc123

What This Skill Does

Determines what to review (uncommitted changes vs branch diff)
Runs codex review (non-interactive, exits on completion)
Parses results into structured format
Writes result to checkpoint file

Workflow

Step 1: Determine Review Scope

# Check for uncommitted changes
git status --porcelain

# Check for branch diff
git diff --quiet main...HEAD && echo "No branch changes" || echo "Has branch changes"

Step 2: Run Codex Review

# For uncommitted changes
codex review --uncommitted --title "Checkpoint Review"

# For branch diff against main
codex review --base main --title "Checkpoint Review"

Codex review:

Runs non-interactively (no terminal interaction needed)
Outputs structured findings with severity levels (P1, P2, P3)
Exits with appropriate status

Step 3: Parse and Write Result

After reviewing, create a structured result:

{
  "checkpoint": "codex-review",
  "timestamp": "2026-01-19T12:00:00Z",
  "passed": true,
  "issues": [],
  "summary": "No critical issues found"
}

Result Fields:

passed: true if no P1/P2 issues found
issues: array of {severity, message, file?, line?}
summary: brief human-readable summary

Step 4: Write Checkpoint File

mkdir -p .checkpoints
cat > .checkpoints/codex-review.json << 'EOF'
{
  "checkpoint": "codex-review",
  "timestamp": "...",
  "passed": true,
  "issues": [],
  "summary": "..."
}
EOF

Decision Criteria

Pass if:

No P1 or P2 issues found
No security vulnerabilities detected
No obvious bugs or logic errors

Fail if:

P1/P2 issues found
Security issues found
Critical bugs detected

Example Output

$ codex review --uncommitted --title "Feature Review"
OpenAI Codex v0.87.0 (research preview)
--------
workdir: /home/user/project
model: gpt-5.2
...

[P2] Guard against missing script before execution — path/to/file.sh:45
  Description of the issue...

[P3] Consider adding error handling — path/to/other.ts:120
  Suggestion details...

Automated Usage

The gate-runner.sh script runs codex review automatically:

./plugins/conductor/scripts/gate-runner.sh --issue ISSUE-ID --worktree /path/to/worktree

This:

Checks issue labels for gate:codex-review
Runs codex review directly (no terminal spawn needed)
Writes checkpoint to .checkpoints/codex-review.json
Returns pass/fail status

Agent Skills: Codex Review Checkpoint

Install this agent skill to your local

Skill Files