codex-review

Codex Review

Call Codex to review an implementation plan and return structured feedback with an approval verdict.

When to Use

Activated once per debate round in the /plan-with-codex command, before Claude revision. The orchestrator calls this skill to get Codex's assessment of the current plan.

Usage

The scripts/ directory is relative to this skill's base directory (shown above as "Base directory for this skill").

bash <base_directory>/scripts/run_codex_review.sh \
  --plan-file <path> \
  --feedback-file <path> \
  --revisions-file <path> \
  --round <N> \
  --codex-model <model> \
  [--session-id <thread_id>] \
  [--log-id <uuid>]

Argument	Required	Default	Description
--plan-file	Yes	--	Absolute path to the implementation plan (plan.json or plan.md) that Codex will review. The script injects this path into the review prompt so Codex can read and analyze the plan's contents.
--feedback-file	Yes	--	Absolute path where the script writes Codex's full feedback text (parsed from the JSON stream). The orchestrator reads this file after the script completes to get the detailed findings. This file is overwritten each round.
--revisions-file	No	--	Absolute path to Claude's revision summary from the previous round, listing which findings were accepted and which were rejected with evidence. Only meaningful when round > 1 AND the file exists with actual content (the script checks -s for non-empty). The script injects this path into Codex's prompt so it can read the revisions before re-reviewing, preventing it from re-raising findings that Claude already refuted with valid evidence. Omit entirely on round 1 or when no revisions file has been written yet -- do not pass /dev/null or an empty file.
--round	No	1	The current debate round number (1-indexed). Controls the review prompt tone: round 1 says "Review this new plan", rounds 2+ say "Claude addressed your feedback, re-review for remaining issues." Also gates whether the revisions file is included in the prompt.
--codex-model	No	gpt-5.3-codex	The OpenAI model ID passed to codex -m. Controls which model performs the review.
--session-id	No	--	Codex thread ID returned as CODEX_SESSION from a previous round. When provided, the script attempts codex exec resume <session_id> to continue the conversation with full prior context. If resume fails, it falls back to a fresh session automatically. Omit on round 1.
--log-id	No	auto-generated UUID	Identifier for the persistent JSONL log file at ~/.closedloop-ai/plan-with-codex/<log-id>.jsonl. The raw Codex JSON stream is appended here each round. Pass the same ID across all rounds of a debate to keep the full conversation history in one file. If omitted, a new UUID is generated.

Interpreting Output

The script prints structured tokens to stdout. Parse these to control the debate loop.

All stdout responses include three tokens: a verdict (or failure indicator), CODEX_SESSION, and LOG_ID. The raw Codex JSON stream is appended to ~/.closedloop-ai/plan-with-codex/<uuid>.jsonl. Pass the LOG_ID back via --log-id on subsequent rounds to keep all rounds in one log file.

Approval

VERDICT:APPROVED
CODEX_SESSION:abc-123-def
LOG_ID:550e8400-e29b-41d4-a716-446655440000

Action: Announce approval. Clean up sidecar files. Stop the debate loop.

Changes Requested

VERDICT:NEEDS_CHANGES
CODEX_SESSION:abc-123-def
LOG_ID:550e8400-e29b-41d4-a716-446655440000

Action: Read the feedback file for full details. Pass to plan-agent for revision.

Codex Failed

CODEX_FAILED:<reason>
CODEX_SESSION:abc-123-def
LOG_ID:550e8400-e29b-41d4-a716-446655440000

Action: Announce the failure reason. Ask the user to retry or abort. Do NOT increment the round counter.

Empty Response

CODEX_EMPTY
CODEX_SESSION:abc-123-def
LOG_ID:550e8400-e29b-41d4-a716-446655440000

Action: Announce empty response. Ask the user to retry or abort. Do NOT increment the round counter.

How It Works

1. Builds a review prompt asking Codex to analyze the plan for technical soundness, missing steps, architectural issues, security/performance risks, and unclear descriptions
2. If --session-id is provided, attempts codex exec resume for context continuity; falls back to a fresh session if resume fails
3. Parses the Codex JSON stream for thread.started (thread ID) and item.completed/agent_message (feedback text)
4. If session resume succeeds but no new thread.started event appears, the input session ID is preserved and re-emitted (prevents losing session continuity)
5. Writes full feedback text to --feedback-file; emits only machine-parseable tokens to stdout