agentleFS
zeikarzeikar/hyperclaude/skills/hyper-plan-review/SKILL.md

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).

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
  1. Very specific:

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

    line 33
  2. Distinctive:

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

    line 43
  3. Distinctive:

    Explicit argument (Group 1): If Group 1 is non-empty, treat it as the plan path.

    line 53
  4. Very specific:

    Most recent in .hyperclaude/plans/: If Group 1 is empty, run via the Bash tool:

    line 54
  5. Distinctive:

    If that returns a path, use it.

    line 60
  6. Very specific:

    If --resume was matched (Group 2 truthy), append --resume <value> to the argv passed to the bridge, where <value> is Group 3 if present, …

    line 76
  7. Very specific:

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

    line 78

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

  3. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.