Hyper Plan Loop

hyper-plan-loop

Autonomous plan-hardening gate. Creates a per-run team, spawns the planner agent as a persistent teammate, writes its plan to .hyperclaude/plans/-.md, runs Codex plan-review through the bridge, and revises via the still-live planner until Codex returns no blocking findings (judged by meaning, not Codex severity labels) or the cap is hit. The planner is spawned once; every revise round reuses its retained context via SendMessage. The reviewer is always the Codex bridge, never a teammate — this preserves the "Claude builds, Codex reviews" invariant.

When to use

• User typed /hyperclaude:hyper-plan-loop .
• 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.
• The experimental agent-teams feature is unavailable (this skill stops with a documented fallback message — see Step 2).

Failure & recovery protocol — read first

${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md carries the shared cross-loop protocol — team contract shapes (§A), unsolicited-message protocol skeleton (§B), teardown procedure (§C), shared anti-patterns (§D), abstract request-id state machine (§E). references/failure-protocol.md (sibling of this file) is the plan-loop binding layer: it names this loop's reply-token shape (WROTE: ), accept regex, post-acceptance file/structure validation, and plan-loop-specific anti-patterns. Step 0 makes Reading BOTH mandatory before the loop starts.

Agent-teams tool contract

See ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §F1 + §A for the Agent/SendMessage argument shapes and idle-notification semantics (a payload-less wake — the loop-bound WROTE: reply arrives only via planner SendMessage, else the lead falls back to a corrective round-trip). Loop-specific bindings:

• Plan ownership: the planner writes the canonical plan file itself via caller-directed write-file mode (its Step 3 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, and only Reads the body for human-facing failure diagnostics. Every write-file-mode reply (initial, retry, revise redo) is gated to WROTE: -only (Step 4 anchored gate). Unsolicited planner messages follow the lead-side protocol (references/failure-protocol.md §2) — prompt-only idle discipline is insufficient.

Planner request id. Every lead→planner solicitation carries a per-run, lead-owned, monotonically increasing integer id. The lead is the SOLE id source — the planner only echoes it. The counter increments on EVERY solicitation: spawn = 1, each Step 7 revise = +1, AND every §1/§3 corrective redo — anchored-gate corrective AND file-check corrective alike — gets its OWN new id (a corrective is a fresh solicitation; reusing the prior id reintroduces the blind spot). The shutdown_request object message is EXEMPT (no id).

The lead must retain the following run-state across turns and never conflate these fields:

• plan_path — the resolved canonical plan path from Step 1.
• teammate_name — "planner" (the spawn name); the bare-name handle for every lead→planner send, per the §A send-resolution procedure.

[DEGRADE] - teammate_id — the opaque agent_id captured at Step 3 spawn (§A-DEGRADE D0; never parsed); the FALLBACK handle for the first degraded send. Degrade-only — unused on the live-mailbox main path. [DEGRADE] - resolved_handle — the degraded handle (teammate_name or teammate_id) that won the first degraded send; null until D1 resolves it. Degrade-only — unused on the live-mailbox main path.

• awaiting_reply, request_id_counter, expected_request_id, solicit_sent_at, review_iteration — these are the cross-loop state-machine fields. Lifecycle and semantics (mint protocol, MESSAGE ACCEPTED / POST-ACCEPTANCE VALIDATION ACCEPTED acceptance stages, Phase 1 / Phase 2 routing, stale-recovery) are defined in ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §E (single source of truth); this loop binds to them by name.

Mint protocol, lifecycle, and phase classification: see ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §E. The references/failure-protocol.md (sibling) carries the plan-loop binding declarations (reply-token shape WROTE: , exact-path accept regex, file/structure post-acceptance validation).

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

See ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §F2 for the two-file read requirement. Both loop-protocol.md (shared §A–§E) AND references/failure-protocol.md (sibling, plan-loop binding) are mandatory before spawning; this loop's local file binds the WROTE: reply-token shape.

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 -).
2. 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 3.
3. Resolve the plan path:

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

Base path: .hyperclaude/plans/-.md. If it exists, append -2, -3, … until free.

Step 2 — Confirm agent-teams availability

See ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §F3 for the probe + documented stop message; ` = /hyperclaude:hyper-plan + /hyperclaude:hyper-plan-review`.

[ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" = "1" ]

Initialize and record the following run-state fields (the Step 3 spawn will mint id 1): request_id_counter = 0, expected_request_id = null, awaiting_reply = false, solicit_sent_at = null.

Failure handling (both cases emit the §F3 documented message with ` = /hyperclaude:hyper-plan + /hyperclaude:hyper-plan-review`):

• Env var unset → STOP with the §F3 message (fallback bound above). No teardown (nothing was created).
• Step 3 spawn fails → STOP with the §F3 message (fallback bound above). No teardown (team never formed).

Step 3 — Spawn the planner teammate

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

Agent({
  subagent_type: "hyperclaude:planner",
  name: "planner",
  prompt: ""
})

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. Do not make the planner re-read them.
• Output format — a multi-task plan with ## Task N: 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: 1 and NOTHING else — no plan body, no summary of changes, no preamble. (The spawn mints request id 1: the lead sets request_id_counter = 1, expected_request_id = 1, awaiting_reply = true, and immediately before the Agent-spawn call captures solicit_sent_at via a Bash date -u +%FT%TZ; the planner must echo that id verbatim.)
• Reply transport (MANDATORY) — that WROTE: reply MUST be delivered by calling SendMessage({ to: "team-lead", summary: "Plan written request 1", message: "WROTE: 1 " }). Plain assistant text is NOT visible to the lead on a live-mailbox host, and going idle only emits a payload-less idle notification — so if you merely print WROTE: and idle WITHOUT the SendMessage call, the lead never receives the confirmation and the loop stalls until a corrective round-trip. Call SendMessage first, then idle. Every later solicitation carries its own id; the planner must echo THAT id verbatim in its reply (e.g. WROTE: 2 for id 2), and the summary echoes request for human mailbox debugging (the message body stays authoritative). This applies identically to every later revise-round reply.

[DEGRADE] Exception (degraded host only): if SendMessage is unavailable on your host (degraded), emit that same WROTE: line as your FINAL ASSISTANT TEXT — the lead reads it from your task-completion result per §A-DEGRADE D2.

• Idle / no-resend discipline — after replying WROTE: , go idle and wait; do NOT resend, re-announce, or nag. The lead will next contact you only via SendMessage carrying revise findings or a shutdown_request, and may take several minutes running Codex review between turns (this is normal). Never re-emit a prior reply.
• State that the planner stays alive as a teammate, will receive Codex feedback in later turns, and must retain its full planning context.

After the Agent(...) call — capture and validate handles:

• Record teammate_name = "planner" (the bare-name handle for all lead→planner sends, per §A R1).

[DEGRADE] - Capture the returned agent_id VERBATIM/OPAQUELY into run-state teammate_id (§A-DEGRADE D0 — never parse the @/suffix); this is the FALLBACK handle for the first degraded send. [DEGRADE] - Set resolved_handle = null (no degraded lead→planner send has been made yet; degrade-only field).

• Note: the Agent spawn is NOT a lead→planner SendMessage. The planner's spawn-time WROTE: 1 reply is a SendMessage({ to: "team-lead", … }) — that exercises teammate→lead routing, NOT lead→planner routing. The FIRST lead→planner send is the Step 7 revise (on a run where the initial plan is accepted cleanly) OR an initial §1 corrective sent via Step 4 when the WROTE: reply is malformed or missing.

[DEGRADE] - Degrade detection (conditions (1)/(2)/(3) per §A-DEGRADE): [DEGRADE] - Condition (1): the first bare-name send FAILED and teammate_id was not captured at spawn (D0 captured nothing — no fallback handle available) → record plan_path from Step 1 (planner may have written it — the spawn prompted the write) and STOP with the fallback noting that path for manual inspection. STOP WITHOUT teardown (no addressable teammate — §A-DEGRADE D3 no-usable-handle exception). This condition is reached ONLY after a bare-name send has actually failed, NOT at spawn time. [DEGRADE] - Condition (2): the teammate replies via its task-completion result (SendMessage unavailable on this host) → this is §A-DEGRADE D2 driving; do NOT STOP. Read the WROTE: 1 reply from the spawn task result (D2 case (i)) and apply the SAME Step 4 anchored gate + file check; then continue the loop (later rounds use D2 case (ii) — reply read from the D1 teammate_id SendMessage task result). Reference §A-DEGRADE for the driving algorithm. [DEGRADE] - Condition (3): first lead→planner send fails on BOTH bare teammate_name AND teammate_id (D1 fallback exhausted) → record plan_path and STOP honestly; the planner may have written the plan at spawn so note that path for manual inspection. STOP WITHOUT teardown (no addressable teammate).

Step 4 — Confirm the planner wrote the plan

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

Anchored reply gate (id-first summary) — applies to EVERY planner reply in write-file mode (the initial write, any retry, and every Step 7 revise redo). Classification is id-first, phase-first:

1. First operation: parse the leading WROTE: token from the trimmed reply and capture ``. Everything after that token is the path payload.
2. Classify by awaiting_reply FIRST, then by id, BEFORE any exact-path or no-prose check.

• Not awaiting (awaiting_reply == false): a WROTE: with id \s*$ (path = entire remaining string, verbatim) plus no-prose rule — on pass → MESSAGE ACCEPTED (clear expected_request_id, awaiting_reply, and solicit_sent_at); a future id (reqid > expected_request_id) is a protocol violation → Step 8 teardown then STOP.

1. After MESSAGE ACCEPTED, run the file/structure check (= PLAN VALIDATION ACCEPTED stage). On any body echo, added prose, preamble, or a different path at the matching-id step → §1 corrective + escalation.

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

[ -s "" ]

If missing or empty → apply the file-check corrective + escalation in references/failure-protocol.md §1.

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. The id, not a new path, is the disambiguator — a stale round-N WROTE: is byte-identical on path but distinguishable by id.

Full two-phase state machine, the two acceptance stages, and the stale-recovery sub-step are authoritative in references/failure-protocol.md §6 — do not duplicate the pseudo-code here.

Step 4a — Unsolicited planner messages

See ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §F4 for unsolicited-message handling (§E two-phase classification is the authoritative router; §B governs genuinely-unsolicited non-WROTE: traffic). This loop's anchored reply-token is WROTE: ; the local binding: reply-token shape + accept rule in references/failure-protocol.md Binding declarations; corrective/recovery in §1; unsolicited-message handling in §2 (which points at shared §B).

Step 5 — Plan-review iteration 1 (fresh)

Iteration counting: the fresh review here is iteration 1. The Step 8 cap is 10 total reviews (iter 1 fresh + at most 9 resumed revise rounds). See ${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md §E for the review_iteration-vs-request_id_counter independence rule.

Invoke via the Bash tool with timeout: 600000:

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" plan-review --plan-path ""

Parse the single-line JSON. On ok:true, read the artifact at path with the Read tool.

On any non-ok:true, Bash timeout, or JSON parse failure → Step 8 teardown, then 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. If the artifact Read itself fails → Step 8 teardown, then STOP.

Step 6 — Severity gate

Read the artifact body and judge by meaning, not regex. The plan-review template emits ### Issues with - **Blocker** — … / - **Major** — … / - **Minor** — … bullets plus ### Verdict — but classify by meaning, not by the severity word Codex attached: a finding blocks if it concerns **plan-level correctness, wrong file p

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zeikar
• Source: zeikar/hyperclaude
• License: MIT
• Homepage: http://zeikar.dev/hyperclaude/

Install and usage instructions live in the source repository linked above.