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
• The working directory must be a spec-kitty-initialized project (if codex runs outside an initialized repo, it needs spec-kitty init first)
• CODEX_HOME should be set to the absolute path to the .codex/ directory in the spec-kitty-enabled project (e.g., CODEX_HOME=/Users/me/my-project/.codex)

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

Build a combined prompt file with the mandatory instruction prepended, then pipe to codex. Do NOT try to combine -C with a positional prompt argument — they conflict. Use stdin (-) only.

# Build combined prompt with mandatory instruction
printf 'IMPORTANT: After reviewing, you MUST execute the appropriate spec-kitty agent tasks move-task command shown at the bottom of this prompt.\n---\n' > /tmp/codex-review-prompt.md
cat "$REVIEW_PROMPT" >> /tmp/codex-review-prompt.md

# Pipe to codex
cat /tmp/codex-review-prompt.md | 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 (do NOT combine with a positional prompt argument)

Shell quoting pitfall: Do NOT use (echo ...; cat ...) subshell piping — parentheses in the move-task commands inside the review prompt cause zsh parse errors. Use the temp file approach above instead.

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: cd ' | sed 's/.*Workspace: cd //')
WP_ID="WP01"

# 3. Build combined prompt and send to codex
printf 'IMPORTANT: After reviewing, you MUST execute the appropriate spec-kitty agent tasks move-task command shown at the bottom of this prompt.\n---\n' > /tmp/codex-review-prompt.md
cat "$REVIEW_PROMPT" >> /tmp/codex-review-prompt.md

cat /tmp/codex-review-prompt.md | 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 status

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. If codex is running outside an initialized spec-kitty project, run spec-kitty init first or set CODEX_HOME to the absolute path of the .codex/ directory.

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). The mandatory instruction prepended in Step 2 ensures codex knows to execute the command.

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

Auto-commit warnings: Codex runs in a sandbox that may not have git index write access to the main repo. The move-task command will show "Failed to auto-commit: fatal: Unable to create .git/index.lock: Operation not permitted" — this is expected. The lane change is written to the status files but needs a manual git add kitty-specs/ && git commit in the main repo afterward. Always commit status changes from main after codex reviews complete.

Illegal transition for_review → planned: When codex rejects a WP and tries move-task WP## --to planned, it may fail with "Illegal transition: for_review -> planned". Codex typically retries with --force automatically. If it doesn't, the orchestrating agent should run the force-move manually.

Shell parse errors with parentheses: The review prompt contains shell commands with parentheses (e.g., move-task WP01 --to planned --review-feedback-file /path). Do NOT wrap the prompt in a subshell (echo ...; cat ...) — use the temp file approach from Step 2 instead.

Cross-worktree visibility: Codex can only see files in the WP workspace it's reviewing. If a WP references deliverables from other WPs (e.g., WP06 T031 cross-checks), those files won't be visible. Document cross-worktree verification explicitly in deliverables so the reviewer understands the verification method.

CODEX_HOME must be absolute: If using CODEX_HOME to point codex to slash commands, it must be an absolute path to the .codex/ directory (e.g., CODEX_HOME=/Users/me/project/.codex). Relative paths will not work.

Parallel reviews: You can safely run multiple codex reviews in parallel (one per WP) since each operates in its own worktree. Use background processes and check results after all complete. Remember to commit all status changes from main in one batch afterward.

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.