hyper-plan-loop skill

hyper-plan-loop

Autonomous plan-hardening gate. Spawns the planner agent once, has it write its plan to .hyperclaude/plans/<YYYYMMDD-HHMM>-<slug>.md, has it reviewed, and revises via the still-live planner until the review returns no blocking findings (judged by meaning, not severity labels) or the cap is hit. The planner is spawned once; every revise round reuses its retained context. The reviewer is Codex plan-review through the bridge by default; the adversarial reviewer agent takes the seat for the run when the Codex budget is over pace (${CLAUDE_PLUGIN_ROOT}/references/reviewer-seat.md).

When to use

• User typed /hyperclaude:hyper-plan-loop <task>.
• User wants an autonomous plan → review → revise cycle in a single gesture.

Skip when:

• The task is one step — dispatch the implementer agent directly (pass run_in_background: false for the result inline).
• You want hands-on control over each plan / review round — use /hyperclaude:hyper-plan + /hyperclaude:hyper-plan-review manually.

Failure & recovery protocol — read first

${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md carries the shared cross-loop protocol: Spawn contract, Reply transport, Correctives and transport failures, Shared anti-patterns. references/failure-protocol.md (sibling of this file) is the plan-loop binding layer: it names this loop's reply shape (WROTE: <path>), the exact-path accept rule, the post-acceptance file/structure validation, the named reports, and what a transport failure preserves. ${CLAUDE_PLUGIN_ROOT}/references/reviewer-seat.md decides who reviews and how the lead drives the Claude seat. Step 0 makes Reading all three mandatory before the loop starts.

Spawn & reply transport

See ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md — Spawn contract for the Agent / SendMessage argument shapes, Reply transport for how each round's reply reaches the lead. Loop-specific bindings:

• Plan ownership: the planner writes the canonical plan file itself via caller-directed write-file mode (its Step 2 prompt carries the exact resolved path). The lead never Writes or Reads the plan body on the normal path — it does only a quiet ok/bad structure check (plus, in the Claude seat, the task blocks a finding cites), and only Reads the body for human-facing failure diagnostics. Every write-file-mode reply (initial write, corrective redo, revise) is gated to WROTE: <path>-only (Step 3 accept rule).

The lead must retain the following run-state across turns:

• plan_path — the resolved canonical plan path from Step 1.
• agent_id — the id returned by the Step 2 spawn, captured verbatim; the address for every later round.
• review_iteration — the review count, in either seat, the Step 7 cap bounds.
• seat (and its Reviewer seat: line), reviewer_agent_id, and the dropped findings — per reviewer-seat.md, set at Step 4.
• review_brief_file — the scratchpad path holding the composed review brief (Step 1), or null when no admissible source exists. Retained across turns; distinct from the shell variable BRIEF_FILE assigned from it in each Step 4/6 bridge Bash call.

How to invoke

Invocation argument: $ARGUMENTS

$ARGUMENTS is a task description only. There is NO existing-plan-path input mode — revision happens inside the loop. Resolution (mirrors stock hyper-plan):

• $ARGUMENTS non-empty → that is the task.
• $ARGUMENTS empty → fall back to the newest .hyperclaude/research/*.md (its task: frontmatter), or the user's most recent build/implement intent in this conversation.
• Nothing found → ask the user and STOP.

Step 0 — Read the failure & recovery protocol

Read all three files before spawning: ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md (the shared spawn + reply transport), ${CLAUDE_PLUGIN_ROOT}/references/reviewer-seat.md, AND references/failure-protocol.md (sibling of this file — the plan-loop binding: reply shape, accept rule, validation stages, named reports, transport-failure declaration).

Step 1 — Resolve task + slug + plan path

Reuse the stock hyper-plan logic — see skills/hyper-plan/SKILL.md Steps 1–2; do not duplicate the rule text. In brief:

1. Derive the canonical slug deterministically (lowercase, ASCII, alphanumerics + hyphen, first 5 words of the task joined by -). A task with no ASCII words gets an empty slug, per hyper-plan Step 1.

2. Unless the slug is empty (it would match every other no-ASCII artifact), scan all .hyperclaude/research/*.md frontmatter slug: fields (the canonical key — not the filename). If one OR MORE equals the derived slug (there may be a Codex + Claude pair), treat ALL matching files as the linked research artifacts and inline the full contents of ALL of them as context in Step 2. The research file an empty $ARGUMENTS took its task from is always linked, whatever its slug.

3. Resolve the plan path:

   mkdir -p .hyperclaude/plans
   date -u +%Y%m%d-%H%M
   

   Base path: .hyperclaude/plans/<timestamp>-<slug>.md (<timestamp>.md when the slug is empty). If it exists, append -2, -3, … until free.

4. Compose the review brief (or record null). Compose per ${CLAUDE_PLUGIN_ROOT}/references/review-brief.md. The admissible source here is $ARGUMENTS (the user's own task text) and decisions the user explicitly approved in this conversation — never the planner's plan output (Step 6 revises the plan every round; re-deriving the brief from it would let the planner bless its own scope additions). Record the resulting scratchpad path as review_brief_file, or null if no admissible source exists.

Step 2 — Spawn the planner

Use the Agent tool with NO name: field. The full contract text below goes in the prompt: string (a populated prompt field — not a separate message):

Agent({
  subagent_type: "hyperclaude:planner",
  prompt: "<the contract string assembled from the bullets below>"
})

The prompt string MUST contain:

• Task — verbatim.
• Research context — full contents of ALL matched research artifacts inline (there may be a Codex + Claude pair), if any were found in Step 1, each labelled with its exact repo path so the planner can cite it. Do not make the planner re-read them.
• Output format — a multi-task plan with ## Task N: <title> headings. Each task block: Files to create / modify (exact paths), Steps ([ ]-checkboxes, 2–5 min each), Verification (a command or observable change), Commit message (one line, conventional-commits). No frontmatter — plan body only; the skill owns the file name.
• Write-file mode — the exact resolved plan path from Step 1, stated literally, with an explicit instruction: use the Write tool to write the full plan to THAT EXACT path yourself (never a different path, never a -v2.md sibling), then reply with exactly WROTE: <that exact path> as your FINAL TEXT and NOTHING else — no plan body, no summary of changes, no preamble. This applies identically to every later round's reply.
• State that the planner stays live between rounds, will receive review feedback in later turns, and must retain its full planning context.

After the Agent(...) call — capture the returned agent_id verbatim into run-state; it addresses every later round.

Failure handling:

• Spawn fails → nothing ran this round. STOP per the transport-failure declaration in references/failure-protocol.md.
• Spawn returns no usable agent_id → the planner may still have written the plan (the spawn prompted the write). STOP per that same declaration.

Step 3 — Confirm the planner wrote the plan

The lead never Writes the plan — the planner writes the canonical file itself (caller-directed write-file mode, Step 2). The lead only verifies.

Read the reply from the spawn's <result> (on a later round, from that round's <result>).

Accept rule — applies to EVERY planner reply in write-file mode (the initial write, any corrective redo, and every Step 6 revise): the trimmed reply must match ^WROTE: <exact resolved plan path from Step 1>\s*$, where the path is the entire remaining string, verbatim. Any body echo, added prose, preamble, or a different path → corrective + escalation per references/failure-protocol.md (Reply-contract correctives).

File check (only after the accept rule passes): confirm the file is non-empty via the Bash tool:

[ -s "<resolved plan path>" ]

If missing or empty → apply the file-check corrective + escalation in references/failure-protocol.md (Reply-contract correctives).

In-place rule: every later revision overwrites THIS SAME path; never a -v2.md (or any other) sibling — the bridge's --resume keys on the plan path, and a new path breaks resume continuity.

Step 4 — Plan-review iteration 1 (fresh)

Iteration counting: the fresh review here is iteration 1.

Seat the reviewer per ${CLAUDE_PLUGIN_ROOT}/references/reviewer-seat.md Decide the seat. In either seat, leave the plan path alone while the review runs — the planner must not be sent a round's findings until this review has landed — then continue at Step 5 with the Read artifact.

Codex seat. Invoke via the Bash tool with run_in_background: true and timeout: 7200000 — this loop's own measured review boundaries were 469s and 1393s, past the 600s FOREGROUND ceiling the harness imposes, and a killed call costs the whole review with no artifact and no diagnostics. If review_brief_file is non-null, assign it to BRIEF_FILE per the shell-safety recipe in ${CLAUDE_PLUGIN_ROOT}/references/review-brief.md and append --review-brief "$(cat "$BRIEF_FILE")"; omit both when review_brief_file is null:

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

End the turn; when the completion notification arrives, Read the output file it names and parse the envelope line per ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md (envelope shape + strict-parse rule; that file merges stdout, stderr and an [exited with code N] marker, so the rule applies to the JSON line alone). On ok:true, read the artifact at path with the Read tool.

On any non-ok:true, Bash timeout, or JSON parse failure → STOP with a named-loop report ("hyper-plan-loop bridge failure, iter N") surfacing error verbatim (or a short parser/timeout diagnostic if no error field) plus the artifact path if present, and the re-run hint from reviewer-seat.md Mid-run Codex failure. If the artifact Read itself fails → STOP with that same named report.

Claude seat. Follow reviewer-seat.md Claude seat — spawn, Artifact, and Reply and validation with these bindings:

• artifact dir .hyperclaude/plan-reviews/, slug = the Step 1 slug;
• task = the Step 2 Task, verbatim; target = plan_path; brief = review_brief_file;
• mode plan-review, identity plan-path: "<plan_path>";
• a terminal failure is "hyper-plan-loop reviewer-seat failure, iter N" (references/failure-protocol.md).

Step 5 — Severity gate

Read the artifact body and judge by meaning, not regex. Either seat's artifact carries ### Issues with - **Blocker** — … / - **Major** — … / - **Minor** — … bullets plus ### Verdict — but classify by meaning, not by the severity word the reviewer attached: a finding blocks if it concerns plan-level correctness, wrong file paths, broken task ordering, unverifiable steps, or missing required behavior the implementer would inherit (regardless of severity label). Pure style / "consider X" / "could be slightly clearer" / vague nits do NOT block.

Claude seat: a blocking finding counts only once confirmed at its cited file:line per reviewer-seat.md The lead verifies before acting (for a plan citation, Read the ## Task block(s) the claim spans, or Grep the plan for a claimed absence — never the whole plan).

• Any blocking finding → revise (Step 6).
• No blocking findings (style/nits only, or an approving verdict) → exit the loop and report (Step 8). Non-blocking findings are reported, never gating — and they stay out of a revise round even when one runs anyway, since every edit is reviewed again next round.

Conservative branch: if severity cannot be confidently judged by meaning (no recognizable ### Issues / ### Verdict structure, truncated body, etc.) — do NOT assume "no blocking findings": instead STOP with a named-loop report ("hyper-plan-loop unparseable review, iter N") surfacing the artifact path for manual triage.

Step 6 — Revise via the live planner, then re-review

First check the cap: if the iteration counter is already at the seat's cap (10 Codex / 3 Claude), do NOT send findings or revise — go directly to Step 7 (cap reached).

The lead never Reads the plan body into its context here (that would reintroduce the token cost this skill is designed to avoid). Validation is filesystem-level only.

Send the blocking findings (Claude seat: the confirmed ones) to the still-live planner:

SendMessage({
  to: "<agent_id>",
  summary: "Revise plan from review findings",
  message: "<verbatim blocking findings + relevant ### Verdict text when it explains the required direction; instruct: first Read <the exact resolved plan path> to refresh, then re-read the files, symbols, and commands the findings cite (Read/Grep) — and for a finding that names none, the tasks it implicates and the code that would have to change — so each fix is checked against the tree rather than recalled, then revise THAT SAME path in place (Edit it, or re-Write it), fixing each finding at its source rather than rewording the sentence that triggered it, with the least plan change that removes the risk (for a rare failure, a step that stops and reports; shrinking an earlier revision's addition to the least that still meets its finding counts), and without adding a changelog of the round or a reply to the reviewer; reply with exactly 'WROTE: <that exact path>' and nothing else — no plan body, no preamble>"
})

Read the reply from that round's <result>. A SendMessage that fails → STOP per the transport-failure declaration in references/failure-protocol.md.

Do NOT re-send the task or research — the planner still holds that context.

Revise-validation — every revise reply must pass, in order: (1) accept rule (Step 3) → (2) structure ok/bad check. The single-redo budget, corrective wording, and terminal STOP are specified in references/failure-protocol.md (Revise-validation redo pipeline) — follow it verbatim. The structure check is a one-liner that prints only ok or bad:

node -e 'try{process.stdout.write(/^##\s*Task\s/m.test(require("fs").readFileSync(process.argv[1],"utf8"))?"ok":"bad")}catch{process.stdout.write("bad")}' "<resolved plan path>"

bad → corrective + terminal handling per that pipeline. On ok, increment the iteration counter and re-review in the run's seat, then loop back to Step 5. Never regenerate review_brief_file from the planner's just-revised plan (that would let the planner bless its own scope additions) — only a NEW user decision may update it.

Codex seat: re-invoke the bridge via the Bash tool with run_in_background: true and timeout: 7200000 (Step 4's reasons), reading that round's envelope from the output file the completion notification names. Same review_brief_file-gated BRIEF_FILE assignment + --review-brief token as Step 4 — per ${CLAUDE_PLUGIN_ROOT}/references/review-brief.md's two re-supply reasons (fallback survival on an auto→fresh fallback, and mid-loop updates), re-pass it on every round:

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

--plan-path is REQUIRED on every iteration including resumes (plan-review --resume auto alone is invalid). Always pass --resume auto from iteration 2 onward. Re-parse per Step 4's JSON and failure rules.

Claude seat: mint a new artifact path (Step 4 bindings) and SendMessage to reviewer_agent_id per reviewer-seat.md Later rounds; its reply runs Reply and validation.

Step 7 — Cap

Cap at 10 total reviews (Codex seat) / 3 (Claude seat).

On cap-reached, emit the named-loop report ("hyper-plan-loop revise loop") directly, carrying the seat, the iterations consumed, the residual blocking findings from the latest review, the dropped findings (as in Step 8), and the plan path left in its latest revised state: the loop ran out of rounds before the reviewer stopped flagging plan-level correctness/path/ordering/missing-behavior issues. The plan path needs manual triage.

(Cap is only reachable via Step 6, which only runs when the latest review had blocking findings — so cap-reached always means "blocking findings still open." A run whose review returns non-blocking-only at any iteration exits cleanly via Step 5 before the cap can trip.)

Step 8 — Final report

Report:

• The plan path.
• Whether the slug was reused from research artifact(s) or freshly derived.
• The Reviewer seat: line from Step 4, and review iterations consumed.
• The final review verdict.
• Residual non-blocking findings (informational, never gating).
• Claude seat: the dropped findings (reviewer-seat.md The lead verifies before acting) and that its artifacts are not resumable.
• Next step:
  • Clean exit (loop converged) → recommend: Next step: /hyperclaude:hyper-implement <plan path>.
  • Cap-reached (blocking findings still open) → do NOT recommend implementation. Direct the user to inspect the plan path and decide whether to revise manually (via /hyperclaude:hyper-plan + /hyperclaude:hyper-plan-review) or re-run /hyperclaude:hyper-plan-loop with the original task description (this skill takes a task description, not an existing plan path).

Anti-patterns

Cross-loop invariants (passing name: at spawn, re-spawning each round, seating a Claude reviewer outside the seat rule, inlining the shared contract): see ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md — Shared anti-patterns; the seat's own list is reviewer-seat.md Anti-patterns. Plan-loop-specific:

• Reading the plan body into lead context each revise round, or accepting any non-WROTE: reply as success.
• Writing <plan>-v2.md (or any) sibling files. Always overwrite the same plan path; --resume keys on it.
• Treating non-blocking findings as revise targets. Step 5 classifies by meaning — style nits, vague "consider X" suggestions, and pure prose-polish do NOT block, regardless of what severity label the reviewer attached. Only plan-level correctness / wrong paths / broken ordering / unverifiable steps / missing required behavior gate the loop.
• Restating ${CLAUDE_PLUGIN_ROOT}/references/review-brief.md's rules inside this SKILL.md instead of pointing at it; fabricating review_brief_file from the planner's plan prose; or letting a brief ask the reviewer to suppress correctness / security / data-loss findings.