---
name: Dispatch
slug: dispatch
category: Automation
description: Fans out parallel workers under per-batch Reviewers, runs a final integration review, and commits per sub-task. Endpoint of the auto-chain — no auto-deploy.
github: "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/ai-agency/hyperflow/skills/dispatch"
language: Python
stars: 2565
forks: 367
install: "git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills"
added: 2026-07-19T06:55:10.096Z
last_synced: 2026-07-29T06:36:42.046Z
canonical_url: "https://dirskills.com/skills/dispatch"
---

# Dispatch

Fans out parallel workers under per-batch Reviewers, runs a final integration review, and commits per sub-task. Endpoint of the auto-chain — no auto-deploy.

**Install:** `git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills`

## README

# 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<n> 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](references/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/<slug>.md` **or** a feature folder `.hyperflow/features/<slug>/` (see [`../hyperflow/feature-phases.md`](../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`](../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`](../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`](../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](references/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](references/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`](../../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](../hyperflow/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`](../../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](../hyperflow/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](../hyperflow/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](references/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<n> 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`](../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](../hyperflow/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