hyper-implement-loop skill

hyper-implement-loop

Autonomous implement-hardening gate. Runs hyper-implement to completion first, has the diff vs main reviewed, and — on the FIRST round that carries blocking findings — spawns the fixer agent once to apply them, reusing that same agent via SendMessage on every later round until no blocking findings remain (judged semantically — see Step 4) or the cap is hit. A run whose first review is clean spawns no fixer at all. The reviewer is Codex code-review --base main 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-implement-loop <plan path>.
• User wants an autonomous implement → review → fix cycle in a single gesture.

Skip when:

• The task is one step — use /hyperclaude:hyper-implement directly.
• You want hands-on control over each implement / review round — use /hyperclaude:hyper-implement + /hyperclaude:hyper-code-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 implement-loop binding layer: it names this loop's structured per-finding reply schema, the schema-gate accept rule, the semantic finding-map 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:

• Lazy spawn: the fixer is spawned inside the first fix round (Step 5), not ahead of it. That spawn's prompt already carries round 1's blocking findings, so the spawn is itself a working round — it can mutate the tree.
• Fixer-reply ownership: there is NO canonical output file — the fixer applies edits in place and its reply is the structured findings-map schema (finding: / status: / files-changed: / verification: / notes: per cited finding). The lead avoids reading full source bodies on the normal path, but MAY run scoped git status / git diff --stat / targeted file reads for validation and failure reporting.

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

• agent_id — the fixer's id: null until the Step 5 spawn; from then on the id it returned, captured verbatim, and the address for every later fix round.
• reviewArtifacts[] — every code-review artifact path produced this run, in either seat (for Step 7).
• review_iteration — the review count, in either seat, the Step 6 cap bounds.
• seat (and its Reviewer seat: line), reviewer_agent_id, and the dropped findings — per reviewer-seat.md, set at Step 3.
• 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 3/5 bridge Bash call.

How to invoke

Invocation argument: $ARGUMENTS

$ARGUMENTS is a plan path (boundary A — a specific .hyperclaude/plans/*.md file, not a task description), resolved in Step 1.

Step 0 — Read the failure & recovery protocol

Read all three files before the loop starts: ${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 implement-loop binding: reply schema, accept rule, validation stages, named reports, transport-failure declaration).

Step 1 — Resolve the plan path

The request. Strip any seat override from $ARGUMENTS and the user's request before anything below reads them (reviewer-seat.md Decide the seat, step 1 — the seat itself is decided at Step 3). That request (under hyper-auto, its task) is the Claude seat's task text — none when only a plan path was given.

Reuse the stock hyper-implement plan-path resolution — see skills/hyper-implement/SKILL.md Step 1; do not duplicate the rule text. In brief:

1. If $ARGUMENTS is non-empty, treat it as a plan path and use it.
2. Else, find the most recent plan via ls -1t .hyperclaude/plans/*.md 2>/dev/null | head -1.
3. If nothing found, tell the user "No plan file found" and STOP.

No feature slug. The code-review slug in this skill is release-level (vs-main), not feature-level — it derives from the diff target, not the plan filename. The final report will reference the code-review artifact path(s) only; do not derive or track a feature slug here.

Compose the review brief (or record null). Compose per ${CLAUDE_PLUGIN_ROOT}/references/review-brief.md. The admissible source here is the user's own request text and decisions the user explicitly approved in this conversation — the resolved plan is not a source (it is planner-authored, not user-authored). Record the resulting scratchpad path as review_brief_file, or null if no admissible source exists — in which case the flag is omitted on every round.

Step 2 — Run hyper-implement to completion (boundary A)

The fixer is not spawned yet — it is spawned lazily in Step 5, on the first round that has blocking findings. Spawning earlier buys no context: hyper-implement builds with its own fresh subagents the fixer never observes, and a run that converges on the first review needs no fixer at all.

Invoke the existing hyper-implement skill on the resolved plan path.

Nested-review boundary: skills/hyper-implement/SKILL.md Step 4 ends with an optional final step: run /hyperclaude:hyper-code-review. Under hyper-implement-loop, the lead MUST NOT perform that optional /hyperclaude:hyper-code-review bullet — it is suppressed for this run. Step 3 below is the single authoritative first review of the full diff.

If hyper-implement fails or aborts (no usable implementation): nothing has been spawned yet, so there is no agent state to account for — STOP, surfacing the hyper-implement failure verbatim. The partial working tree is left as-is for manual triage.

The loop begins AFTER hyper-implement finishes its task loop + final acceptance (smoke/tests), with the optional code-review bullet suppressed.

Step 3 — Code-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 — here, once hyper-implement has finished, so the reading is current. Either seat reviews the effective worktree vs main — commits since main plus staged, unstaged, and untracked changes, read from the live tree — so the fixer's uncommitted edits are in scope every round and no per-round commit is needed.

Codex seat. --base main names that target on every round (never --commit <sha>).

Invoke via the Bash tool with timeout: 600000. 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" code-review --base main [--review-brief "$(cat "$BRIEF_FILE")"]

Parse the bridge's single stdout JSON envelope per ${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md (envelope shape + strict-parse rule).

On ok:true: Read the artifact at path with the Read tool; capture resumeStatus; append path to a reviewArtifacts[] list (for Step 7).

On any non-ok:true, Bash timeout, or JSON parse failure → STOP with a named-loop report ("hyper-implement-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, as this loop's reviewer-seat.md Mid-run Codex failure line: "The implementation is committed on this branch (any uncommitted fix edits stay in the tree — git status --short); do not re-run this loop or hyper-auto (it would re-execute the plan). Review the branch instead: /hyperclaude:hyper-code-review once the Codex budget allows, or ask for an adversarial Claude review."

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

• artifact dir .hyperclaude/code-reviews/, slug vs-main;
• task = the Step 1 request; brief = review_brief_file;
• target = the effective worktree vs main (above);
• mode code-review, identity base-ref: "main";
• a terminal failure is "hyper-implement-loop reviewer-seat failure, iter N" (references/failure-protocol.md).

End the turn. Until the reply lands — this round and every later one — leave the working tree alone: the reviewer reads it live. On ok, Read the artifact, append its path to reviewArtifacts[], and go to Step 4.

Step 4 — Severity gate

Read the artifact body and judge by meaning, not regex. Either seat's artifact carries ### Findings (Blocker/Major/Minor bullets) then ### Verdict — but still classify by meaning, not by the severity label the reviewer assigned: a finding blocks if it concerns correctness, data loss, security, a broken build/tests, a regression, or missing required behavior. Pure style / nits / opinions do NOT block, and neither does a finding labelled Minor about wording nothing executes — a comment, docstring, doc, or message text (the one place the label counts).

Claude seat: a blocking finding counts only once confirmed at its cited file:line per reviewer-seat.md The lead verifies before acting (Grep for a claimed absence).

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

Conservative branch: if the body cannot be confidently judged by meaning (unparseable, truncated, or no recognizable structure) → STOP with a named-loop report ("hyper-implement-loop unparseable review, iter N") surfacing the artifact path for manual triage.

Step 5 — Fix via the fixer, then re-review

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

The round's blocking findings (Claude seat: the confirmed ones) go to the fixer.

First blocking round (agent_id is null) — spawn the fixer. 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:fixer",
  prompt: "<the contract string assembled from the bullets below>"
})

The prompt string MUST contain:

• Role framing — you are the fixer for this hyper-implement-loop run; your job is to apply code-review findings to the working tree in targeted, minimal fixes.
• This round's findings — the verbatim blocking findings, the relevant verdict direction, and the code-review artifact path.
• Reply format — for EVERY cited finding emit its own finding: / status: / files-changed: / verification: / notes: block (status exactly fixed or not-applicable; notes: required when not-applicable), delivered as your FINAL TEXT. No diff dump, no patch block, no source-body echo. This applies identically to every later round's reply.
• Constraints echo — fix only the findings cited in each round, with no opportunistic refactors; leave the tree uncommitted and unpushed; don't invoke codex or scripts/codex-bridge.mjs; re-read the current diff/files each round before applying any fix (context may be stale across rounds).
• State that the fixer stays live between rounds, will receive further review findings in later turns, and must retain its full context across rounds.

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

Failure handling — hyper-implement has already committed the implementation by this point, so both branches are side-effect-aware STOPs per the transport-failure declaration in references/failure-protocol.md:

• Spawn fails outright → nothing ran, so this run produced no fix edits. STOP per that declaration.
• Spawn returns no usable agent_id, or fails ambiguously → the spawn prompt carried this round's findings, so the fixer may already have applied them. Treat the tree as potentially mutated. STOP per that same declaration.

Later rounds (agent_id set) — reuse the live fixer. Send the round's blocking findings to the captured agent_id:

SendMessage({
  to: "<agent_id>",
  summary: "Fix blocking review findings",
  message: "<verbatim blocking findings + relevant verdict direction + the code-review artifact path; instruct: re-read current diff/files, fix ONLY these findings, run relevant verification, reply with the structured per-finding schema as your final text>"
})

Reading the reply — round 1's reply is the spawn task's <result>; every later round's is that round's <result>. A SendMessage to the fixer that fails → STOP per the transport-failure declaration in references/failure-protocol.md.

Do NOT re-send the plan or task — the fixer still holds that context.

Fix-validation pipeline (per references/failure-protocol.md — Fix-validation redo pipeline): (1) structured-schema reply gate (schema requirements in that file's Binding declarations) → (2) semantic finding-map check (every cited blocking finding maps to status: fixed OR status: not-applicable with a non-empty notes: reason). No git-state / no-op gate. Each stage has its OWN one-redo budget — a schema-gate failure escalates (after its one corrective) to "hyper-implement-loop reply-contract failure"; a semantic-finding-map failure escalates (after its own one corrective redo, which re-enters the pipeline from the schema gate) to "hyper-implement-loop fixer format, iter N". Follow that file's corrective and redo-pipeline sections verbatim.

On pass, increment the iteration counter and re-review in the run's seat, append the artifact path to reviewArtifacts[], then loop back to Step 4.

Codex seat: re-invoke via the Bash tool with timeout: 600000. Same review_brief_file-gated BRIEF_FILE assignment + --review-brief token as Step 3 — 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" code-review --base main --resume auto [--review-brief "$(cat "$BRIEF_FILE")"]

Always pass --resume auto from iteration 2 onward; --base main is REQUIRED on every iteration; --commit <sha> is FORBIDDEN. Re-parse per Step 3's strict-JSON and failure rules; a resume-failed/fallback resumeStatus is still a valid round — record it for Step 7.

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

Step 6 — Cap

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

On cap-reached with blocking findings still open, emit the named-loop report ("hyper-implement-loop fix loop") carrying the seat, the iterations consumed, the residual blocking findings from the latest review, the dropped findings (as in Step 7), the working tree left in the fixer's latest state (fix edits uncommitted), and all reviewArtifacts[] paths.

Step 7 — Final report

Reached only on Step 4's clean (no-blocking) exit — cap-reached and failure STOPs emit their own reports and never arrive here.

Convergence commit. The lead commits its uncommitted fix edits once on the current feature branch — the fixer never commits (invariant). This only has anything to stage when a fixer actually ran; a clean first review spawned none, and the SKIP: no fix edits to commit branch below covers that case. The fixer is at rest (idle since its last reply) and the lead sends it nothing during the git ops, so it performs no concurrent edits. git add -A carries the same scoping as hyper-implement's per-task commit (clean-tree preflight + gitignored .hyperclaude/); if autonomous verification left unrelated untracked files they ride in too — same exposure as hyper-implement, so eyeball the diff before pushing. This is the loop's ONLY commit; its subject names the seat:

git add -A
if git diff --cached --quiet; then
  echo "SKIP: no fix edits to commit"
else
  git commit -m "fix(review): apply <Codex code-review | Claude reviewer-seat> findings" && git rev-parse --short HEAD
fi

Report the actual git outcome (never assume success): the commit SHA + clean tree on success; the skip note if nothing was staged; or — if git commit failed (pre-commit hook, signing, author config) — surface its stderr + git status --short and do NOT claim the branch is ready to push. Then report:

• All reviewArtifacts[] paths (not just the latest; NO plan/slug — release-level slug only).
• The Reviewer seat: line from Step 3, and review iterations consumed.
• The final review verdict.
• Residual non-blocking findings (informational, never gating).
• When residual findings ask to remove or simplify code (over-engineering, dead code, duplication), list them apart from the rest and recommend Claude Code's built-in /simplify main...HEAD; when a review brief exists, name its requirements as what /simplify must not change. A recommendation only, never run here: simplification stays a human call, and its edits would land after the last review.
• Claude seat: the dropped findings (reviewer-seat.md The lead verifies before acting) and that its artifacts are not resumable.
• Any resume-failed / fallback rounds noted.
• Branch / working-tree state: hyper-implement committed each task on the feature branch it created/used (hyper/<slug> when started from main/master); on clean convergence the lead committed the fixer's fix edits in one fix(review): commit on top (working tree now clean — or no fix edits to commit). Nothing was pushed. Next step: push the branch when ready.
• Recommend /hyperclaude:hyper-recap as an optional follow-up for a human-readable write-up of this cycle — a recommendation only, never auto-run it here.

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. Full list also in references/failure-protocol.md — Anti-patterns (implement-loop specific). Implement-loop-specific:

• Committing or pushing from the fixer, or letting the fixer invoke codex or scripts/codex-bridge.mjs.
• Using --commit <sha> as the diff target, or omitting --base main on any iteration (Codex seat). --base main is the fixed target for all code-review invocations.
• Reasserting a git-state / no-op gate. A stuck or no-change fixer is bounded by the Step 6 cap — a separate no-op detection path is an anti-pattern.
• Fabricating review_brief_file from plan prose; or letting a brief ask the reviewer to suppress correctness / security / data-loss findings. Also: composing --background in this loop — the review brief is this loop's context channel, --background is never composed here.