Dispatch

Workhorse phase. Picks up a task file from /hyperflow:plan and runs it through the orchestrator pattern with parallel worker dispatch and multi-level reviews.

This skill exercises Layer 3 (Orchestrator), Layer 5 (Quality Gates), Layer 6 (Project Memory), Layer 8 (Git Workflow), and Layer 9 (Security) from the doctrine. Multi-level review (L1–L5) is applied per the triage's flow profile.

Per-Step Agent Map (DOCTRINE rule 12 — §12.1 inline-allowed for trivial steps · §12.2 sub-phase decomposition)

Every substantive step dispatches at least one Agent. Trivial steps (≤ 2 tool calls, no content generation, no decision-making, mechanically verifiable) MAY be performed inline by the orchestrator per §12.1. Non-trivial steps decompose into ≥ 2 named sub-phases per §12.2.

Step	Sub-phase	Workers	Reviewer	Notes
0 — Mode confirm	— (exempt)	—	—	AskUserQuestion only
0.5 — Operational choices	— (exempt)	—	—	AskUserQuestion only
1 — Load task	— (atomic · §12.2.8)	—	—	Read + schema check = single mechanical decision; no parallel angles
2a — Pre-dispatch	Composer × N parallel — one per sub-task; stitches persona + injects learnings	Reviewer — reviews prompt set for completeness	Parallel worker prompts built before any fan-out fires
2b — Worker fan-out	Implementer / Searcher / Writer × N parallel	Domain specialist Reviewer — the Specialist:-matched agent, batched over full batch (P2) or per-sub-task fallback	One Reviewer call per batch; security/correctness specialists run with --thorough
2c — Gate run	Worker — runs lint/typecheck/tests on affected files	Reviewer — judges gate output	Small focused diff
2d — Learnings + commit	Writer — synthesizes per-batch learnings	— (mechanical commit · §12.1)	Per-sub-task PASS commits land here; learnings appended to context
3 — Final integration review	— (atomic · §12.2.8)	Reviewer — broadest matching specialist(s), L1–L over full diff	Single Reviewer dispatch; skipped under D7 incl. single-specialist coverage (rule 17)
4 — Wrap up	Writer — optional; only if memory prose is non-trivial	—	§12.1 trivial-inline; no Reviewer (D5)
5 — End of chain	— (exempt)	—	ONE AskUserQuestion with audit + deploy questions

Iron rule — review agents ≥ batches + 1 (one batched Reviewer per batch + final integration when not skipped). The batched Reviewer counts as 1 per batch regardless of how many sub-tasks are in the batch. If less, a per-step reviewer was skipped.

Review Levels (scale by flow profile)

Every batch reviewer and the final integration reviewer uses the level set below. Profile comes from /hyperflow:plan triage and is propagated via the chain args (triage=).

Profile	Levels	Workers	Reviewers
fast	L1	1	inline self-review only
standard	L1–L2 default	1–2	1 per-batch reviewer
deep	L1–L5	3+	per-batch + final integration
research	L1–L2 + synthesis	3+ searchers	inline synthesis
creative	L1–L3 + UX	1–2	1 reviewer
scientific	L1–L5 + TDD	2–3	per-batch + final

L1 syntax/format · L2 spec/naming/edges · L3 integration/security · L4 perf/scale · L5 a11y/UX. See review-levels.md for the full checklist.

Default cap is L1-L2. Triage may flag security: true or integration_risk: true in its output; when either is set, the cap elevates to L1-L3 for both per-batch and final integration reviewers. Workers do NOT request elevation — only the upstream triage classification can elevate. See reviewer-prompt-batched.md — workers must honor the cap passed to them (cap enforcement lives on the reviewer-prompt side).

Approval Gates

Gate	When	Format
Session context	Step 0, resolved (not asked)	inherited session= / handoff HANDOFF.md / default one
Phase-dispatch scope	Step 1.5, feature mode with ≥ 2 incomplete phases	AskUserQuestion — all phases / phase by phase
Inter-batch (manual mode only)	After each batch's gates pass	AskUserQuestion — continue / stop. Auto mode fires NO inter-batch question — see DOCTRINE rule 8 (invented gates banned).
Hard halt	Any SECURITY_VIOLATION from a reviewer	Stop the chain, surface the finding
Audit prompt	Step 5, after wrap-up	AskUserQuestion — run /hyperflow:audit? (yes/no, recommended toggles with flow profile)
Deploy prompt	Step 5, after audit gate	AskUserQuestion — run /hyperflow:deploy? (yes/no, recommended toggles with gate state)

Inputs

• Task artefact — positional arg (slug or path): either a flat .hyperflow/tasks/.md or a feature folder .hyperflow/features// (see ../hyperflow/feature-phases.md). Default — the most-recently-modified of either.
• Handoff package — a positional slug/path resolving to .hyperflow-handoff// (see ../hyperflow/session-handoff.md). When present, dispatch is a second-session build: it rehydrates artefact/ into .hyperflow/ (Step 1.0) and reads session/handoff/chain args from HANDOFF.md. on_complete (review|deploy) governs Step 5.
• session= — passed in by /hyperflow:plan (or read from a handoff package's HANDOFF.md). If absent, assume one. In a two-session build, handoff= governs the end-of-build behavior at Step 5.
• --from-batch — resume from a specific batch (skip prior batches).
• --final-only — skip batch dispatch, run only the final integration review.
• --thorough — disable P2 batched reviews; fall back to per-sub-task reviewers for every sub-task in every batch, and always run the final integration review (D7 skip is disabled). Use when belt-and-suspenders depth is required on a high-risk run. P3 (concurrent pre-conditions) and P5 (lean worker prompts) remain on. When --thorough is passed, BOTH D5 (wrap-up Reviewer drop) and D7 (integration review skip) are disabled — the full pre-round-2 ceremony runs. D2 combined gate stays (no quality tradeoff), D6 default L1-L2 stays (cap can still be elevated by triage flags).

Flow

Step 0 — Resolve session context (only if invoked directly)

Dispatch is the build endpoint — it is on the far side of the planning→build split, so it does not ask the one/two-session question (that decision is made upstream at spec/scope, or carried inside a handoff package). It resolves the session context instead:

• A session= arg was propagated (from scope) → use it.
• Invoked directly on a handoff package (slug resolving to .hyperflow-handoff//) → read session/handoff/chain args from its HANDOFF.md; this is a second-session build (see ../hyperflow/session-handoff.md).
• Invoked directly on a plain task file with no session= arg → default session=one (build here, then offer the audit/deploy gates at Step 5). No session question fires — there is nothing left to split.

Step 0.5 — Operational Choices (STRUCTURAL GATE · fires immediately after Step 0)

When operational args (commit=, branch=, push=) were NOT already propagated from a prior chain-starter or a handoff package, fire ONE AskUserQuestion call with 3 questions covering every operational decision dispatch needs. After this batch, dispatch runs silently until the end-of-chain audit + deploy gates.

Skip when operational args are already propagated (re-asking is an invented-gate violation).

Dispatch owns this gate (plan no longer asks operational choices at startup — it stops at a build-location gate and lets dispatch decide commit/branch/push when a build actually starts). The 3 questions are commit cadence · branch behaviour · push at end, with the canonical option text, recommended-default logic, the Per-task (deferred) queue behaviour, and the commit=/branch=/push= propagation contract in ../hyperflow/git-workflow.md. Recommended defaults: commit Per-task (unless complexity=low ∧ sub-tasks≤2 → Single); branch Create on main/master else Stay; push Ask at deploy gate always. Skip only when the args are already propagated (re-asking is an invented-gate violation).

Step 1.0 — Handoff rehydration (handoff pickup only)

When invoked on a handoff package (.hyperflow-handoff//), before loading the task:

1. Read HANDOFF.md → artefact type, chain args (commit=/branch=/push=/triage=/mode=, plus ghissue=/pr=/comment= when the plan was GitHub-native), oncomplete.
2. If the .hyperflow/ cache is absent → run /hyperflow:scaffold first (so workers get Layer-0 context). If scaffold cannot run here, fall back to the package's context/ copies.
3. Copy artefact/tasks/.md → .hyperflow/tasks/.md (flat), or artefact/features// → .hyperflow/features// (feature), if not already present locally.
4. Leave STATUS=planned until the build completes (Step 5 flips it).

Then continue Step 1 normally. (Non-handoff runs skip Step 1.0.)

Step 1 — Load the task (atomic · §12.2.8)

Detect the artefact mode:

• Flat — .hyperflow/tasks/.md (the terse roster). Read it; extract batches, sub-tasks, flow-profile, and operational args. For each roster line carrying a Brief: /T.md pointer, note the brief path — Step 2a loads it verbatim (do not inline its body here).
• Feature (multi-phase) — .hyperflow/features//. Read feature.md for the ordered phase roster +

dependency graph + Specialists. Each phase--/ is executed as if it were a task file: its

phase.md carries the batch/task roster and its tasks/T*.md are the sub-tasks. Also read each phase's spec.md

/ research.md (when present) and inject them as the phase's design context into Step 2a Composers.

Confirm structural completeness: batches/tasks non-empty, each task has id, title, files, complexity,

Specialist. If absent or malformed, stop and suggest /hyperflow:plan first.

> Atomic-exempt per §12.2.8 — file/folder existence + schema validation is a single mechanical decision with no parallel angles. No Worker or Reviewer dispatched.

Step 1.5 — Phase loop (feature mode only)

Phase-dispatch scope gate (STRUCTURAL GATE · feature mode, ≥ 2 incomplete phases). Before the loop, fire ONE AskUserQuestion — a named-workflow choice, so the recommended option goes first with (Recommended):

This feature has <N> phases. How should I build them?

  All phases (Recommended)  — build every phase in order, straight through to the end.

  Phase by phase            — build only the NEXT phase, then stop so you can review it
                              before the next one starts. Re-run /hyperflow:dispatch
                              <slug> to continue with the following phase.

Skip the gate (default all) when: only one phase is incomplete; --phases=all|next was passed; or this is an on_complete=deploy two-session build (fully autonomous — all). Portable surface without popup (Codex / OpenCode / Grok) → Hyperflow Question chat-block fallback; no channel at all → default All phases. Propagate the choice as --phases=.

In feature mode, Step 2 runs once per phase, in roster order. A phase does not start until its Depends on

phase is completed. For each phase:

1. Run Step 2 over that phase's batches (parallel inside the phase, exactly as flat mode).
2. On all-tasks-PASS + exit criteria met → set phase.md status completed, advance feature.md's Phases bar,

and append the phase's decisions.md learnings to .hyperflow/memory/ (Step 2d learnings synthesis writes here).

1. Run Step 3 (final integration review) per phase over that phase's cumulative diff (D7 + single-specialist

skip apply per phase). After the last phase, also run one feature-level integration pass over the full diff

when ≥ 2 phases touched disjoint surfaces.

1. If --phases=next — STOP after this phase completes. Print: Phase done (/). Review it, then run /hyperflow:dispatch to build the next phase. Do NOT advance to the next phase. If --phases=all — continue to the next phase immediately.

In flat mode, skip Step 1.5 — Step 2 runs once over the single task file's batches as before.

Step 2 — For each batch

Print the batch header: Batch — .

Mode resolution (one-time per chain, before Step 2a fires for the first batch): run python3 $PLUGINROOT/scripts/resolve-mode.py $PROJECTROOT --from-args "$CHAIN_ARGS" and cache the resulting word (default / lean / thorough). Subsequent batches use the cached value.

Sub-phases 2a–2d run in order for every batch (P1 sequential — each depends on the prior sub-phase's output). Within each sub-phase, Workers are parallel.

Step 2a — Pre-dispatch (P1 · sequential after mode resolution)

For each sub-task in the batch, dispatch a Composer Worker in parallel (one Composer per sub-task — N total). Each Composer:

• Loads the pre-authored brief verbatim when one exists. If the roster line carries a Brief: /T.md pointer (plan's briefs=auto default), read that file and use its body — Task / Why / Scope / Files / Acceptance criteria / Test cases (incl. the E2E case) / Gotchas — as the worker-prompt body unchanged. Do NOT re-derive those sections; plan already authored them on the strong model. The Composer's only job is then to append context (below). Fallback (no brief): trivial sub-task or a legacy terse task file → author the brief inline per worker-prompt.md, the pre-existing behavior. This loader path is what lets dispatch run faithfully on a cheaper model or a second session.
• Selects the worker persona (Implementer / Searcher / Writer) from the sub-task brief.
• Stitches the persona header + Project Context per resolved mode:
• mode = default / thorough → inline excerpts from .hyperflow/profile.md, architecture.md, conventions.md matching the worker's role.
• mode = lean → render the lean Project Context block: a Project Context (load on demand): heading + paths to .hyperflow/memory/session-context.md, .hyperflow/profile.md, .hyperflow/architecture.md, .hyperflow/conventions.md, .hyperflow/testing.md, .hyperflow/memory/index.md with one-line descriptions each. Workers read on demand. Saves ~2k tokens × N; same content, lazy access.
• Injects accumulated Learnings from prior batches (in all modes).
• Outputs a complete worker prompt ready for fan-out.

Use the worker-prompt.md template for each Composer output. Persona stitching (top-3), memory injection (all tag matches), and all clarification gates remain unchanged regardless of mode.

Each Composer also reads the sub-task's Specialist: field from the task file and stitches that specialist's

output-contract expectations (../../agents/README.md) into the worker prompt, so

workers produce review-ready output for the specialist that will judge it (e.g. an api-reviewer sub-task tells the

worker to document status codes + validation up front). It also fills the worker-prompt {{CONSULTPEERHINT}} slot

from that specialist's Composes with: line (the recommended peers); if the line is absent it renders "any

specialist as needed". The hint only ranks peers — the worker may consult any agent in agents/ (consultation.md).

After all Composers return, dispatch one Reviewer over the full prompt set: confirms persona selection is correct, context block is well-formed, learnings are injected. Verdict: PASS / NEEDSREVISION. NEEDSREVISION re-dispatches only the affected Composer(s).

Step 2b — Worker fan-out (P1 · sequential after 2a · internal parallelism P1)

Dispatch all N sub-task Workers in a single message with parallel Agent calls using the composed prompts from Step 2a. Workers are Implementer / Searcher / Writer and run fully in parallel.

When all workers have returned, dispatch one batched per-batch Reviewer covering the entire batch (P2 — batched single-pass review):

• Dispatch as the matching domain specialist. Read the batch's sub-task Specialist: fields (Brain-decided, from the task file). Dispatch the per-batch Reviewer as that specialist agent (../../agents/README.md) — its charter + strict checklist + output contract injected on top of reviewer-prompt-batched.md. When the batch spans several surfaces, inject the union of the matching charters. On a gated flow the specialist runs its web-research-first pass (web-research.md) before the verdict.
• Check level-cap homogeneity first. If every sub-task shares the same review-level cap → batched review. If any sub-task carries a different cap (rare mixed profile) → fall back to per-sub-task reviewers.
• Also fall back to per-sub-task reviewers when --thorough was passed.
• Batched reviewer dispatch: use reviewer-prompt-batched.md. Print Reviewer — batched review Batch (L1–L, sub-tasks). Returns one verdict per sub-task.
• Per-sub-task fallback (mixed caps or --thorough): dispatch a separate reviewer per sub-task per reviewer-prompt.md. Print Reviewer — reviewing (L1–L).
• Per-batch vs final-integration split: per-batch reviewers are anchored to one batch's diff and catch L1–L issues there. The final integration Reviewer at Step 3 sees the cumulative diff across all batches and catches cross-batch contradictions no single batch-anchored reviewer could see. Running both passes covers more ground than running either alone.

(Path note: reviewer-prompt-batched.md lives in skills/hyperflow/ because it is a cross-skill template shared across the chain; reviewer-prompt.md stays in dispatch/references/ from prior convention. The asymmetric paths are intentional.)

Failure recovery: DOCTRINE rule 14 — skills/hyperflow/failure-recovery.md. When a Worker errors out (tool crash, OOM, 5xx, timeout) or returns malformed output: retry → escalate (add a deeper review pass) → abort. After 3 cumulative aborts in the chain, the chain itself aborts and prints the full failure trail.

Parse the per-sub-task verdicts:

• SECURITY_VIOLATION — halt the chain immediately. Surface the finding; do not commit anything in the batch.
• Worker returned OVERSIZE: with SUGGESTED-SPLIT: — do NOT proceed. Dispatch a Planner consultation: Planner — mid-flight split — split per Worker's OVERSIZE signal. Pass the Worker's reason, suggested split, the original brief, and batch context. The Planner returns a final split plan (N new sub-tasks, each complexity = low | medium). Remove the original; dispatch the N new sub-tasks as a new sub-batch. The per-batch Reviewer fires after the new sub-batch completes. No user question — splitting an oversized brief is a mechanical reshape.
• Worker (or batched Reviewer) returned CONSULT: — — do NOT mark the sub-task done. Broker per consultation.md: resolve to agents/.md (any registered agent), dispatch it with the consultation brief (CONSULT-CONTEXT + "answer in ≤8 lines, you are consulted not taking over"), then re-dispatch only that Worker/Reviewer with Consultation answer from : injected. Cap 2 consults/worker; a consulted peer may not itself consult (depth-1). If doesn't resolve or errors, fall back to failure-recovery (ESCALATE) — never block. No user question — a consult is a mechanical handoff.
• NEEDS_FIX — re-dispatch only that sub-task's Worker with the fix list. After the fix, dispatch a single focused reviewer for just that sub-task (not a full re-batch). Repeat until PASS (max 3 retries before re-scoping the sub-task).
• PASS — sub-task handed to Step 2d for commit.

Step 2c — Gate run (P1 · sequential after 2b verdicts resolve)

After all sub-tasks in the batch have passed review, run Layer 5 quality gates (lint / typecheck / tests on affected files) per quality-gates.md.

Dispatch one Worker to run the gate commands. Dispatch one Reviewer to judge the gate output. Verdict: PASS / NEEDSFIX. On NEEDSFIX the Worker applies fixes (never amending per-sub-task commits — fixes land as small additional commits) and the gate re-runs. Max 3 gate cycles before escalating.

Failure recovery: DOCTRINE rule 14 — skills/hyperflow/failure-recovery.md. When the per-batch Reviewer returns NEEDSREVISION, retry the Worker once with a ## Learnings from review injection. A second NEEDSREVISION surfaces the sub-task as partial; the chain continues with the latest output marked partial — no third Worker dispatch.

Step 2d — Learnings + commit (P1 · sequential after 2c PASS)

For each sub-task whose verdict is PASS:

• Commit immediately per git-workflow.md rule 2 (per-sub-task commit cadence). Stage only the files that sub-task touched. Write a conventional commit (feat():