# Plan Review

> Get Codex's review of an implementation plan before the user starts building — trigger when they want Codex (or a named GPT model like gpt-5.6) to review, critique, or pressure-test a plan. Applies to any plan-shaped artifact — a plan file, plan-mode plan, a migration/rearchitecture/integration/checkout write-up, or a doc describing how they intend to do something (pasted, at a repo path, or just described). Fire on any second-opinion phrasing — "poke holes in it", "sanity-check my plan", "run this past Codex", "get Codex's take", "flag the biggest risks", "look this over before I start", "did I miss edge cases, testing, or a rollback path?". The point is catching gaps, risks, missing steps, and better alternatives ahead of implementation. Do NOT use for reviewing already-written code or diffs (that's diff-review), mapping an existing codebase's architecture (codebase-analysis), or web/research questions.

- Skill: `robbyt/plan-review-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add robbyt/plan-review-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/robbyt/plan-review-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: robbyt (https://skillmd.com/u/robbyt)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/robbyt/plan-review-3

---


# Plan Review via Codex

Use Codex to critique implementation plans for gaps, risks, and better alternatives. Codex consults; Claude writes.

## Transport

**Always use the MCP tool.** The plugin runs `codex mcp-server` on stdio via `.mcp.json`. Tool name: `mcp__plugin_codex_cli__codex`. If the example below errors with an unknown-tool error, run `/mcp` and substitute the actual prefix (e.g., `mcp__codex_cli__codex`).

## Model

**Pin `model: "gpt-5.6-sol"` with `config: { "model_reasoning_effort": "medium" }`** on the opening call. Plan review benefits from flagship reasoning — don't downgrade to `gpt-5.6-luna` here. Set both on the first `codex` call only; `codex-reply` inherits them. Honor an explicit user-named model if given. See `../references/patterns.md` → Models and Reasoning effort.

## Flow

Codex reads files from the project root. For plans living outside the repo (e.g., `~/.claude/plans/...`), **read them with Claude's `Read` tool first and embed the content in the prompt** — Codex can't see paths outside its `cwd`.

**Give Codex enough context to critique against reality, not assumptions.** A plan reviewed blind gets flagged for things you've already handled. State the plan's goal, the hard constraints it must respect (tech stack, deadlines, backward-compat, what's already decided), and what's deliberately out of scope. The critique is only as good as the context you prime it with.

```
mcp__plugin_codex_cli__codex({
  "prompt": "Review this implementation plan:\n\n---\n[PLAN CONTENT HERE]\n---\n\nConsider:\n1. Gaps or missing steps?\n2. Risks not addressed?\n3. Is the approach optimal? What alternatives should we consider?",
  "sandbox": "read-only",
  "model": "gpt-5.6-sol",
  "config": { "model_reasoning_effort": "medium" }
})
```

If the plan lives inside the repo, you can just reference the path:

```
mcp__plugin_codex_cli__codex({
  "prompt": "Review the implementation plan at docs/plans/auth-rewrite.md. Flag gaps, risks, and better alternatives.",
  "sandbox": "read-only",
  "model": "gpt-5.6-sol",
  "config": { "model_reasoning_effort": "medium" }
})
```

## With source context

Let Codex cross-check the plan against the actual code:

```
mcp__plugin_codex_cli__codex({
  "prompt": "Review this plan:\n\n[PLAN CONTENT]\n\nRead these source files for context before critiquing:\n- src/auth/login.ts\n- src/middleware/session.ts\n\nEvaluate whether the plan accounts for the real code structure.",
  "sandbox": "read-only",
  "model": "gpt-5.6-sol",
  "config": { "model_reasoning_effort": "medium" }
})
```

## Focused reviews

**Risk assessment:**
```
mcp__plugin_codex_cli__codex({
  "prompt": "Risk review of this plan:\n\n[PLAN CONTENT]\n\nEvaluate:\n- Breaking changes\n- Data loss potential\n- Rollback complexity\n- Dependencies that could fail",
  "sandbox": "read-only",
  "model": "gpt-5.6-sol",
  "config": { "model_reasoning_effort": "medium" }
})
```

**Completeness check:**
```
mcp__plugin_codex_cli__codex({
  "prompt": "Completeness review of this plan:\n\n[PLAN CONTENT]\n\nEvaluate:\n- Edge cases covered?\n- Testing addressed?\n- Missing steps?",
  "sandbox": "read-only",
  "model": "gpt-5.6-sol",
  "config": { "model_reasoning_effort": "medium" }
})
```

## Iterative workflow (prefer `codex-reply`)

When you're still iterating on the same plan, **continue the existing thread** rather than starting a new `codex` call. Codex keeps the plan and its prior critique in context; starting fresh discards that reasoning and forces re-reading.

Typical loop: initial critique → Claude revises the plan → `codex-reply` with the revised sections asking "does this address your concern?" → Codex confirms or pushes back → repeat.

**Cap at 3–4 rounds total.** Plan review should converge fast; if you're still going at round 5, stop and surface the open questions to the user rather than letting the dialog spiral.

**`threadId` is an MCP argument — pass it as the `threadId` field of `codex-reply`, not in the `prompt` text.** See `../references/mcp-schema.md` for wrong-vs-right examples.

**Example — three rounds on the same plan:**

```
# Round 1 — initial critique (opening call pins model + effort)
mcp__plugin_codex_cli__codex({
  "prompt": "Review this plan:\n\n[PLAN CONTENT]\n\nFlag gaps, risks, and better alternatives.",
  "sandbox": "read-only",
  "model": "gpt-5.6-sol",
  "config": { "model_reasoning_effort": "medium" }
})
# → threadId: "019da14b-..."  /  flags: "No rollback strategy for the schema migration in step 3."

# Round 2 — Claude revises and resubmits only the changed section
mcp__plugin_codex_cli__codex-reply({
  "threadId": "019da14b-...",
  "prompt": "Revised step 3 to use an expand-contract migration with a reversible intermediate state:\n\n[REVISED SECTION]\n\nDoes this address the rollback concern?"
})

# Round 3 — triage remaining risks
mcp__plugin_codex_cli__codex-reply({
  "threadId": "019da14b-...",
  "prompt": "Of the risks you flagged, which would actually block merge vs. which can be mitigated post-launch?"
})
```

**Start a fresh thread when:** reviewing a different plan, the `threadId` is no longer in context, or the plan has been rewritten so substantially that re-priming is cleaner than patching. See `../references/patterns.md`.

## After the review

Codex's critique is input, not instructions — treat it the way you'd treat a thoughtful colleague's review, not a verdict.

- **Relay it.** Surface the findings to the user (or act on them); don't silently absorb a critique and quietly rewrite the plan as if it were your own conclusion.
- **Don't auto-apply.** Codex can be wrong or miss project context it never saw (see `../references/patterns.md` → Validation). Weigh each point against the actual constraints before revising.
- **Surface genuine disagreements to the user** rather than looping with Codex to force consensus — if you and Codex still differ after a round or two, that disagreement is exactly what the user needs to see.

## Safety

- **Always** `sandbox: "read-only"`.
- Never use `workspace-write`, `danger-full-access`, or `--dangerously-bypass-approvals-and-sandbox`.

## Fallback (rare)

If the MCP server is unavailable, see `../references/commands.md` for the Bash `codex exec` form. Requires `dangerouslyDisableSandbox: true`. Don't pipe with `$(cat plan.md)` — Codex doesn't expand shell substitutions; either embed the content or pass a repo-relative path.