adversarial-plan-review

name	adversarial-plan-review
description	Use when in plan mode and the plan draft is ready for review, before finalizing — runs the Codex CLI as a devil's advocate critic to iteratively challenge the plan until it survives adversarial scrutiny

Adversarial Plan Review

Stress-test a draft plan before finalizing. Runs the Codex CLI (codex exec) as an external critic using plan-critic criteria. Revise and re-run until approved. Max 3 rounds.

Requires: codex CLI installed and authenticated.

When to Use

Invoke manually after drafting a plan and before finalizing. Does not auto-trigger.

The Loop

digraph review_loop {
    "Plan draft ready" [shape=box];
    "Write plan to temp dir" [shape=box];
    "Run codex exec" [shape=box];
    "Read critic output" [shape=box];
    "Verdict?" [shape=diamond];
    "Revise plan (blocking issues only)" [shape=box];
    "Round > 3?" [shape=diamond];
    "Surface blockers to user, stop" [shape=box];
    "Finalize plan" [shape=box];

    "Plan draft ready" -> "Write plan to temp dir";
    "Write plan to temp dir" -> "Run codex exec";
    "Run codex exec" -> "Read critic output";
    "Read critic output" -> "Verdict?";
    "Verdict?" -> "Finalize plan" [label="APPROVED"];
    "Verdict?" -> "Round > 3?" [label="BLOCKING"];
    "Round > 3?" -> "Revise plan (blocking issues only)" [label="no"];
    "Round > 3?" -> "Surface blockers to user, stop" [label="yes"];
    "Revise plan (blocking issues only)" -> "Write plan to temp dir";
}

How to Run the Critic

Step 0: Create a workspace-scoped temp dir to avoid collisions between parallel workspaces:

REVIEW_DIR="/tmp/plan-review-$(git rev-parse --abbrev-ref HEAD)"
mkdir -p "$REVIEW_DIR"

All files below go in $REVIEW_DIR/.

1. Write current plan text to $REVIEW_DIR/index.md.
2. If round > 1, append prior critique below a --- separator.
3. Run via Bash (note: unquoted heredoc so $REVIEW_DIR expands):

codex exec \
  --dangerously-bypass-approvals-and-sandbox \
  --ephemeral \
  -o "$REVIEW_DIR/output.md" \
  "$(cat <<PROMPT
# Plan Critic

Purpose:
Validate the implementation plan in $REVIEW_DIR/index.md against requirements and produce a smaller, clearer, safer version.

Behavior:
- Think like a skeptical senior engineer.
- Prioritize correctness, simplicity, and requirement coverage.
- Remove unnecessary scope.
- Expose ambiguity and hidden assumptions.
- Rewrite plans into concise, executable steps.

Review criteria:
- Requirement coverage
- Simplicity
- Dependency awareness
- Sequencing correctness
- Testability
- AI execution clarity

Anti-patterns to flag:
- vague verbs like "handle", "support", "improve"
- premature abstraction
- broad refactors not required by the task
- missing validation steps
- hidden migrations or config changes
- steps that bundle multiple concerns together
- work that is not tied to a requirement

Output format:
- **Verdict:** one paragraph on whether this plan will succeed
- **Gaps/Issues:** numbered list of blocking issues (if any)
- **Simplified Plan:** rewritten plan with unnecessary scope removed
- **Validation Checklist:** steps to verify the plan works
- **Risks:** optional, only if significant
- End with exactly one token on its own line: APPROVED or BLOCKING

Blocking = requirement gaps, sequencing errors, missing validation, or unnecessary scope.
PROMPT
)"

4. Read $REVIEW_DIR/output.md for the verdict.
5. Check last non-empty line for APPROVED or BLOCKING.

Revision Rules

• Revise only to resolve blocking issues. Do not expand scope.
• Do not add work the critic did not flag.
• Non-blocking suggestions are optional.

Non-Convergence

After round 3 still BLOCKING: present remaining blockers to the user and stop. Let them decide.