Independent cross-model review of implementation plans. Codex reviews, Claude revises spec.md and prd.json directly, you decide when it's good enough.
When to Use
- After
/workflows:planor/deepen-plan, before/workflows:work - High-stakes plans: auth, payments, data models, multi-service coordination
- Plans that will take days to implement
- When you want a genuinely independent perspective (not same-model echo chamber)
When to Skip
- Simple bug fixes, small changes
- Already-validated approaches
- Speed matters more than thoroughness
Prerequisites
Codex CLI: npm install -g @openai/codex
Arguments
Parse $ARGUMENTS for:
- Plan folder path — e.g.,
docs/plans/2026-01-30-feat-user-auth/ - Model override — e.g.,
gpt-5.5(default:gpt-5.5)
If no path provided, check ls docs/plans/ sorted by date and ask user which plan to review.
Workflow
Step 1: Setup
Generate a review ID for session tracking:
REVIEW_ID=$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 3 2>/dev/null || head -c 3 /dev/urandom | od -An -tx1 | tr -d ' \n')
Validate format matches ^[0-9]{8}-[0-9]{6}-[0-9a-f]{6}$ (prevents path traversal).
Step 2: Load Plan
Read the plan folder:
spec.md(required)prd.json(required)brainstorm.md(optional — shaping context)
If spec.md or prd.json missing, inform user and abort.
Step 3: Send to Codex
Write the structured output schema:
cat > /tmp/codex-plan-schema-${REVIEW_ID}.json <<'SCHEMA'
{
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"severity": { "enum": ["critical", "high", "medium", "low"] },
"category": { "enum": ["correctness", "architecture", "security", "data-model", "edge-case", "story-breakdown", "feasibility"] },
"description": { "type": "string" },
"suggestion": { "type": "string" }
},
"required": ["severity", "category", "description", "suggestion"],
"additionalProperties": false
}
},
"summary": {
"type": "object",
"properties": {
"total": { "type": "number" },
"critical": { "type": "number" },
"high": { "type": "number" },
"medium": { "type": "number" },
"low": { "type": "number" }
},
"required": ["total", "critical", "high", "medium", "low"],
"additionalProperties": false
}
},
"required": ["issues", "summary"],
"additionalProperties": false
}
SCHEMA
Send plan to Codex with structured output and here-doc prompt:
codex exec \
-m ${MODEL:-gpt-5.5} \
-s read-only \
-c model_reasoning_effort=high \
--output-schema /tmp/codex-plan-schema-${REVIEW_ID}.json \
-o /tmp/codex-review-${REVIEW_ID}.json \
<<EOF
You are reviewing an implementation plan before any code is written.
Read these files in the repo:
- ${PLAN_FOLDER}/spec.md
- ${PLAN_FOLDER}/prd.json
- ${PLAN_FOLDER}/brainstorm.md (if exists)
Review for:
1. **Correctness** — Will this achieve the stated goals? Are acceptance criteria testable?
2. **Architecture** — Sound technical choices? Missing components? Over-engineering?
3. **Security** — Auth gaps, injection risks, data exposure, OWASP concerns?
4. **Data Model** — Schema conflicts, missing constraints, migration risks?
5. **Edge Cases** — Race conditions, concurrency, error paths, failure modes?
6. **Story Breakdown** — Stories atomic? Dependencies correct? Anything missing?
7. **Feasibility** — Unrealistic assumptions or missing prerequisites?
For each issue, provide severity, category, description, and suggestion.
EOF
Fail-open: If codex is not installed or the command fails:
- Self-review spec.md and prd.json against the same 7 categories
- Note clearly: "Self-review (Codex unavailable) — install with
npm install -g @openai/codex" - Continue to Step 4
Step 4: Present Feedback
Read /tmp/codex-review-${REVIEW_ID}.json and parse the structured output.
Present to user:
## Codex Review -- Round N (model: gpt-5.5)
[Codex's feedback, formatted from JSON]
---
Issues: X total (Y critical, Z high, ...)
Step 5: Revise spec.md and prd.json
Address each issue directly in the real files. Use your judgment — do NOT blindly accept every suggestion.
For each issue:
- Agree → edit spec.md and/or prd.json directly
- Disagree → note why you're skipping it
- Contradicts user's requirements → skip and flag
Show the user what changed:
### Revisions (Round N)
- [What changed in spec.md and why]
- [What changed in prd.json and why]
- [Skipped: issue X — reason]
For critical/high issues that map to specific stories, add to that story's review_findings in prd.json:
{
"severity": "high",
"category": "security",
"agent": "codex-gpt-5.5",
"finding": "No auth on agent write endpoints",
"suggestion": "Add per-agent API keys with ACL",
"status": "resolved",
"resolved_at": "2026-01-30T14:45:00Z"
}
Step 6: User Decides
Use AskUserQuestion tool:
Question: "Round N complete. X issues addressed, Y skipped. Another round?"
Options:
- Another round — Send updated plan back to Codex for re-review
- Done — Plan is good enough, proceed to handoff
- Review changes — Show diff of what changed in spec.md and prd.json
- Undo last round — Revert changes from this round (git checkout the files)
If Another round and round < 5: → Go to Step 6b (Re-submit)
If Another round and round = 5: → Warn: "Max 5 rounds reached. Proceed anyway or stop here?"
If Done → Step 7
If Review changes:
→ Show git diff for spec.md and prd.json, then re-ask
If Undo:
→ git checkout -- ${PLAN_FOLDER}/spec.md ${PLAN_FOLDER}/prd.json
→ Re-ask from the previous round's state
Step 6b: Re-submit to Codex (Round 2+)
Use fresh codex exec with structured output and here-doc (session resume does not support -o or --output-schema):
codex exec \
-m ${MODEL:-gpt-5.5} \
-s read-only \
-c model_reasoning_effort=high \
--output-schema /tmp/codex-plan-schema-${REVIEW_ID}.json \
-o /tmp/codex-review-${REVIEW_ID}.json \
<<EOF
You are re-reviewing an implementation plan after revisions. This is round N.
Read these files in the repo:
- ${PLAN_FOLDER}/spec.md
- ${PLAN_FOLDER}/prd.json
- ${PLAN_FOLDER}/brainstorm.md (if exists)
Previous round found these issues:
[List prior findings]
Changes made:
[List specific revisions]
Skipped (with rationale):
[List skipped items and why]
Re-review. Focus on:
1. Whether previous issues were addressed
2. Any new issues introduced by revisions
3. Anything missed in prior passes
Review categories: correctness, architecture, security, data-model, edge-case, story-breakdown, feasibility.
EOF
Return to Step 4.
Step 7: Log & Handoff
Add review summary to prd.json log array:
{
"timestamp": "2026-01-30T14:30:00Z",
"action": "codex_review",
"review_id": "REVIEW_ID",
"model": "gpt-5.5",
"rounds": 3,
"issues_found": 14,
"issues_resolved": 12,
"issues_skipped": 2
}
Clean up:
rm -f /tmp/codex-review-${REVIEW_ID}.json /tmp/codex-plan-schema-${REVIEW_ID}.json
Present summary:
Codex Review complete (ID: REVIEW_ID)
Rounds: N
Issues found: X (Y critical, Z high)
Resolved: A | Skipped: B
spec.md and prd.json updated in place.
Then use AskUserQuestion tool:
Question: "Plan reviewed and updated. What next?"
Options:
- Start
/workflows:work— Begin implementing stories - Run
/deepen-plan— Further enrich with skill/agent discovery - Review final plan — Read updated spec.md
- Done for now — Come back later
Rules
- Claude actively revises spec.md and prd.json between rounds — the real files, not copies
- User controls the loop — Codex doesn't decide when to stop, you do
- Default model:
gpt-5.5. Accept override from arguments. - Always use read-only sandbox — Codex reads the codebase but never writes
- Max 5 rounds as safety cap (user warned, can override)
- Show user each round's feedback and revisions transparently
- Fail-open: on any error, fall back gracefully. Never trap the user.
- If a revision contradicts user's explicit requirements, skip it and note why
- Review ID validated against
^[0-9]{8}-[0-9]{6}-[0-9a-f]{6}$ - Findings written in prd.json
review_findingsformat for downstream consumption - No temp plan file — Codex reads the real spec.md and prd.json from the repo
- Undo is always available — files are in git, user can revert any round
- Always pass
-c model_reasoning_effort=high— deeper analysis for plan review - Use
--output-schemafor structured JSON output — deterministic parsing, no markdown guessing - Use here-doc for prompts — avoids shell escaping issues with long, multi-line prompts
- Round 2+ uses fresh
codex exec— session resume does not support-oor--output-schema - Do NOT use
--ephemeral— silently breaks session resume (creates new session instead)