Plan Refinement with Codex
plan-refine-codex
Refine a Claude Code plan using OpenAI Codex. Use when you have a plan file and want a second opinion or to improve robustness.
SKILL.md
Full skill instructions
Plan Refinement with Codex
Use OpenAI Codex to review and refine implementation plans, adding robustness and catching edge cases.
Prerequisites
codexCLI installed and authenticated (codex login)- A plan file exists (typically at
~/.claude/plans/<name>.md)
Usage
| Invocation | Behavior |
|---|---|
/plan-refine-codex | Refine the current plan file (if in plan mode) |
/plan-refine-codex /path/to/plan.md | Refine the specified plan file |
How to Refine a Plan
Run codex exec with --full-auto and ask it to read and refine the plan file:
codex exec --full-auto "Please read the file $PLAN_FILE and refine the plan. Make it more robust, handle edge cases, and simplify where possible. Return only the improved plan in markdown format."
Important: Have codex read the file itself rather than piping content via stdin. Stdin piping has reliability issues.
Example
codex exec --full-auto "Please read the file /Users/me/.claude/plans/my-plan.md and refine the plan. Look for edge cases like: error handling, input validation, permission issues. Return only the improved plan in markdown format."
Known Issues & Workarounds
Issue: Model not available
ERROR: The 'o3' model is not supported when using Codex with a ChatGPT account.
Workaround: Don't specify -m o3. Use the default model (gpt-5.2-codex).
Issue: Stdin content not received
When piping content via stdin, codex may not receive it:
# This may fail - codex doesn't see the piped content
cat plan.md | codex exec "Refine this plan..."
Workaround: Ask codex to read the file directly in the prompt.
Issue: Heredoc with embedded bash fails
# This fails due to nested $() and backticks
codex exec "$(cat <<'EOF'
...plan with bash code...
EOF
)"
Workaround: Reference the file path instead of embedding content.
Iterating on Refinement
You can pass the plan to codex multiple times for progressive improvement:
- First pass: Focus on edge cases and error handling
- Second pass: Focus on simplification and clarity
- Final pass: Focus on production-readiness
After each refinement, update your plan file with the improved version.
Related Skills
/roborev-review- Get AI code review on your implementation/roborev-refine- Automated review-fix loop