Hyper Implement Loop

---
name: hyper-implement-loop
description: Use when a plan should be executed end-to-end and critic-hardened in one gesture — implement → review → fix, repeated until clean. Also when the user invokes /hyperclaude:hyper-implement-loop. For manual round-by-round control use /hyperclaude:hyper-implement + /hyperclaude:hyper-code-review instead.
---

# 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`:

```bash
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:

```bash
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:

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