hyper-docs-loop

Autonomous docs-hardening gate. Has the docs target reviewed and — on the FIRST round that carries blocking ### Findings — spawns the documenter 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 documenter at all. The reviewer is Codex docs-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-docs-loop [target].
• User wants an autonomous docs-review → fix cycle in a single gesture.

Skip when:

• A single doc edit is enough — edit it directly or use /hyperclaude:hyper-docs-sync for code-change-driven sync.
• You want hands-on control over each review / fix round — use /hyperclaude:hyper-docs-review + manual edits.

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 docs-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 documenter 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 docs tree.
• Documenter-reply ownership: there is NO canonical output file — the documenter 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 doc 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:

• docs_target — the bridge argv tokens resolved in Step 1, reused verbatim on every iteration.
• agent_id — the documenter'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 docs-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.

How to invoke

Invocation argument: $ARGUMENTS

$ARGUMENTS is a docs target (optional path tokens; the loop mirrors hyper-docs-review's target grammar), 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 docs-loop binding: reply schema, accept rule, validation stages, named reports, transport-failure declaration).

Step 1 — Resolve the docs target

Strip any seat override from $ARGUMENTS first (reviewer-seat.md Decide the seat, step 1 — the seat itself is decided at Step 3), then apply the table below to what remains. Classify each token via Bash — [ -f "<path>" ] (existing file → --docs-path) vs [ -d "<path>" ] (existing directory → --docs-dir); a token that is neither → STOP. Record docs_target as the bridge argv tokens:

docs_target is reused verbatim on every iteration in Step 3 and Step 5 — never change it mid-run.

Directory-target note. Per docs-review's established contract, --docs-dir <p> reviews only the top-level .md files directly under <p> (not recursive). This is intentional. The loop inherits that scope; if the user wants nested docs reviewed, they invoke the loop once per subdirectory or against an explicit file path of any type.

Step 2 — (Reserved)

This skill has no pre-loop sync step. The loop targets accuracy of docs as they are; if the user wants to first sync docs to recent code changes, they invoke /hyperclaude:hyper-docs-sync separately before this skill. Keeping the loop pure (review ↔ fix only) avoids conflating the code-diff-driven sync flow with the docs-target-driven review flow.

Step 3 — Docs-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.

Codex seat. Invoke via the Bash tool with timeout: 600000, passing the docs_target argv tokens from Step 1:

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" docs-review <docs_target argv>
# e.g. ... docs-review --docs-dir docs/
# or   ... docs-review --docs-path docs/architecture.md

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

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

• artifact dir .hyperclaude/docs-reviews/, slug = the slug field of node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" docs-review <docs_target argv> --dry-run (no Codex spawn);
• task, brief = none (the target is the request);
• target = each --docs-path file, or the top-level *.md files of the --docs-dir (Step 1's directory-target note);
• mode docs-review, identity docs-target from docs_target (Artifact);
• a terminal failure is "hyper-docs-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 docs alone: the reviewer reads them 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. The artifact carries ### Findings (Blocker/Major/Minor bullets) and ### Verdict, plus — when present — ### Gaps, ### Broken Or Suspect Links, and ### Cross-Doc Inconsistencies.

Only `### Findings` is gating. Bullets in ### Gaps / ### Broken Or Suspect Links / ### Cross-Doc Inconsistencies are reported in the final summary (Step 7) but do NOT drive fix rounds — those sections frequently need human judgment (which gap is worth filling? is this link genuinely broken or just suspicious?) that the loop should not auto-resolve. The user runs another pass manually when ready.

Within ### Findings, classify by meaning: a finding blocks if it concerns accuracy / drift / actively misleading claims that would cause a reader to do the wrong thing (regardless of which severity word the reviewer attached). Pure prose-polish nits do NOT block. Redundancy-only findings (duplicated-but-consistent claims) do NOT block either — collapsing repeated content needs human judgment; report them in Step 7 like the non-gating sections.

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

• Any blocking ### Findings item → fix (Step 5).
• No blocking ### Findings (Findings absent, or Findings contains only style/nits/redundancy, or verdict is approving) → exit the loop and report (Step 7). Non-blocking findings + the three non-gating sections are reported, never gating.

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

Step 5 — Fix via the documenter, 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 bullets (Claude seat: the confirmed ones) go to the documenter.

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

The prompt string MUST contain:

• Role framing — you are the documenter for this hyper-docs-loop run; your job is to apply docs-review findings to the cited doc files in targeted, minimal edits. This dispatch is NOT hyper-docs-sync's per-doc UPDATE/CREATE mode — it is the loop's structured-findings mode, and the contract below is authoritative for this dispatch.
• This round's findings — the verbatim blocking ### Findings bullets (with their Stale claim / Code evidence / Recommended edit sub-bullets) and the docs-review artifact path.
• Reply format — for EVERY cited finding emit its own finding: / status: / files-changed: (comma-separated doc paths, or none) / verification: (what you re-read to confirm, or n/a) / notes: block, each field on its own line (status exactly fixed or not-applicable; notes: required when not-applicable), delivered as your FINAL TEXT. No diff dump, no patch block, no verbatim source-body echo. End with a one-line summary of the findings processed this round. This applies identically to every later round's reply.
• Constraints echo — fix ONLY the findings explicitly cited in each round; no opportunistic prose polish; revise the sentence a finding cites rather than appending one beside it; no edits to uncited docs; edit DOCUMENTATION files only (no source code, tests, scripts, or config edits to make a doc claim "true" — if the doc disagrees with code, the doc is what changes, or report not-applicable if the doc was actually right); NEVER commit or push; NEVER invoke codex or scripts/codex-bridge.mjs; re-read the cited docs each round before applying any fix (context may be stale across rounds).
• State that the documenter 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 — this loop commits nothing, so any doc edits live only in the working tree; both branches are STOPs per the transport-failure declaration in references/failure-protocol.md:

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

Later rounds (`agent_id` set) — reuse the live documenter. Send the round's blocking ### Findings bullets to the captured agent_id:

SendMessage({
  to: "<agent_id>",
  summary: "Fix blocking docs findings",
  message: "<verbatim blocking ### Findings bullets (with their Stale claim / Code evidence / Recommended edit sub-bullets) + the docs-review artifact path; instruct: re-read the cited doc files, apply ONLY these fixes, 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 documenter that fails → STOP per the transport-failure declaration in references/failure-protocol.md.

Do NOT re-send context the documenter still holds.

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-docs-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-docs-loop documenter 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, passing the SAME docs_target argv tokens:

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-bridge.mjs" docs-review <docs_target argv> --resume auto

Always pass --resume auto from iteration 2 onward; docs_target is REQUIRED on every iteration (the bridge requires --docs-path or --docs-dir even on resume). 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-docs-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 docs tree left in the documenter's latest state (doc 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. Report:

• All reviewArtifacts[] paths.
• The Reviewer seat: line from Step 3, and review iterations consumed.
• The final review verdict.
• Residual non-blocking ### Findings items (informational).
• All bullets from ### Gaps, ### Broken Or Suspect Links, ### Cross-Doc Inconsistencies, when present (informational — these sections are non-gating; the user resolves them manually).
• 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.
• Working-tree state: any documenter edits — if fix rounds ran — are left uncommitted. Nothing was pushed. Next step: review the diff and commit it when ready.

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 (docs-loop specific). Docs-loop-specific:

• Committing or pushing from the documenter, or letting the documenter invoke codex or scripts/codex-bridge.mjs.
• Letting the documenter edit source code, tests, scripts, or config to make a doc claim "true". The doc is what changes; if the doc was actually right, the documenter reports status: not-applicable with a notes: reason.
• Changing docs_target mid-run. The same --docs-path / --docs-dir argv tokens are REQUIRED on every iteration, including Codex resumes — the bridge enforces this.
• Auto-fixing items from ### Gaps, ### Broken Or Suspect Links, or ### Cross-Doc Inconsistencies. Only ### Findings drives fix rounds; the other sections need human judgment and are reported in Step 7 only.