/plan-review

name: plan-review
description: "Pre-ExitPlanMode adversarial plan review loop via Codex exec. Use when: in plan mode, before presenting a plan to the user; reviewing an in-context plan draft. Not for: .md file review (use doc-review), code review (use codex-code-review), lifecycle spec review (use review-spec). Output: review trail summary + plan gate (✅ Plan Ready / ⛔ Plan Blocked / ⚠️ Plan Needs Human)."
allowed-tools: Bash(bash:*), Bash(git:*), Bash(node:*), Read, Grep, Glob, Task, Skill

Plan Review Skill

Adversarial review gate for plan-mode drafts: the plan is challenged by an independent reviewer and revised until convergence **before** `ExitPlanMode` presents it to the user.

Trigger

• Keywords: plan review, review plan, plan-review, pre-ExitPlanMode review
• Self-invoke: in plan mode, before calling `ExitPlanMode`, when the project opts in via `@rules/auto-loop-project.md ## Plan Review: enabled` or the user asks for plan review

When NOT to Use

• Reviewing `.md` files on disk (use `/codex-review-doc` — different artifact: filesystem path vs in-context plan text)
• Reviewing lifecycle specs `1-requirements.md` / `2-tech-spec.md` (use `/review-spec`)
• Code review (use `/codex-review-fast`)
• Not in plan mode / no plan draft exists

Boundary Contract (v1 Acceptance Scope)

• Review gate applies **only when this skill is actually invoked** (A1 skill-driven; enabled-but-unexecuted detection is v2).
• Analysis-only: the reviewer surfaces findings; **Claude revises the plan** — the skill never rewrites or deletes plan content itself.
• Review pass ≠ execution approval: the user still arbitrates the final plan after `ExitPlanMode` (FR-14 Won't).
• **Fully behaviour-layer**: no hook parses plan-review output and no state file records the loop. The skill counts its own rounds in conversation, and the sentinels below are prose contracts the model and the human read — nothing mechanical routes on them (hook-lightweighting § 3.3).

Arguments

| Arg | Behavior | |-----|----------| | (none) | tier = `standard` — Codex alone, with the fix → re-review loop | | `--quick` | Single Codex pass, no loop | | `--dual` | Adds a secondary reviewer in parallel. **Off unless passed** — for a release or a security-sensitive plan, not routine planning | | `--deep` | Delegate to `/codex-brainstorm` (Nash equilibrium debate; attack/defense built-in) | | `--skip-review` | Immediate bypass: emit `[PLAN_REVIEW_SKIPPED]`, present raw plan | | `--verbose` | Round-by-round trail (default: summary only) |

User escape (NFR-5): any explicit "skip review" / "直接看 plan" instruction — detected at skill entry **and** before each re-review round — exits within ≤1 round, emits `[PLAN_REVIEW_SKIPPED]`, and presents the current plan.

Workflow

sequenceDiagram
    participant C as Claude (plan mode)
    participant RD as security-redact
    participant CX as Codex exec
    participant SA as Secondary (Task)

    C->>C: Step 1: tier + round counter (in conversation)
    C->>RD: Step 2 redaction contract
    alt high-confidence secret hit
        C->>C: [PLAN_REVIEW_DEGRADED] → ExitPlanMode (plan NOT sent to reviewer)
    else masked plan
        alt quick
            C->>CX: 1-pass review (references/codex-prompt-plan.md)
        else standard
            C->>CX: Codex review loop (save threadId)
            opt --dual
                C->>SA: Secondary perspective (parallel)
            end
        else deep
            C->>C: Skill("codex-brainstorm", plan challenge)
        end
        loop until ✅ Plan Ready or max_rounds (default 5)
            CX-->>C: findings + ## Plan Review sentinel
            C->>C: revise plan (author-side), increment round
            C->>CX: re-review (§ Resume, references/review-loop-plan.md)
        end
        alt converged
            C->>C: ✅ Plan Ready → trail summary → ExitPlanMode
        else max_rounds reached
            C->>C: ⚠️ Plan Needs Human + residual findings → user arbitrates
        else codex_fail (adapter exit 1)
            C->>C: [PLAN_REVIEW_DEGRADED] → ExitPlanMode
        end
    end

Step 1: Tier + round budget

Determine tier (`standard` default; `--quick` / `--deep` explicit) and the round cap: read `## Plan Review Max Rounds` from `rules/auto-loop-project.md` directly (unset → **5**). The round counter lives **in this conversation** — state the current round in each re-review dispatch ("round 2/5") so the count survives in the transcript. There is no state file to open and no script to run: the loop's bookkeeping is the skill's own.

Step 2: Secret redaction (NFR-8, fail-closed)

Apply the contract from `scripts/security-redact.js` (verified API — `scanHighConfidence` returns `{name, fingerprint} | null`, it does NOT throw):

const { scanHighConfidence, maskMediumConfidence } = require('./scripts/security-redact.js');
const high = scanHighConfidence(planText);   // {name, fingerprint} | null
if (high) {
  // fail-closed: plan is NOT sent to any reviewer
  // → output [PLAN_REVIEW_DEGRADED]; plan still delivered to user via ExitPlanMode
} else {
  send(maskMediumConfidence(planText));      // medium-confidence → [REDACTED] before send
}

Run via `node -e` against the plan text, feeding the text through **stdin with a quoted heredoc — never as an argv literal**:

node -e '...' <<'PLAN_EOF_<random-hex>'
<plan text>
PLAN_EOF_<random-hex>

> `<random-hex>` is a **placeholder to be generated**, not a value to copy. It is written this way > deliberately: the rationale below is that "a fixed delimiter makes the attack a copy-paste", and > an example carrying a concrete literal reinstates exactly that for anyone who copies rather than > generates. Substitute a fresh suffix on every invocation, per the table that follows.

**The delimiter must be freshly randomized per invocation, and you must verify it does not collide.** Before emitting the command:

| Step | Action | |------|--------| | 1 | Generate