Claude Code skill: /codex-review — Delegate spec-kitty WP reviews to OpenAI Codex CLI

SKILL.md

name	description	argument-hint
codex-review	Delegate work package review to OpenAI Codex CLI. Use when a WP is in for_review and you want an external AI reviewer. Codex reads the full spec-kitty review prompt, examines the git diff, evaluates against acceptance criteria, and runs the move-task command to approve or request changes.	[WP_ID]

/codex-review — Delegate WP Review to Codex CLI

Sends a spec-kitty work package review to codex exec --full-auto so that OpenAI Codex acts as the reviewer. Codex receives the full review prompt (subtask criteria, review guidance, git context), inspects the implementation diff, and executes the appropriate spec-kitty agent tasks move-task command.

Prerequisites

• codex CLI installed and authenticated (codex --version)
• A work package in for_review lane (or specify WP ID)
• The WP worktree must exist with committed implementation

Workflow

Step 1 — Generate the review prompt

Run the spec-kitty review workflow command. This moves the WP to doing_review and produces a temp file with the full review prompt.

spec-kitty agent workflow review $ARGUMENTS --agent codex

Capture these values from the output:

• REVIEW_PROMPT: The temp file path (e.g., /var/folders/.../spec-kitty-review-WP01.md)
• WORKTREE_PATH: The workspace path (e.g., .worktrees/013-feature-WP01/)
• FEEDBACK_FILE: The feedback temp file path (for rejections)

Step 2 — Feed the prompt to Codex

Pipe the review prompt to codex exec with these flags:

cat "$REVIEW_PROMPT" | codex exec --full-auto \
  -C "$WORKTREE_PATH" \
  --add-dir "$(pwd)" \
  -o "/tmp/codex-review-${WP_ID}-result.md" \
  -

Flag explanation:

• --full-auto — workspace-write sandbox + auto-approval (codex can run git and spec-kitty commands)
• -C "$WORKTREE_PATH" — sets codex working directory to the WP worktree
• --add-dir "$(pwd)" — grants read access to the main repo (for spec-kitty CLI, source docs)
• -o — captures codex's final verdict to a file for your records
• - — reads the prompt from stdin

Step 3 — Verify the outcome

After codex completes, check:

1. Read the output file to see codex's verdict:

   cat /tmp/codex-review-${WP_ID}-result.md

2. Check the WP lane to confirm codex ran the move-task command:

   spec-kitty agent tasks list

3. If codex approved: WP should be in done lane. Proceed to next WP or merge.

4. If codex requested changes: WP should be back in planned lane with review feedback written to the WP file. The implementing agent picks it up on next run.

Complete Example

# 1. Generate review prompt (moves WP to doing_review)
OUTPUT=$(spec-kitty agent workflow review WP01 --agent codex 2>&1)

# 2. Extract paths from output
REVIEW_PROMPT=$(echo "$OUTPUT" | grep -o '/var/folders[^ ]*/spec-kitty-review-WP[0-9]*.md')
WORKTREE=$(echo "$OUTPUT" | grep 'Workspace:' | sed 's/.*Workspace: cd //')
WP_ID="WP01"

# 3. Send to codex
cat "$REVIEW_PROMPT" | codex exec --full-auto \
  -C "$WORKTREE" \
  --add-dir "$(pwd)" \
  -o "/tmp/codex-review-${WP_ID}-result.md" \
  -

# 4. Check result
cat "/tmp/codex-review-${WP_ID}-result.md"
spec-kitty agent tasks list

Why codex exec not codex review

• codex review is designed for code diffs and gives shallow results on markdown/document deliverables
• codex review cannot accept custom review criteria (no prompt argument with --commit)
• codex review has no -o flag for output capture
• codex exec --full-auto can run spec-kitty agent tasks move-task to complete the review cycle
• codex exec accepts the full structured review prompt via stdin

Troubleshooting

Codex says "read-only sandbox": You forgot --full-auto. The default sandbox is read-only.

Codex can't find spec-kitty: Make sure --add-dir "$(pwd)" points to the main repo root where spec-kitty is available on PATH.

Codex doesn't run move-task: The review prompt includes completion commands at the bottom. If codex skips them, check that the full prompt was piped (not truncated). You can also add an explicit instruction before piping:

(echo "IMPORTANT: After reviewing, you MUST execute the appropriate spec-kitty agent tasks move-task command shown at the bottom of this prompt."; echo "---"; cat "$REVIEW_PROMPT") | codex exec --full-auto -C "$WORKTREE" --add-dir "$(pwd)" -o "/tmp/codex-review-${WP_ID}-result.md" -

Review takes too long: Codex MCP servers (Tavily, Notion, Playwright) add ~3s startup overhead. This is normal. For large diffs, expect 30-90s total.

Integration with Sprint Workflow

The intended sprint pattern is:

1. Claude subagent implements a WP via /spec-kitty.implement
2. Subagent commits and moves WP to for_review
3. Codex reviews via /codex-review WP##
4. If approved → next WP or merge
5. If changes requested → Claude subagent addresses feedback and resubmits

This creates a two-AI review loop: Claude implements, Codex reviews. Different model families catch different issues.