Dispatch

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.

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=).

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

Inputs

• Task artefact — positional arg (slug or path): either a flat .hyperflow/tasks/<slug>.md or a feature folder .hyperflow/features/<slug>/ (see ../hyperflow/feature-phases.md). Default — the most-recently-modified of either.
• Handoff package — a positional slug/path resolving to .hyperflow-handoff/<slug>/ (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=<one|two> — passed in by /hyperflow:plan (or read from a handoff package's HANDOFF.md). If absent, assume one. In a two-session build, handoff=<review|deploy> governs the end-of-build behavior at Step 5.
• --from-batch <n> — 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=<one|two> arg was propagated (from scope) → use it.
• Invoked directly on a handoff package (slug resolving to .hyperflow-handoff/<slug>/) → 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/<slug>/), before loading the task:

1. Read HANDOFF.md → artefact type, chain args (commit=/branch=/push=/triage=/mode=, plus gh_issue=/pr=/comment= when the plan was GitHub-native), on_complete.
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/<slug>.md → .hyperflow/tasks/<slug>.md (flat), or artefact/features/<slug>/ → .hyperflow/features/<slug>/ (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/<slug>.md (the terse roster). Read it; extract batches, sub-tasks, flow-profile, and operational args. For each roster line carrying a Brief: <slug>/T<id>.md pointer, note the brief path — Step 2a loads it verbatim (do not inline its body here).
• Feature (multi-phase) — .hyperflow/features/<slug>/. Read feature.md for the ordered phase roster + dependency graph + Specialists. Each phase-<n>-<name>/ 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=<all|next>.

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).
3. 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.
4. If --phases=next — STOP after this phase completes. Print: Phase <name> done (<k>/<N>). Review it, then run /hyperflow:dispatch <slug> 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 <n> — <one-line description>.

Mode resolution (one-time per chain, before Step 2a fires for the first batch): run python3 $PLUGIN_ROOT/scripts/resolve-mode.py $PROJECT_ROOT --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: <slug>/T<id>.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 {{CONSULT_PEER_HINT}} 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 / NEEDS_REVISION. NEEDS_REVISION 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 <n> (L1–L<n>, <k> 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 <subtask> (L1–L<n>).
• 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: <reason> with SUGGESTED-SPLIT: — do NOT proceed. Dispatch a Planner consultation: **Planner — mid-flight split** — split <sub-task-id> 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: <peer> — <question> — do NOT mark the sub-task done. Broker per consultation.md: resolve <peer> to agents/<name>.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 <peer>: injected. Cap 2 consults/worker; a consulted peer may not itself consult (depth-1). If `<pee