hyper-plan-review
Skill5 starsChanged 48 days agoMITView on GitHub
Use after a plan exists in .hyperclaude/plans/ and should be sanity-checked before execution. Also when the user invokes /hyperclaude:hyper-plan-review. Runs Codex critique on the plan — distinct from /hyperclaude:hyper-code-review (code, not plans).
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cc-changelogSkill
- codex-changelogSkill
- hyper-autoSkill
- hyper-code-reviewSkill
- hyper-docs-loopSkill
- hyper-docs-reviewSkill
- hyper-docs-syncSkill
- hyper-implement-loopSkill
- hyper-implementSkill
- hyper-interviewSkill
- hyper-memorySkill
- hyper-plan-loopSkill
- hyper-planSkill
- hyper-recapSkill
- hyper-researchSkill
- hyper-setupSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
When Group 2 is '--resume' (truthy) and Group 3 is undefined, treat as --resume auto.
- Distinctive: line 43
If the argument doesn't match the regex, ask the user to clarify and stop.
- Distinctive: line 53
Explicit argument (Group 1): If Group 1 is non-empty, treat it as the plan path.
- Very specific: line 54
Most recent in
.hyperclaude/plans/: If Group 1 is empty, run via the Bash tool: - Distinctive: line 60
If that returns a path, use it.
- Very specific: line 76
If --resume was matched (Group 2 truthy), append --resume <value> to the argv passed to the bridge, where <value> is Group 3 if present, …
- Very specific: line 78
Use the Bash tool with run_in_background: true (invocation mode: ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.
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 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

