olshansk/cmd-codex-review-plan

Codex Review Plan <!-- omit in toc -->

Use codex exec as an independent reviewer on the plan currently in scope. Codex sees only the plan (no conversation history), so its critique is a genuine outside perspective — useful right before exiting plan mode and switching to auto execution.

• When to use
• Instructions
• Codex prompt
• Output format
• Notes

When to use

• Right before approving "Yes, and use auto mode" on an ExitPlanMode prompt
• Any time the user says "review plan with codex", "second opinion from codex", or /cmd-codex-review-plan
• After a non-trivial plan has been drafted and the user wants an outside critique before execution

Instructions

1. Locate the plan

Use the most recent plan in conversation context — typically the body of the last ExitPlanMode call, or the latest plan markdown the user is reviewing. If multiple candidates exist, ask the user which one. Do not invent or summarize — pass the plan verbatim.

2. Write the plan to a tempfile

Codex reads from stdin reliably only if the input is a file or a piped heredoc. Use a tempfile to avoid quoting issues:

PLAN_FILE=$(mktemp -t codex-plan.XXXXXX.md)
OUT_FILE=$(mktemp -t codex-review.XXXXXX.md)

Write the plan verbatim into $PLAN_FILE using the Write tool.

3. Run codex in headless review mode

codex exec \
  --sandbox read-only \
  --skip-git-repo-check \
  --color never \
  --output-last-message "$OUT_FILE" \
  - < "$PLAN_FILE"

Pass the prompt from Codex prompt as the initial argument, and the plan via stdin. Concretely:

codex exec \
  --sandbox read-only \
  --skip-git-repo-check \
  --color never \
  --output-last-message "$OUT_FILE" \
  "$(cat <<'PROMPT'
You are reviewing an implementation plan written by another coding agent (Claude).
The plan follows in the <stdin> block.

Your job:
1. Identify GAPS — requirements, edge cases, failure modes, or dependencies the plan misses.
2. Identify RISKS — fragile assumptions, ordering hazards, breaking-change risks, test coverage holes.
3. Identify SIMPLIFICATIONS — anything over-engineered, premature abstraction, or scope that should be deferred.
4. Identify CONCRETE FIXES — for each issue, suggest the smallest change that addresses it.

Constraints:
- Do NOT rewrite the whole plan. Critique it.
- Do NOT execute commands or modify files. This is a read-only review.
- Be specific: cite file paths, phase numbers, or step numbers from the plan.
- If the plan is solid, say so. Do not invent issues.

Output format (markdown):

## Verdict
One sentence: ship-as-is | minor-tweaks | needs-rework

## Gaps
- [bullet per gap, with phase/file reference]

## Risks
- [bullet per risk, with phase/file reference and severity: high/medium/low]

## Simplifications
- [bullet per simplification opportunity]

## Concrete Suggestions
- [numbered list of specific actionable changes to apply to the plan]

## What's Good
- [1-3 bullets on what the plan gets right — keep this honest, not flattery]
PROMPT
)" < "$PLAN_FILE"

Stream codex's progress to the user as it runs (don't background it — the user wants to watch). Capture the final message from $OUT_FILE.

4. Present codex's raw feedback

Show the contents of $OUT_FILE to the user verbatim under a heading:

## Codex review

> Independent review from `codex exec` — no conversation context, plan only.

<contents of $OUT_FILE>

5. Synthesize a revised plan

Read codex's suggestions and decide, item by item, what to apply. Then produce:

1. Revised plan — the original plan with codex's accepted suggestions integrated.
2. Changelog — a table showing each codex suggestion and what you did with it.

Don't blindly accept everything codex says. If a suggestion is wrong, irrelevant, or misunderstands context Claude has and codex doesn't, mark it rejected and explain why.

6. Cleanup

rm -f "$PLAN_FILE" "$OUT_FILE"

Codex prompt

The exact prompt is embedded in step 3. Key requirements when adapting it:

• Tell codex it's reviewing another agent's plan (sets expectations for tone)
• Demand specific references (phase numbers, file paths) — vague critique is useless
• Explicitly forbid command execution (read-only review)
• Require a verdict line so the user can triage at a glance
• Allow codex to say "looks good" — don't force it to manufacture issues

Output format

After codex returns, present the result as three sections in order:

1. Codex's raw review

Quoted verbatim under a ## Codex review heading. Don't paraphrase — the user wants codex's voice, not Claude's summary of codex.

2. Revised plan

Same shape as the original plan (phases, action items, risks, etc.) with accepted changes integrated. Mark new or modified items with a leading marker so they're easy to spot:

| Marker | Meaning | |--------|---------| | 🆕 | New item added based on codex feedback | | ✏️ | Existing item modified based on codex feedback | | ➖ | Item removed based on codex feedback |

3. Changelog

Table with one row per codex suggestion:

| S | Codex Suggestion | Decision | Reason | |---|------------------|----------|--------| | 🟢 | Add rollback step to phase 2 | Applied | Valid — the migration can fail mid-write | | 🟡 | Split phase 1 into two phases | Partial | Kept as one phase, but added explicit checkpoints | | 🔴 | Use a feature flag for the rename | Rejected | Overkill — the function is internal and has 2 callers |

🟢 Applied · 🟡 Partial / modified · 🔴 Rejected · ⚪ Deferred to follow-up

End with a one-line tl;dr of net changes (e.g., "Added 1 phase, modified 2 steps, rejected 1 suggestion.").

Notes

• Codex needs auth — if codex exec errors with auth issues, tell the user to run codex login and stop.
• Read-only sandbox — codex cannot modify files even if it tries. This is intentional.
• --skip-git-repo-check — lets the skill work outside git repos (e.g., scratch dirs).
• --output-last-message — gives a clean final message without progress event noise.
• Don't loop — one codex review per invocation. If the user wants another pass after revisions, they re-run the skill.
• Plan mode caveat — if invoked from plan mode, the only file edits available are via Write/Edit on the tempfiles, which is fine. The Bash call to codex exec is allowed; it's just running an external tool, not modifying repo files.