Dispatch

Dispatch

Workhorse phase. Picks up a task file from /hyperflow:scope and runs it through the orchestrator pattern with parallel worker dispatch and thinking-tier 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 | Worker tier | Thinking tier | 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 (Sonnet) — one per sub-task; stitches persona + injects learnings | Reviewer (Sonnet) — reviews prompt set for completeness | Parallel worker prompts built before any fan-out fires | | 2b — Worker fan-out | Implementer / Searcher / Writer × N parallel (Sonnet) | Reviewer (Sonnet · worker tier) — batched over full batch (P2) or per-sub-task fallback (mixed caps / --thorough) | One Reviewer call per batch · escalates to Opus under --thorough | | 2c — Gate run | Worker (Sonnet) — runs lint/typecheck/tests on affected files | Reviewer (Sonnet) — judges gate output | Small focused diff; Sonnet sufficient | | 2d — Learnings + commit | Writer (Sonnet) — 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 (Opus · thinking tier) — L1–L over full diff | Single Reviewer dispatch, no parallel angles; atomic-exempt | | 4 — Wrap up | Writer (Sonnet) — 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 — thinking 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:spec triage and is propagated via the chain-mode args.

| 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 | |---|---|---| | Chain mode | Step 0, only if invoked directly | AskUserQuestion — auto / manual | | 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 file — positional arg (slug or path). Default — most-recently-modified file in .hyperflow/tasks/.
• chain-mode= — passed in by /hyperflow:scope. Controls whether to pause for confirmation after the final integration review. If absent, assume auto.
• --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. 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 — Choose mode (only if invoked directly · STRUCTURAL GATE)

This is a structural gate per DOCTRINE rule 8. When dispatch is invoked directly (no chain-mode arg from scope), it MUST fire. "No clarifying questions" / "auto-pilot" / any autonomy directive does NOT skip it. Defaulting silently is a doctrine violation.

If a chain-mode arg was passed, skip this step — the chain-starter already asked.

Otherwise, ask via AskUserQuestion. Per DOCTRINE rule 8, the recommended option goes first with (Recommended):

How should I handle progress through the batches?

  Auto (Recommended)  — run all batches + final review and stop. Print next-step suggestions.
  Manual              — pause between batches and ask before continuing.

Wait for the user's answer. Do not proceed without it. If AskUserQuestion cannot be presented as a popup, use the Codex fallback: print the same gate as a Hyperflow Question chat block with numbered options, then stop and wait for the user's answer. If no interactive channel is available at all, print an error and stop — never silently default.

Step 0.5 — Operational Choices (auto-mode only · STRUCTURAL GATE · fires immediately after Step 0)

When the user picks Auto at Step 0 AND operational args (commit=, branch=, push=) were NOT already propagated from a prior chain-starter, 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 chain-mode=manual (per-batch pauses cover ops decisions) OR when operational args are already propagated (re-asking is an invented-gate violation).

The 3-question batch is identical to scope Step 0.5 — see [scope/SKILL.md § Step 0.5](../scope/SKILL.md#step-05--operational-choices-auto-mode-only--structural-gate--fires-immediately-after-step-0) for the full question + option text + recommended-default logic + chain-arg propagation contract. Spec, scope, dispatch share one canonical definition; whoever fires first owns the batch, the others see the args propagated and skip.

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

Read .hyperflow/tasks/.md. Extract batches, sub-tasks, flow-profile, and operational args. Confirm the task file is structurally complete: batches array non-empty, each sub-task has id, title, files, complexity. If absent or malformed, stop and suggest /hyperflow:scope first.

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

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 $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:

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

After all Composers return, dispatch one Reviewer (Sonnet) 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 (Sonnet) and run fully in parallel.

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

• 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 (reviewers escalate to Opus under --thorough).
• Batched reviewer dispatch: use [reviewer-prompt-batched.md](../hyperflow/reviewer-prompt-batched.md) with model: "" (or "" under --thorough). Print **Reviewer** (Sonnet) — 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](references/reviewer-prompt.md). Print **Reviewer** (Sonnet) — reviewing (L1–L).
• Why Sonnet by default: per-batch reviewers see one batch's diff (typically 2–8 files). L1 (syntax/format) and L2 (spec/naming/edges) are pattern-matching work Sonnet handles at near-Opus quality. The cross-cutting concerns Sonnet might miss (L3+ integration, architectural drift) are exactly what the Opus final integration Reviewer at Step 3 catches over the cumulative diff. Two-tier review covers more ground than two-Opus review at a fraction of the cost.

(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 tier → 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 Thinking Lead consultation: **Thinking Lead — Planner (mid-flight split)** — split per Worker's OVERSIZE signal. Pass the Worker's reason, suggested split, the original brief, and batch context. The Thinking Lead 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.
• 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 escalating to a thinking-tier worker).
• 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](references/quality-gates.md).

Dispatch one Worker (Sonnet) to run the gate commands. Dispatch one Reviewer (Sonnet) to judge the gate output. Verdict: PASS / NEEDS_FIX. On NEEDS_FIX 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](../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](references/git-workflow.md) rule 2 (per-sub-task commit cadence). Stage only the files that sub-task touched. Write a conventional commit (feat(): derived from the task file). One sub-task = one commit. A batch of 3 parallel sub-tasks produces 3 commits, even though they were reviewed in a single batched Reviewer call.
• Update the task file's ## Status block after each commit lands: tick [ ] → [x], increment Sub-tasks: /, add tokens to Tokens used: running totals, refresh Wall-clock: and Last update:, recompute ETA: once ≥3 sub-tasks are done. This is what /hyperflow:status reads for live progress.

Dispatch one Writer (Sonnet) in parallel to synthesize per-batch learnings from all Worker outputs and the Reviewer's notes. The learnings are appended to the in-memory Learnings from prior batches context (injected at Step 2a of subsequent batches). Writer also checks off the batch in the task file.

The two activities (commits + learnings synthesis) run concurrently — the Writer synthesizes while commits land sequentially per the commit cadence arg.

After Step 2d, print a one-line status update — "Batch 1 done · 9/36 sub-tasks · next: B2 deps" — then proceed to the next batch immediately in auto mode. Per DOCTRINE rule 8, "transparency checkpoints" / "m

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeremylongshore
• Source: jeremylongshore/claude-code-plugins-plus-skills
• License: MIT
• Homepage: https://tonsofskills.com

Install and usage instructions live in the source repository linked above.