user-invocable	true
allowed-tools	Bash, Read, Write, Glob, Grep, AskUserQuestion, EnterPlanMode, ExitPlanMode
description	Send the current plan to Codex for adversarial review, iterate through multiple rounds using a shared transcript, and stop only when Claude and Codex converge or the user resolves the disagreement.

Codex Plan Review

Trigger

/codex-review

Overview

Use this skill when Claude has a technical plan that should be challenged by Codex before implementation.

The goal is not a one-shot review. Claude sends the plan to Codex, revises it, sends it back, and continues until:

Codex approves the plan
only minor suggestions remain
or Claude and Codex reach a real stalemate that needs user input

Claude and Codex share one evolving transcript for the entire review. If a fact, repo observation, decision, or disagreement is not written into that transcript, assume Codex does not know it.

Core Rules

If the conversation already contains a plan, use it. Do not ask the user to restate it.
Ask the user for review settings only when needed:
- Codex model (if not specified, use the Codex CLI default — do not pass -m)
- Maximum rounds (default: 4)
Prefer inspecting the repository yourself to discover relevant files before asking the user for file lists.
Do not freeze context after round 1. If Claude learns new repo facts, constraints, or tradeoffs between rounds, append them to the shared transcript before the next Codex turn.
Do not blindly accept all Codex feedback. For each substantial point, explicitly decide whether to accept, reject, or partially accept it, and record the decision in the Feedback Ledger.
Prefer revising the current plan over replacing it wholesale.
Ask the user for confirmation (via AskUserQuestion) only when the revised plan changes scope, introduces a new tradeoff, or requires a user decision. Routine revisions that stay within the original scope can be sent back to Codex without pausing.
The user has final say if Claude and Codex do not converge.

Working Directory

Create a temporary working directory for the review session:

/tmp/codex-plan-review/<task-slug>/
  shared-context.md
  current-plan.md
  round-1.prompt.md
  round-1.codex.md
  round-2.prompt.md
  round-2.codex.md
  ...
  final-summary.md

Generate <task-slug> from the topic of the plan using lowercase letters, digits, and hyphens. If the directory already exists, append a timestamp suffix (e.g., <task-slug>-20260323-1430) to avoid collisions with prior review sessions.

Do not discard earlier round files — they form the audit trail.

Shared Transcript

Create shared-context.md as the single source of truth. It must contain these sections:

# Objective
{one-line goal}

# Success Criteria
{what a good final implementation plan must cover}

# Constraints And Non-Goals
{scope boundaries, explicit non-goals, compatibility requirements}

# Review Settings
- Model: {explicit model if chosen, otherwise "CLI default"}
- Max rounds: {max_rounds}

# Repo Evidence
- /abs/path/file1: why it matters
- /abs/path/file2: why it matters

# Current Plan
{full current plan text}

# Feedback Ledger
- R1-I1 | Status: ACCEPTED | Reason: ...
- R1-I2 | Status: REJECTED | Reason: ...
- R1-I3 | Status: PARTIAL  | Reason: ...
- R1-I4 | Status: DEFERRED | Reason: awaiting user decision on ...

# Discussion History
## Round 1 - Claude
- Why this version exists
- What changed since the prior round
- Open questions for Codex

## Round 1 - Codex
Verdict: REVISE
- Main concerns
- Suggested edits
- Risks or sequencing issues

Rules for this transcript:

Individual round files (round-N.prompt.md, round-N.codex.md) are immutable once written. Never modify them.
# Discussion History is append-only under normal operation.
Update # Current Plan whenever the plan changes.
Add new repo files or discoveries to # Repo Evidence before the next Codex round.
Record every substantial Codex issue in # Feedback Ledger with a unique ID (R{round}-I{issue}) and status: ACCEPTED, REJECTED, PARTIAL, or DEFERRED (for items awaiting user input), plus a short reason.
If the transcript needs compaction (see Context Management), append the older discussion to shared-context.archive.md before trimming (append on each compaction event, do not overwrite prior archived material). Never silently delete history.
If something is not in the transcript, assume Codex does not know it.

Context Management

Prefer a concise shared transcript plus repository file paths over pasting large file contents into prompts. Codex runs with -C {repo_root} so it can read files directly.
If the transcript grows too large, append resolved discussion rounds to shared-context.archive.md and keep only: durable facts, unresolved issues, the Feedback Ledger, and the latest plan in the main transcript. Reference the archive path in a note at the top.
If the plan depends on unverified repository facts, inspect the files first and update # Repo Evidence before asking Codex to continue.
Only ask the user to narrow scope if Claude cannot reasonably determine the relevant context by inspection.
Size guard: If the shared transcript exceeds ~80,000 characters, trigger the archival compaction above.
Greenfield / no-repo plans: If there is no repository to inspect (e.g., architecture-only or greenfield plans), skip # Repo Evidence and instead capture the relevant context directly in the transcript under a # Reference Material section (docs, conversation history, design constraints).

Workflow

Step 1: Gather the Plan

Check whether the conversation already has a plan.

If yes: use that plan. If no: use AskUserQuestion to ask the user to provide or describe the plan to review.

Step 2: Gather Repository Context

Inspect the repository and identify the files Codex should read.

Prefer Claude-driven discovery first:

inspect files named in the plan
inspect files directly affected by the proposed work
inspect tests, configs, schemas, or docs that constrain the work

Only if the relevant context is still unclear, ask the user which extra files or directories Codex should read.

If there is no repository (greenfield/architecture plan), gather reference material from the conversation or docs instead.

Step 3: Create the Working Files

Write shared-context.md and current-plan.md.

The # Repo Evidence section should list each relevant file with a one-line note explaining why it matters.

Step 4: Round 1 — Initial Codex Review

Write round-1.prompt.md with:

You are reviewing a technical implementation plan. Your role is adversarial reviewer. Be thorough and critical.

Read these inputs first:
- {shared_context_path}
- Then read the repository files listed under `# Repo Evidence` in that transcript, if present; otherwise rely on `# Reference Material` in the transcript

Evaluate the plan under `# Current Plan` using the full shared context.

Return EXACTLY this structure:

Verdict: APPROVE | REVISE | BLOCKED

Strengths:
- ...

Issues:
- [CRITICAL] ...
- [SUGGESTION] ...

Missing considerations:
- ...

Validation or sequencing concerns:
- ...

Improved plan: (only if Verdict is REVISE or BLOCKED)
Provide the complete revised plan. This must be a full plan, not a diff.

If your only concerns are [SUGGESTION] items with no [CRITICAL] issues, APPROVE.

Execute:

codex exec -C {repo_root} -o {workdir}/round-1.codex.md "$(cat {workdir}/round-1.prompt.md)"

If the user explicitly chose a model, add -m {model} to the command.

Step 5: Process Codex Feedback

Read round-N.codex.md.

Append the Codex response summary to # Discussion History.

Classify each substantial point in # Feedback Ledger:

ACCEPTED — incorporate into the plan
REJECTED — explain why it doesn't apply (reasoning will be visible to Codex in transcript)
PARTIAL — take part of the suggestion with modifications
DEFERRED — requires user input before Claude can decide (used primarily in BLOCKED path)

Check for effective approval first: If there are no [CRITICAL] issues and only [SUGGESTION] items remain, treat this as EFFECTIVE-APPROVAL and go to Step 8. Note the remaining suggestions in the final summary.

If Verdict is APPROVE: Verify that Claude also has no material open concerns discovered during this round. If Claude is also satisfied, go to Step 8. If Claude has a new concern, append it to the transcript and send one more round.

If Verdict is BLOCKED:

Present the blocking issue clearly
Use AskUserQuestion to ask whether to rethink the plan or override the block
Mark blocking items as DEFERRED in the Feedback Ledger until the user decides
If rethinking fundamentally changes the objective, append the current transcript to shared-context.archive.md, create a fresh transcript with the new objective, and restart the loop. Continue using the next unused round number in the same working directory so immutable round files do not collide.
Otherwise continue as a REVISE round

If Verdict is REVISE:

Present the Codex feedback to the user in a clear summary
For each issue, decide whether to accept, reject, partially accept, or defer
Revise the plan
Update current-plan.md and # Current Plan in shared-context.md
Append Claude's reasoning to # Discussion History:

## Round {round} - Claude
Changes made:
- {list of accepted changes}

Rejected feedback (with reasoning):
- {rejected items and why}

Partially accepted:
- {what was taken and what was modified}

Open questions for Codex:
- {any}

If the revision changes scope, introduces a new tradeoff, or requires a user decision, ask for confirmation via AskUserQuestion before proceeding. Otherwise continue directly.

Step 6: Later Rounds

For round 2+, write round-N.prompt.md with:

You are continuing an adversarial plan review. This is round {round}/{max_rounds}.

Read these inputs first:
- {shared_context_path}
- Then read the repository files listed under `# Repo Evidence`, if present; otherwise rely on `# Reference Material` in the transcript

The plan has been revised. The `# Feedback Ledger` and `# Discussion History` in the transcript show which of your prior concerns were accepted, rejected, or partially accepted, with reasoning.

Focus on:
1. Whether your prior concerns were adequately addressed
2. Any new issues introduced by the revised plan
3. Unresolved disagreements only
4. Do not rehash points already resolved unless the latest revision regressed

Return EXACTLY this structure:

Verdict: APPROVE | REVISE | BLOCKED

What improved:
- ...

Assessment of prior feedback:
- Addressed well: ...
- Still unresolved: ...

Remaining issues:
- [CRITICAL] ...
- [SUGGESTION] ...

Missing considerations:
- ...

Validation or sequencing concerns:
- ...

Improved plan: (only if Verdict is REVISE or BLOCKED)
Provide the complete revised plan. This must be a full plan, not a diff.

If your only remaining concerns are [SUGGESTION] items with no [CRITICAL] issues, APPROVE.

Before each later round, update the transcript per the rules in the Shared Transcript section (update # Current Plan, # Repo Evidence, # Feedback Ledger, append to # Discussion History).

Execute with the same command pattern, then return to Step 5.

Step 7: Repeat Until Convergence or Stalemate

Continue the loop until one of the convergence rules below is reached.

Step 8: Finalize

Write final-summary.md to the working directory with:

# Codex Plan Review Summary

## Final Plan
{the agreed-upon plan}

## Review History

### Round 1
**Codex verdict**: ...
**Key issues raised**: ...
**Claude response**: accepted X, rejected Y because ...
**Changes made**: ...

### Round N
...

## Feedback Ledger
{full ledger from transcript}

## Outcome
- Rounds taken: {round}
- Final verdict: APPROVED | EFFECTIVE-APPROVAL | USER-DECIDED
- Key improvements from review: (bullet list)

## Unresolved Disagreements
{any points where Claude and Codex did not converge, with both perspectives}

## Working Files
- Transcript: {shared_context_path}
- Archive: {archive_path if created}
- Round files: {workdir}/round-*.prompt.md, round-*.codex.md

Also write a copy to {repo_root}/codex-review-output.md if write permissions allow and it is appropriate for the project.

Present the final plan, key improvements, unresolved risks, and file paths to the user.

Convergence Rules

Stop the review loop when any of these is true:

Approved: Codex returns APPROVE, and Claude also has no material open concerns.
Effective approval: Codex returns only [SUGGESTION] issues and no [CRITICAL] issues. Treat as approval and note the remaining suggestions.
Repeated disagreement: The same disagreement repeats for two rounds with no new evidence. Stop and ask the user to decide.
Max rounds reached: {round} reaches {max_rounds} (i.e., do not start round N+1 if N == max_rounds). Summarize the best current plan and unresolved points, then ask the user for the final call.
Unproductive loop: Codex feedback is substantively identical to the prior round. Stop and escalate to the user.

Failure Handling

If codex is not installed or the command fails, report that clearly and stop. Do not fabricate a Codex review.
If Codex returns a vague answer, ask a narrower follow-up question in the next round instead of pretending the issue is resolved.
If the output file is empty or malformed, retry once using a new artifact name (round-N.retry-1.codex.md) to preserve the immutability of the original file. Read the latest successful artifact for that round. If the retry also fails, report the problem and ask the user how to proceed.
If Codex keeps proposing out-of-scope changes, write the scope boundary explicitly into # Constraints And Non-Goals and instruct Codex to review within that boundary on the next round.

fyxme/SKILL.md

Select an option

No results found