zeikar 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
--resumeas 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 fromauto/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.
- Budget exceeded (docs > 200KB after revision): bridge returns
ok:false— NOT fallback. Tell user to narrow scope.
Step 1 — Resolve the plan path
In priority order:
Explicit argument (Group 1). If Group 1 is non-empty, treat it as the plan path.
Most recent in
.hyperclaude/plans/. If Group 1 is empty, run via the Bash tool:ls -1t .hyperclaude/plans/*.md 2>/dev/null | head -1If that returns a path, use it.
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 timeout: 600000 and 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.