hyper-plan-review

Plan review gate. Locates a plan file, sends it to Codex for critique, saves the review to .hyperclaude/plan-reviews/<timestamp>-<slug>.md, and you read the review and refine the plan.

When to use

• User typed /hyperclaude:hyper-plan-review (with or without an argument).
• You just produced an implementation plan and want a critic pass before executing.

How to invoke

Invocation argument: $ARGUMENTS

--resume is supported. Paths with spaces are unsupported.

Argv grammar

Apply this regex to the trimmed $ARGUMENTS:

^(?:((?!--)\S+))?(?:\s*(--resume)(?:\s+(\S+))?)?\s*$

• Group 1 = optional plan path (negative lookahead prevents matching --resume as a path)
• Group 2 = literal "--resume" token (truthy when present, undefined when not)
• Group 3 = optional resume artifact path

When Group 2 is '--resume' (truthy) and Group 3 is undefined, treat as --resume auto.

Valid invocations:

• /hyperclaude:hyper-plan-review — auto-discovers most recent plan, fresh run
• /hyperclaude:hyper-plan-review path/to/plan.md — explicit plan path, fresh run
• /hyperclaude:hyper-plan-review --resume — auto-discovers plan, resumes from latest artifact (auto)
• /hyperclaude:hyper-plan-review --resume <prev-artifact-path> — resumes from explicit artifact
• /hyperclaude:hyper-plan-review path/to/plan.md --resume — explicit path, resume from auto
• /hyperclaude:hyper-plan-review path/to/plan.md --resume <prev-artifact-path> — explicit path, explicit artifact

If the argument doesn't match the regex, ask the user to clarify and stop.

Resume semantics

See ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md for the shared --resume semantics (explicit vs auto fallback, the template-version precondition). Plan-review's identity check keys on the plan path.

Step 1 — Resolve the plan path

In priority order:

1. Explicit argument (Group 1). If Group 1 is non-empty, treat it as the plan path.
2. Most recent in `.hyperclaude/plans/`. If Group 1 is empty, run via the Bash tool:

   ls -1t .hyperclaude/plans/*.md 2>/dev/null | head -1

If that returns a path, use it.

1. Nothing found. Tell the user: "No plan file found. Write your plan to .hyperclaude/plans/<slug>.md, or pass an explicit path: /hyperclaude:hyper-plan-review path/to/plan.md." Stop.

Step 2 — Compose the review brief (or omit it)

Compose per ${CLAUDE_PLUGIN_ROOT}/references/review-brief.md, assigning the scratchpad path to BRIEF_FILE per its shell-safety recipe; with no admissible source, omit the flag.

Concrete omission case for this skill: a fresh session with no conversation history that auto-discovers a plan (Step 1.2) has no (a)/(b) source at all — omit the flag, or ask the user for their requirements and use their reply. Never mine the plan file's prose — it is Claude-authored; quoting it would let the planner bless its own additions.

Step 3 — Run the bridge

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" plan-review --plan-path "<resolved path>" [--review-brief "$(cat "$BRIEF_FILE")"]

If --resume was matched (Group 2 truthy), append --resume <value> to the argv passed to the bridge, where <value> is Group 3 if present, otherwise auto. The --review-brief "$(cat "$BRIEF_FILE")" token is OPTIONAL — present when a source exists (fresh and --resume alike), omitted otherwise.

Use the Bash tool with `run_in_background: true` (invocation mode: ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md).

Step 4 — Surface the review

Once the bridge task completes, parse the JSON envelope from its stdout per ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md. On success, read the review file with the Read tool. Integrate the review:

• Blockers / Majors — fix the plan before proceeding.
• Minors / Improvements — optionally fold in.
• Verdict — communicate to the user.

When you revise the plan, always overwrite the same plan file in place. Do not create -v2.md or sibling files: the review thread's --resume identity is keyed on the plan path, so a new path breaks resume continuity (the next critique loses its prior context). Tell the user the plan was updated in place.

Output contract

Review files have frontmatter (mode: plan-review, task: plan path, slug, generated, plugin-version, codex-version, template-version, plan-path, review-brief (present when a brief was supplied, or carried forward from a successfully-resolved resume), plus codex-input-tokens, codex-cached-input-tokens, codex-output-tokens, codex-reasoning-output-tokens each emitted independently when Codex reported that token field in usage; omitted when Codex did not emit usage) followed by Issues / Improvements / Verdict sections.