| name | codex-plan-review |
| description | Review/debate plans before implementation between Claude Code and Codex CLI. Can run in plan mode — debates the plan and edits the plan file to fix accepted issues. |
Codex Plan Review
Purpose
Adversarially review a plan before implementation to maximize its chance of achieving the stated target. Validate achievability, catch technology/capability hallucinations (steps that look like they solve the problem but don't), fix logic/design flaws, bad practices, and pattern violations, and fill missing steps. Propose additions ONLY when required to reach the target — no over-engineering, no gold-plating.
When to Use
After creating a plan, before implementing code.
Prerequisites
- A Markdown plan file (e.g.
plan.md) with headings.
Runner
RUNNER="{{RUNNER_PATH}}"
SKILLS_DIR="{{SKILLS_DIR}}"
json_esc() { printf '%s' "$1" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>process.stdout.write(JSON.stringify(d)))'; }
Critical Rules (DO NOT skip)
- Stdin:
printf '%s' "$PROMPT" | node "$RUNNER" ... -- NEVER echo. JSON via heredoc.
- Validate:
init output must start with CODEX_SESSION:. start/resume must return valid JSON. CODEX_NOT_FOUND->tell user install codex.
status === "completed" means Codex's turn is done -- NOT that the debate is over. MUST check Loop Decision table.- Loop: Do NOT exit unless APPROVE or stalemate. No round cap.
- Errors:
failed->retry once (re-poll 15s). timeout->report partial, suggest lower effort. stalled+recoverable->stop->recovery resume->poll; not recoverable->report partial. Cleanup sequencing: finalize+stop ONLY after recovery resolves.
- Cleanup: ALWAYS run
finalize + stop, even on failure/timeout.
- Runner manages all session state -- NEVER read/write session files manually.
- For detailed error flows ->
Read references/protocol.md
Workflow
1. Collect Inputs
Plan-path detection: ls plan.md PLAN.md, find ./docs -maxdepth 3 -name "*plan*.md".
Auto-pick if 1; ask if multiple/none. Announce defaults, block only if plan not found.
Inputs: plan path (abs .md), user request, session context, acceptance criteria, effort (default high).
2. Pre-flight
Read plan -> verify .md + has headings. Derive acceptance criteria from "Goals"/"Outcomes" if not provided.
3. Init + Render + Start
INIT_OUTPUT=$(node "$RUNNER" init --skill-name codex-plan-review --working-dir "$PWD")
SESSION_DIR=${INIT_OUTPUT#CODEX_SESSION:}
Render template=round1, placeholders: PLAN_PATH, USER_REQUEST, SESSION_CONTEXT, ACCEPTANCE_CRITERIA.
Start: printf '%s' "$PROMPT" | node "$RUNNER" start "$SESSION_DIR" --effort "$EFFORT"
4. Poll -> Check Verdict -> Apply/Rebut -> Resume Loop
Poll: node "$RUNNER" poll "$SESSION_DIR". Report specific activities.
Parse review.blocks[] (id, title, severity, category, problem, suggested_fix). Verdict in review.verdict.status.
Check stalemate FIRST, then verdict (-> references/protocol.md § Debate Loop Protocol):
| # | Condition | Action |
|---|
| 1 | convergence.stalemate === true | EXIT -> step 5 (stalemate). Do NOT render rebuttal. |
| 2 | verdict === "APPROVE" | EXIT -> step 5 |
| 3 | verdict === "REVISE" or open issues | CONTINUE -> sub-steps below |
If CONTINUE — all 4 sub-steps are MANDATORY, even if you fix every issue:
- Categorize each
review.blocks[] issue: ACCEPT (valid) or DISPUTE (invalid with reasoning).
- Fix accepted issues -> edit plan file, save before resume (Codex re-reads). Invalid -> rebut with reasoning.
- ALWAYS render rebuttal — template=
rebuttal. Placeholders: PLAN_PATH, SESSION_CONTEXT, FIXED_ITEMS, DISPUTED_ITEMS. If all issues fixed, DISPUTED_ITEMS = "None — all issues addressed". Rebuttal is NEVER skipped.
- ALWAYS resume —
printf '%s' "$PROMPT" | node "$RUNNER" resume "$SESSION_DIR" --effort "$EFFORT". Back to Poll. Codex MUST re-verify fixes and may find new issues.
5. Completion + Output
APPROVE -> done. Stalemate -> present deadlocked issues, ask user.
Report: Rounds, Verdict, Issues Found/Fixed/Disputed, edits made, risks, next steps.
6. Finalize + Cleanup
finalize + stop. Always run. (-> references/protocol.md for error handling)
Flavor Text Triggers
SKILL_START, POLL_WAITING, CODEX_RETURNED, APPLY_FIX, SEND_REBUTTAL, LATE_ROUND, APPROVE_VICTORY, STALEMATE_DRAW, FINAL_SUMMARY
Rules
- Plan mode active -> stay in plan mode. Debate takes priority over plan mode behavior.
- Do not implement code. Do not claim consensus without VERDICT: APPROVE.
- Each accepted issue -> concrete plan edit.
