# Hyper Sprint > Run a full "implement + test + verify a batch of change requests to zero bugs" sprint in one session as a thin orchestrator that delegates implementation to sub-agents (routed by task difficulty, isolated in worktrees for parallel work) and gates completion on an independent BLIND validation by the best model. Use when handed a list of changes/issues (a PDF, ticket list, or spec) to implement, test, and prove working end-to-end — stop rule "a blind best-model hunt finds no bugs + a proof artifact (a Markdown sprint report by default; recorded demo optional)". Repo-agnostic; reads a root `.hyper-sprint/config.md` for repo facts; front-loads app/browser readiness so verification never stalls. - Skill: `agentiapt/hyper-sprint` (Agent Skill, multi-file: 14 files) - Install (CLI): `npx skillmds@latest add agentiapt/hyper-sprint` - Raw SKILL.md: https://api.skillmd.com/api/skills/agentiapt/hyper-sprint/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: AgentiaPT (https://skillmd.com/u/agentiapt) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agentiapt/hyper-sprint --- # Hyper Sprint > ## ⚠️ THE MAIN AGENT IS AN ORCHESTRATOR, NOT A WORKER > > It plans, delegates, integrates, and gates — and does **nothing else** in the main > context. It NEVER does bulk implementation, debugging, browser-driving, screenshotting, > or diagnostic/verification scripting inline. Every hands-on task → a sub-agent that > returns a compact verdict. > > **The objective is lowest total $/token cost over the whole sprint — turn count is only a > proxy.** Every turn re-reads the ENTIRE cached hub context, so hub cost ≈ **(standing > context size) × (number of turns)**. A long, complex sprint driving a big issue list will > *necessarily* run more turns — that's fine and expected. What must stay bounded is the > **per-turn hub cost**: keep the standing context **small AND FLAT for the whole session**, > not just thin at the start. A payload pinned early (a screenshot, a diff, a big doc) is > re-charged on *every later turn* for the rest of the run, so unchecked growth compounds > silently into the bill. Concrete anchor: one sprint's hub was **$59.74 across 72M > cache-read tokens over 375 turns**, and cache-reads were **94% of that sprint's 150M total > tokens** — the fix was a thin *and flat* hub, not fewer turns. > > **≤50 main-loop turns is a heuristic for a normal-size sprint, not a hard ceiling** — for a > genuinely large issue list, turns scale with cluster count. Measure and checkpoint real > spend mid-sprint (`assets/sprint-cost.py --audit`, principle 9) and course-correct on > **cost/tokens**, not on hitting a turn number. When a worker dies (session/rate limit), > spawn a **replacement** sub-agent — never absorb its work into the hub. (The 375-turn > sprint above blew its budget doing exactly that: a worker died mid-task and the > orchestrator inline-wrote ~12 diagnostic/browser-driver scripts instead of delegating.) > > **Trip-wire:** more than 2 consecutive inline diagnostic/driver round-trips on one > question = a missed delegation. Stop and delegate the whole investigation. Deliver a batch of changes to a **verified zero-bug** state in one session, cheaply. This skill replaces an ad-hoc "implement everything and test it" prompt. ## Orchestration model (full detail: `references/orchestration.md`) **Orchestrator, not worker —** run as a **thin orchestrator** on the best model — plan, delegate, integrate, judge; **never do bulk implementation in the main context** (it burns the premium context and biases the final gate). Three separate roles: - **Orchestrator** (main loop, best model): reads *recon summaries + worker results*, not raw source; partitions work; routes each worker's model/effort/isolation; drives the gate. - **Workers** (sub-agents, model routed to difficulty): one objective + exclusive file set each; disjoint clusters run in parallel **git worktrees** (partition-by-module → clean merges); orchestrator merges sequentially, suite green between merges. - **Validators** (**best model, max effort, BLIND**): own the stop gate — see only the spec + code at HEAD, never the sprint history (*Stop rule*). Default shape is **hybrid**: a small-context verifier per change-request/cluster, plus one or two broad cross-cutting hunters (*verify-each + hunt-across* — see *Stop rule*). ## Operating principles (the economy rules) 1. **Readiness before features (hard gate) — inline it when the env is pre-provisioned, sub-agent it when bring-up is uncertain.** When a setup script / container image / prebuilt artifact already provisions the environment, the fast boot+smoke gate is cheap and deterministic — the **orchestrator runs it itself**, inline, and moves on; spawning a sub-agent for a 20-line, already-solved probe just adds a round-trip. Spawn a **dedicated readiness sub-agent** only when bring-up is genuinely uncertain (undeclared deps, a first boot on this box, an unfamiliar stack) — its build + dep-provision + boot + smoke-test trial-and-error is then pure noise to the hub, so it must return only a compact verdict (`ready | blocked` + reason) and the **path to a persisted entrypoint file** — the ONE boot+drive command plus the baseline (passing count, known-failing tests) and any gotchas, which workers/validators reuse verbatim. Either way, it must **smoke-test every surface the sprint will verify** (e.g. the primary view, a secondary mode, a dialog), not just that it boots once — latent harness bugs surface at minute 5, not hour 2, if you only check the happy path. The blocked-CDN SPA-boot recipe is one example (`references/ agent-profiles.md`). Orchestrator **hard-gates on `blocked`**; if the app can't run here, agree the fallback (unit-only + manual checklist) with the user. 2. **Recon in parallel, once — deposit detail to files, return only a pointer.** A sub-agent's return value is pinned in the orchestrator's context and cache-read *every later turn*, so a recon agent must **write its full line-anchored map (`file:line` + what changes) to a file** and **return only a compact index** (subsystem → files → one-line summary → map path). The orchestrator partitions from the index (pointers, not payloads); each **worker reads its own map file directly** into its isolated context. Put the shared notes at an **absolute path outside any worktree** (a session scratch dir) so worktree workers can read them, and pass that path in. 3. **Orchestrator, not worker — hub hygiene: payloads to disk, pointers + verdicts in the hub (HARD RULE).** The orchestrator must **never** read a worker's diff, a screenshot, or any large doc into the main loop — it trusts the worker's pasted test-summary + one-line verdict, and re-drives only **by exception**, via a cheap sub-agent that returns a bare pass/fail (not the raw artifact). Frame-checks and one-off lookups (a pricing page, a doc for one config flag, a single number buried in a giant reference) are **delegated**, never fetched/read directly in the hub. **Screenshots are the single worst payload — treat "no images in the hub" as an absolute.** A viewed screenshot is ~10–37K tokens, is **un-evictable** (compaction is the only thing that sheds it, and context-editing/`clear_tool_uses` does not cover image blocks), and is re-read on **every** later turn. The blind verifiers/hunters already *look* at every proof state (principle 8) and return a one-line frame-check verdict — the hub reads the **verdict, never the pixels**; if the hub genuinely needs its own visual check, spawn a throwaway "look at this PNG → reply pass/fail + one sentence" sub-agent so the image lives and dies in an isolated window. *(Measured example: in one sprint the orchestrator was **65% of total spend** and **95% of its tokens were cache-reads**; **10 screenshots the hub looked at were 31% of its cache-read and ~46% of its standing context** — more than any other single bucket. This is generally the single biggest cost lever; it is not specific to that run.)* Enforceable checklist, the CLI-vs-SDK context levers, and the re-drive-by-exception recipe: `references/hub-hygiene.md` + `references/context-economy.md`. 4. **Cluster by file-locality, not by ticket number.** Group changes that touch the same files into one work item so edits don't collide and each item is independently testable — and so clusters with **disjoint file sets** can run as parallel workers in separate worktrees. Track them with the task tool; keep the list live. 5. **Test-as-you-go, never batch-at-end.** Each change lands with its unit and/or e2e test in the *same* step; a fix with no test is not done. Re-run the suite after **every** fix (a fix can regress the thing it fixed). **Workers receive the acceptance Verify verbatim** (the exact acceptance text for their change requests, not a paraphrase) and the **cluster-boundary check asserts against that same text** before merge — a paraphrase drifting from the spec is exactly what surfaces as an integration-time surprise later. 6. **Orchestrator, not worker — one canonical verify command; trust green, re-drive by exception.** The biggest main-loop turn-inflator is the orchestrator re-verifying every worker by hand. Define a *single* repo verify entrypoint; **workers paste its real output** and the orchestrator **trusts a green standardized run**, re-driving only on a worker's explicitly-flagged uncertainty. And **never hand-write bespoke drivers in the main context** — each ad-hoc script sits in the premium context and is re-read (cache-read tax) every later turn; call the repo-provided driver or delegate the drive to a cheap sub-agent that returns a verdict. **Hard cap on confirmation-drives (this is the #2 cost lever and the root cause of image bloat):** once a worker returns green with its pasted standardized-run output, the orchestrator does **not** re-run that same verification itself "to be sure." Budget **at most one** inline re-drive for the *whole sprint's* single load-bearing increment — and even that is delegated if it would pull a screenshot or large artifact into the hub. Re-verifying already-green work in the premium context is what silently adds turns *and* drags in the screenshots principle 3 bans: the two biggest levers are the same habit. Trust the green; the **blind gate** is the real check, and it is owned by agents who never saw the build. 7. **Converge on a BLIND gate, not "one more final pass" — verify-each + hunt-across.** Fix-round hunting during the sprint uses diverse-lens hunters (correctness, edge/boundary, state/undo, data-loss, security). But *completion* is decided by **blind validators** who never saw the work (see *Stop rule*), and the default validator shape is **hybrid**: one small-context **verifier per change-request/cluster** (parallel, blind, each drives only its own surface and checks its acceptance Verify verbatim) **plus** one or two **broad adversarial hunters** for emergent/cross-cutting/integration bugs no single cluster would surface. **Scale verifier count to distinct *surfaces*, not raw CR count** — when N CRs build **one feature over a few surfaces** (e.g. 6 CRs → an exporter with ~3 drivable surfaces), a fix-round hunt(1) → blind(1–2) → [fix → blind(1)] is enough; fanning one per-CR verifier ×N spends flagship-max agents on overlapping coverage that largely agrees. Reserve the full per-CR fan-out for genuinely independent surfaces. Cap by the parallelism limit; every validator stays blind to sprint history regardless of scope. The biased main context declaring "done" is exactly the trap that spawns redundant "final" passes — see *Stop rule* and `references/orchestration.md` for the full protocol and the tradeoff (pure per-CR risks missing feature interactions; the broad hunters are what catch those). 8. **Verify with eyes, sample before declaring done.** The proof artifact is, **by default, a single self-contained Markdown sprint report** — agentic burndown + before/after screenshots per change — archived under `.hyper-sprint/completed//` (see *Proof artifact*). Screenshots come **free from the blind verifiers** (each `ctx.shot()`s its proof state via the `burst-bug-hunter` warm-app harness; "before" shots come from the base-commit render driven the same way). A recorded HTML/video demo deck is **optional** — build it only if the user asks. Never trust a shot blindly — *look* at it (feature visible, right screen, interaction landed); a driver bug silently proves nothing. **But the eyes are the verifier's, not the hub's:** the looking happens *inside* the blind verifier/hunter sub-agent, which reports a one-line frame-check verdict; the orchestrator reads that verdict and must **not** pull the PNG into its own context to look (principle 3). Same rigor, without pinning a 20K-token image in the premium loop for the rest of the run. 9. **Cost is a first-class deliverable, not an afterthought — and it's the real optimization target, not turns.** Hub cost compounds as **(standing context size) × (number of turns)**: nearly every token in a long sprint is a cache-*read* of context pinned in an earlier turn, re-billed on every turn since. Turn count naturally grows with a large, complex issue list — that's expected and fine — so the only real lever is keeping the **standing context thin AND flat** across the whole session, not just at the start. Track and report real spend, not a guess. Run a **mid-sprint cost checkpoint** — `assets/sprint-cost.py` at roughly the halfway point — so runaway hub bloat or an over-provisioned validator fleet is caught *before* it compounds, not discovered in a post-mortem. **Run it with `--audit`**: besides the per-agent cost table it flags the orchestrator's context bloat — image count + their cache-read share, and the largest pinned tool-results — so a "images-in-hub" or confirmation-drive regression is caught at turn ~150, not at the retro. The report's cost + savings section (see *Proof artifact*) comes from the same script re-run at the end. **Long-session cost levers (what actually keeps a big-list sprint cheap):** - **Pointers, not payloads** — recon/workers write detail to files, return a compact index/verdict; every KB pinned in the hub is re-read × every remaining turn (principle 2). - **Fat, batched delegations over many small round-trips** — give each worker a large, self-contained objective (a whole cluster, not one issue at a time) so N issues cost far fewer than N dispatch round-trips; fan out independent clusters in parallel rather than dispatching one-at-a-time. - **Never re-read or re-verify already-green work in the hub** — trust the standardized verify output a worker pastes; the blind gate, not a hub re-check, is the real check (principle 6). - **Hub tool-results stay small** — verdicts, not dumps; **no images in the hub, ever** (principle 3). - **Shed stale context at phase boundaries** — across a long sprint, prefer a clean boundary (end of a phase, after a merge) to compact or drop tool-results that are no longer needed, rather than letting standing context ratchet upward turn after turn. - **Replace, never absorb, a dead worker** — spawning a replacement sub-agent costs one dispatch; absorbing its unfinished debug loop into the hub is what turns a normal sprint into a 375-turn one (see the banner). 10. **Don't fight the environment.** Detect a capability once (signing keys, network, missing binaries); if an op is impossible here, record it as a known limitation and move on — don't burn turns retrying "command not found" or an empty credential. 11. **Right-size the fan-out & route the model.** Recon inline for a file a single worker owns; spawn a dedicated recon agent only for a subsystem no worker owns (don't pre-spawn agents that go unused). Parallelize independent reads/hunts and disjoint-file workers (worktrees); serialize colliding writes. Match model+effort to task difficulty — flagship for orchestration, hard logic, and the final adversarial hunt; cheap/fast for mechanical work **and for verification-drivers** (the per-CR verifiers in principle 7 need enough model to follow a spec, not the flagship) — full routing table in `references/orchestration.md`. 12. **Orchestrator, not worker — enforce worker restart budgets.** Every worker owns a session-only `context.md` outside the repository. It updates the file after each completed milestone, before each long validation/browser run, and at least every **10 tool calls or 5 minutes**. The file stays under 250 lines and records only the objective, acceptance, owned files, diff fingerprint, stable decisions, exact test state, artifact paths, open gaps, and ordered next actions. It excludes exploration history, raw logs, screenshots, and diffs. **Context relevance is the primary trigger.** Restart at each phase boundary when prior material is no longer needed (for example, discovery → implementation and implementation → validation), or sooner when failed paths, raw outputs, or completed work dominate the active context. The numeric budget is only a backstop: restart at the first hard limit of **50 tool calls, 15 minutes, or 3 completed turns**. A long command started below a limit may finish; then the worker checkpoints and stops. The orchestrator must not send more work to an over-limit agent. It starts a fresh agent from `context.md`; the replacement verifies the diff fingerprint and reads only changed regions before it continues. Track these limits from agent status and restart without waiting for quality to degrade. **Long-run resilience:** heavy sub-agents can also die mid-task. Session limits, rate limits, and container resets don't wait for a convenient boundary. Stagger heavy/long-running sub-agents rather than firing them all at once (so one reset doesn't stall the whole fan-out). When one dies, **spawn a replacement sub-agent that adopts its partial edits and re-verifies them** — never absorb the dead worker's remaining work into the hub yourself; the partial work is usually salvageable and a clean restart throws away real progress for no reason, but doing it in the main loop is the exact move that blew one sprint's hub cost to **$59.74 over 375 turns of 94% cache-read tokens** (heuristic ≤50 for a normal sprint, see the cost-economy banner at the top of this file). 13. **Report for steering, not just logging.** On a fixed cadence (not per-action) give a short, mobile-readable status: **done / total**, what's in flight, blockers. When the profile supports sending files/images, **attach screenshots of new or changed features** as they land so the user can course-correct early — cheap steering beats a wrong demo at the end. Adapt to the profile's comms channel; degrade to text where richer media isn't supported, skip silently where there's no user channel at all. 14. **Respect repo conventions & disclosure hygiene.** Read the repo's contributing/CLAUDE guidance first (version bumps, changelog, test commands, public-repo secrecy). Match surrounding code style. Never leak secrets, session URLs, or exploit detail into anything committed/public. 15. **Stay on the given branches.** Start from whatever **base branch** you were handed — never assume `main`/`master`. The only branches in scope are the **sprint branch** and its **base**; don't read, diff against, fetch, or checkout any other branch (or peek at other refs) unless strictly required and the user approves. Diff against the base you were given, not a guessed default. ## Phases **Phase 0a — Intake (orchestrator; stays in the hub, it drives planning).** Read the repo's **`.hyper-sprint/config.md`** at the repo root if present (base branch, build/test + app-boot commands, vendored/declared deps, conventions, stop rule) — honor it over guesses. Identify the **agent profile** (`references/agent-profiles.md`) and reuse its known facts. Parse the change list into discrete, testable items; ask *now* (batched) about any that don't make sense or need a UX decision. Image-heavy PDF → rasterize + read the screenshots (recipe in the profile). If the spec's screenshots are from a **different app version** than the base, flag it — some CRs may already be (partly) done; validate against the spec, don't blind-reimplement. Agree the **stop rule** explicitly (blind-hunt duration + proof artifact), and — in the same batched round of questions — decide the **gate style** (validator granularity: hybrid per-CR + cross-cutting is the default, see principle 7; adjust only for a good reason), the **driver style** (scripted vs interactive), and the **proof artifact** shape. Deciding these up front avoids building a validation round in one style and scrapping it for another once the CRs are already partitioned. **Phase 0b — Readiness probe (hard gate; inline or sub-agent per principle 1).** If the environment is already pre-provisioned (a setup script ran, a prebuilt image/artifact is present), the orchestrator runs the fast boot+smoke gate itself, inline, and moves straight to Phase 1. Otherwise, delegate to a readiness sub-agent: verify the config's commands/paths exist on the base branch (a missing one is *config drift* — **repair it here, don't route around it**: fix the broken path / stale test-id / missing reset hook so the shipped harness works, rather than quietly building your own). Provision declared deps; run build + tests; then boot and **smoke-test every surface the sprint will verify** (e.g. the primary view, a secondary mode, a dialog). It **writes an entrypoint file** (the one boot+drive command, baseline passing-count + known pre-existing failures, new gotchas) and **returns only `ready|blocked` + reason + that path**. Orchestrator **hard-gates on `blocked`** either way. Delegating (when genuinely needed) keeps the bring-up trial-and-error out of the premium context entirely; running it inline (when pre-provisioned) avoids paying a sub-agent round-trip for a gate that's already solved. **Readiness MUST boot *through the same harness the blind gate will use* — the `burst-bug-hunter` engine (§Phase 5), not a parallel driver.** Concretely: `start-hunt.sh `, then prove every sprint-verified surface with a real `vrun` burst (present view, gallery, a modal, the edit path…). This is where latent harness bugs surface at minute 5 instead of hour 2 — e.g. a headless `requestFullscreen` that hangs `keyboard.press` — and the workaround gets **crystallized into the repo verb library now**, so no later hunt re-pays it. **Anti-pattern (the #1 way the engine gets bypassed): writing a throwaway per-step Playwright helper for the readiness smoke and then reusing it for the blind gate.** If you catch yourself hand-rolling a `launch()`/driver in the hub, stop — fix the engine's config instead. A second driving harness that gets reused for verification means the enforced time-box and burst efficiency never apply. **Phase 1 — Recon.** Parallel read-only sub-agents (one per subsystem) → anchored edit maps in `NOTES.md`. **Phase 2 — Plan.** Cluster by file-locality into task-tracked items with **disjoint file sets** where possible; assign each a model/effort tier and a rough effort estimate (the burndown's ideal line); note the start time. **Pick a short memorable codename** for the sprint (e.g. `limelight`) — folder and plan filenames carry **date + codename**. **Write the plan NOW, not at the end:** create `.hyper-sprint/completed/-/plan--.md` with the *verbatim original prompt* + this plan (parsed CRs, clusters, batches). Capturing it live makes it a real artifact — at close you append a short "what happened vs plan" (e.g. blind-round count), which is only honest if the plan wasn't reconstructed afterward. **Phase 3 — Delegate & integrate.** Dispatch each cluster to a **worker sub-agent** (routed model/effort) with its objective, edit map, its **acceptance Verify verbatim**, and exclusive file set; disjoint clusters run in parallel **worktrees**. **Base-ref guard (hard rule — NEVER assume any checkout is on the intended ref: the harness may start the MAIN session on the default branch or any arbitrary branch, and worktree isolation may base new worktrees on the repo's DEFAULT branch, not the sprint branch — a stale ref silently hands every agent the wrong code):** in Phase 0 the orchestrator confirms its own working tree is on the designated sprint branch (`git rev-parse --abbrev-ref HEAD`; check out / create it from the designated base if not) before recording the sprint HEAD SHA everything pins to; then it pins that SHA in every worktree-agent prompt (workers AND validators), and the agent's step 0 — before reading or editing anything — is `git rev-parse HEAD` == that SHA, else `git reset --hard ` and re-check; a worker that edited before passing the guard redoes its work on the correct base. The orchestrator verifies each returned commit's merge-base against sprint HEAD before merging. Worker does edits + unit/e2e tests and returns a compact result — never its raw diff (*hub hygiene*, principle 3). **New UI a worker adds must be drivable by the repo's burst verb library**: emit the stable test-ids those verbs expect (or update the verbs in the same change) — otherwise the blind gate can't drive the feature and you pay a mid-sprint reconciliation. The orchestrator merges sequentially, **full suite green between merges**, and posts a steering update (done/ total + feature screenshots where supported, sent as a file/link — not pasted inline). Re-run the suite after every fix. **At roughly the halfway point, run the mid-sprint cost checkpoint** (`assets/sprint-cost.py` gives a per-agent + per-model cost breakdown from the transcripts so far — a mid-sprint run catches hub bloat or an over-provisioned fan-out while there's still time to correct it, instead of discovering it at the retro). **Phase 4 — Fix-round hunt.** Diverse-lens hunters find bugs → fix workers + regression tests → re-run suite. This *reduces* defects but does **not** decide done — the blind gate does. **Phase 5 — Blind gate + proof + archive.** Run the **blind validation** stop gate (below) — default hybrid shape (per-CR verifiers + broad hunters, principle 7). Browser verification runs **through the `burst-bug-hunter` engine — this is mandatory, not advice**; a round driven by an ad-hoc per-step Playwright harness **does not count** (it loses the enforced time-box and warm-app efficiency). **Render-freshness precondition (hard rule, before ANY hunt/verify dispatch — Phase 4 fix-round hunt, each blind-gate round, and any re-check after a fix commit lands): rebuild the offline render from current HEAD first. Never reuse a render/workdir across a commit boundary** — a validator driven against a stale pre-fix render produces a false-positive re-report of an already-fixed bug, and worse, that false positive can look like the mandatory "any real issue → new blind round" rule firing when it's actually testing dead code. One sprint hit exactly this: two round-1 validators re-found a bug that commit `31dc2c4` had already fixed, because the render dir wasn't rebuilt after the fix landed. Cheap, mechanical, zero tradeoff — rebuild every time, not "when in doubt." Concrete required sequence: for each hunter, `start-hunt.sh ` (one warm server, app opened once), **write the hard time-box to `/deadline`** (`python3 -c 'import time;print(time.time()+*60)' > /deadline` — the *engine* enforces it; a prompt that merely says "hunt for X minutes" with no `deadline` file is non-compliant), then spawn each blind hunter given only **`VDRIVE=` + the verbs path + the `vrun`/burst protocol** (never a bespoke driver). Each verifier works in **bursts** (multi-step `job.mjs` run to completion, observe at burst boundaries) and `ctx.shot()`s its proof state so the same pass that verifies also captures the report screenshots. Hunt **non-stop until the engine `deadline`**; `stats.json` + `findings.jsonl` are the audit trail. Only once it's clean, assemble the **default proof: a single Markdown report** — agentic burndown (from `assets/sprint-stats.py` + the blind-round timeline) + before/after screenshots + cost/savings (`assets/sprint-cost.py`) — and **archive the whole sprint** to `.hyper-sprint/completed//` (`README.md` = report, `plan-*.md`, `sprint.json`, `img/`); append a row to `.hyper-sprint/completed/README.md`. A recorded HTML/video demo deck is **optional** (build only on request — see *Proof artifact*). **Deliver the report as a clickable Markdown link** — `[Sprint "" report](https://github.com///tree//.hyper-sprint/completed/-)` (the `tree` folder URL renders the README on open). NEVER wrap the URL in backticks (that renders as non-clickable code) or hand over a bare repo path. Also offer the shorter **repo/branch-root** link — deep paths with a dot-folder (`.hyper-sprint`) often fall back to the browser, while short `github.com//` links hand off to the GitHub mobile app more reliably. Then the final status vs the full list. ## Proof artifact — default: a Markdown sprint report (video optional) **Default = one self-contained Markdown report** archived at `.hyper-sprint/completed//README.md` (renders when the folder is opened). Full convention + generation flow: **`references/sprint-archive.md`**. Arc: Scope → **agentic burndown** (work-remaining = open CRs + agent-found defects; the blind-hunt rounds *add* scope, so the curve bumps up before zero — render with `assets/mk-burndown.py`) → **stats** (`assets/sprint-stats.py`) → **before/after per change** (screenshots the verifiers already captured: HEAD for "after", the base-commit render for "before") → **cost/savings** (`assets/sprint-cost.py`, grounded in real numbers) → **bugs found & fixed**. Use **relative** `img/…` paths (GitHub renders those; it does *not* render base64 data-URIs) — optionally also emit a base64-inlined single-file copy for portable one-click viewing. **Screenshots are a by-product of verification, not a separate step.** The blind verifiers drive each feature through the `burst-bug-hunter` warm app; add one `ctx.shot("-after-…")` per proof state. "Before" shots = the same tagged bursts run against a render of the base commit. **Frame-check (hard gate):** *look* at every shot (feature visible, right screen, interaction landed) — a green suite is not proof the report shows it. **Optional: recorded HTML/video demo deck.** Build the embedded-clip HTML deck **only if the user asks** (a guided walkthrough on top of the report). Pipeline, slide types, VP8/frame-check gotchas: **`references/demo-deck.md`**. ## Stop rule (both required) 1. **A blind validation round comes back clean — hybrid: verify-each + hunt-across.** Spawn fresh validator sub-agents, **best model, max effort, always** (never economize on the gate). Default shape: a **small-context verifier per change-request/cluster** (parallel, blind, drives only its own surface and checks its acceptance Verify verbatim), **plus one or two broad adversarial hunters** for emergent/cross-cutting/integration/data-loss bugs that no single cluster's verifier would see. Scale verifier count to CR count, capped by the parallelism limit. Every validator's prompt contains **only** its slice of the acceptance spec (or the full spec, for the broad hunters) + code at HEAD + the **drive recipe** + the **known-intentional behaviors / acceptance nuances**, and instructs: "confirm every feature in scope, then hunt ANY bug for **X min non-stop**; **report the literal observed output, not interpretations**; report pre-existing/out-of-scope issues *separately* (they don't fail the gate)." **Withhold the sprint history** — bug counts, turns, elapsed time, "nearly done", the diff — so the verdict can't be anchored. Classify findings **in-scope defect vs cosmetic/out-of-scope from the start** — the bar never moves by round. Any in-scope finding → fix → **new** blind round (fresh agents; may share the harness bring-up, never the findings). Done when a full round **run through the `burst-bug-hunter` engine with an engine-enforced `deadline`** (§Phase 5) surfaces **zero in-scope defects** and all features confirmed present. The `X min` budget is the `deadline` file, not a sentence in a prompt — a round whose time-box wasn't mechanically enforced, or that was driven by a bespoke per-step harness instead of the engine, **does not satisfy the gate**. Keep the engine's `stats.json`/`findings.jsonl` as evidence the enforced burst hunt actually ran. (Protocol, and the tradeoff of per-CR-only vs hybrid: `references/orchestration.md`.) **And** 2. the **Markdown sprint report** exists at `.hyper-sprint/completed//README.md` (agentic burndown + before/after screenshots + cost) and its shots have been *looked at* to confirm every change is actually shown working. (A recorded video demo is optional — only when the user asks; it is **not** required for the gate.) Do not let the (biased) main context declare done; the gate is owned by agents who never saw the work happen. ## Package policy (installs) **Provisioning a dep the repo already declares is fine — adding a NEW one needs approval.** Installing what's already in the repo manifest (`package.json`, `requirements.txt`, lockfile — e.g. `npm ci`, `pip install -r`, or a single declared devDependency like `jsdom`) is readiness, not a new dependency; do it. **Adding an undeclared language package** (npm / pip / gem / cargo …) requires explicit user approval — prefer stdlib. OS packages via the system manager (`apt-get`) are fine. Allow-list (undeclared but safe, no approval — else ask): **`playwright`** (Node browser driver; browsers pre-provided) and **`poppler-utils`** (OS/apt: `pdftotext`+`pdftoppm` for spec PDFs). Never install a dep the repo config marks **vendored**. Anything else: stop and ask; the user amends this list to extend it. ## Repo config & pre-requisites Prefer a root **`.hyper-sprint/config.md`** (stack-agnostic — any agent framework reads it) carrying the repo facts: base branch, build/test + app-boot commands, vendored deps to never install, conventions, and the default stop rule. If it's absent, the caller should provide: - The **agent profile** (or confirmation of `claude-code-cloud-default`), plus how to **build/run tests** and **launch + drive the app** for this repo. - The **change list** (with screenshots/acceptance criteria where possible). - The **stop rule**: blind-hunt duration and expected proof artifact. - Repo conventions (versioning, changelog, secrecy) and the base branch.