parallel-dispatch

Parallel Dispatch — T3 Quartet Orchestration

Tier first. Pick the smallest pipeline. Auto-escalate one tier on migration / RLS / auth / payments / enum / public-export / generated-column / >5 files / >100 lines. User words "deep", "every page", "pixel-perfect" force T3. Cross-cutting gates (type-check, lint, build, browser when UI) run at every tier — tier sizes the agent fleet, not the gates.

Mistake-monitor required for T2 and T3. Skip for T0/T1 (small surface = monitor adds latency without finding much).

⛔ Single-message fan-out for T3

When N independent sub-domains, emit ONE tool-call turn with 4N Agent blocks (1 foreground primary + 3 backgrounded helpers per domain).

N domains	Agent blocks	Foreground	Background
1	4	1	3
2	8	2	6
k	4k	k	3k

Acceptable sequencing (only):

• Cross-cutting gates run AFTER all primaries + their re-dispatch chains have settled.
• Per-source-agent re-dispatches fire as sources go idle (still in same conversation turn).

Unacceptable: splitting quartets across turns. Violation symptom: total wall ≈ N × per-quartet budget instead of ≈ 1 ×.

Tool wiring contract

Every dispatched agent inherits the orchestrator's full surface: all Claude Code official tools, full mcp__Claude_in_Chrome__* namespace, all project MCPs (Supabase, Sentry, Greptile, Context7, GitHub). Read-only constraints are enforced by prompt rules, not by stripping tools.

• Read-only agents (Explore, mistake-monitor, code-reviewer, dept-verifier, perf-auditor in dept mode) MUST still HAVE writer tools available — that's how mistake-monitor audits "did the source agent actually call Edit?". Read-only enforcement is in their prompt body.
• Writer-gated MCPs (Supabase apply_migration/execute_sql writes, deploy_edge_function, branch ops, pause/restore): db-guardian only by prompt rule.
• GitHub writes: orchestrator only, with explicit user "push" this turn.

If a target subagent's frontmatter restricts tools: to a subset missing a required entry, fall back to general-purpose and pass role-specific instructions in the prompt — never silently dispatch a tool-starved helper.

Decomposition (T3 only)

1. What independent sub-domains? Different pages, tables, Sentry issues, API routes, verification targets → one quartet each.
2. Truly independent? Pre-flight: no shared files, no shared DB rows, no shared API route, no ordering dependency.
3. Yes → fan out N quartets (4N agents) in ONE message.
4. No, but T3 → one quartet on the single domain.

The Investigation Quartet

Role	Default subagent	Mode	Job
Primary	Domain specialist (see table below)	read+write	Owns the domain end-to-end. Only writer for the domain.
Deep Explorer	Explore or feature-dev:code-explorer	read-only	Maps the dependency graph: every file/route/hook/store consuming the affected code.
Deep Validator	feature-dev:code-reviewer	read-only	Audits primary's diff for missed cases, regressions, RLS holes, naming drift, gotcha-doc hits.
Mistake Monitor	frontend-backend:mistake-monitor	read-only	Quick Check on primary's diff for the source agent's typical failure mode + verification-skip detection.

Quartet contract

• Primary is the only writer. Helpers MUST NOT call Edit/Write/apply_migration.
• All four run concurrently — ONE message with 4 Agent blocks.
• Each receives same domain context (goal, scope, constraints, verification gate) + role-specific instruction.
• Mistake Monitor runs in two passes: Pass A (coarse, immediate, parallel with primary, on git state) emits provisional findings; Pass B (fine, post-primary diff) confirms or supersedes. De-dup by (file, line-range, category).

Role-specific prompts

[PRIMARY]
You are the writer. Investigate via Grep/Read, fix root cause, verify locally. Return: root cause in one sentence + diff list + verification evidence + adjacent risks.

[DEEP EXPLORER]
Read-only. Map every consumer of the affected code: files importing/reading/writing the column or component, adjacent routes/hooks/stores/pages, tests/docs referencing it. Return: dep map with file:line. No fixes.

[DEEP VALIDATOR]
Read-only. Audit primary's domain for: missed cases (same bug shape elsewhere), convention violations (CLAUDE.md + gotcha-doc — tz helpers, whitelist helpers, enum casing, mobile breakpoints, design tokens, .single vs .maybeSingle), RLS/permission gaps. Return: findings with file:line + severity + recommended action. Don't edit.

[MISTAKE MONITOR]
Read-only. Quick Check primary's diff for the source agent's typical failure mode. Read project CLAUDE.md + gotcha-doc first. Generic sweeps: schema/RLS drift, same-bug-shape across codebase, verification-skip detection (every "X passes" claim must cite a tool call this turn), file-size limits, test-data pollution, tool-substitution violations. Return: findings with severity + file:line + category + fix instruction + "Re-dispatch to: <source-agent>". Don't edit.

Streaming dispatch (per source agent, N rounds)

Time budget (wall p95): T0 ≤ 1m · T1 ≤ 4m · T2 ≤ 8m · T3 ≤ 15m per quartet. Quartets concurrent — N do NOT add their times. Escalate to user if a tier blows budget.

Three rules:

1. Helpers backgrounded; primary foreground. Primary's diff gates correctness. Explore, code-reviewer, mistake-monitor all dispatch run_in_background: true. Findings stream back into per-source-agent queues.
2. N rounds per source agent (default N=3). Each helper finding fires its own re-dispatch the moment the source agent is idle. Findings while in-flight queue, de-duped by (file, line-range, category). State: idle → in-flight → (queued ? merge-and-redispatch : idle). Wall budget T2=90s, T3=180s per source agent across all rounds combined. Beyond cap → "Open findings — deferred (round-cap-truncated | deadline-truncated)".
3. Every Agent() carries model: "inherit".

Dispatch template

Message 1 (one turn, all helpers backgrounded):
  Agent(subagent_type=<primary>,                 description="primary: <domain>",  prompt=...PRIMARY...,   model="inherit")
  Agent(subagent_type=Explore,                   description="explorer: <domain>", prompt=...EXPLORER...,  model="inherit", run_in_background=true)
  Agent(subagent_type=feature-dev:code-reviewer, description="validator: <domain>",prompt=...VALIDATOR..., model="inherit", run_in_background=true)
  Agent(subagent_type=frontend-backend:mistake-monitor, description="monitor: <domain> (A+B)", prompt=...MONITOR..., model="inherit", run_in_background=true)

Per-quartet streaming loop (same turn):
  1. Primary returns → capture diff + start per-source wall-budget timer.
  2. Helper finding arrives → look up source agent in `Re-dispatch to:`:
       if state[src]==idle and rounds[src]<N: fire re-dispatch immediately, state=in-flight, rounds++
       elif state[src]==in-flight: queue (de-dup)
       else: defer (round-cap or deadline truncated)
  3. Re-dispatch returns → if queue non-empty AND rounds<N AND wall-budget remaining: merge queue, fire next round; else: idle, queued items become deferred.
  4. Cross-cutting checks (type-check/lint/build/browser) run once all primaries + re-dispatch chains across all quartets settle. Best dispatched via `frontend-backend:type-build-runner` so they run in parallel with the last in-flight re-dispatches.

For multi-domain runs (N>1), Message 1 has 4N Agent calls — all in one message.

Auto-promotion of round-cap-truncated findings

Findings tagged round-cap-truncated (NOT deadline-truncated) auto-promote into round-1 of the next orchestrator turn for the same source agent, max 2 promotion cycles per finding-id. Counter persists in manifest.json keyed by finding-id. After 2 cycles → surface as Open findings — escalated. Deadline-truncated findings surface immediately (don't auto-promote — slow source isn't solved by re-firing).

Available primaries

Subagent	Use for
Explore	Read-only code search — usually a helper, rarely primary.
general-purpose	Multi-step research/work that doesn't fit a specialist.
feature-dev:code-explorer	Default Deep Explorer.
feature-dev:code-architect	Designing a feature blueprint.
feature-dev:code-reviewer	Default Deep Validator.
frontend-backend:mistake-monitor	Mandatory Mistake Monitor.
frontend-backend:visual-verify-observer	Default primary for browser-verify quartets. Seven-axis visual matrix.
frontend-backend:perf-auditor	Default primary for perf-grounded tasks. Core Web Vitals via Chrome MCP.
frontend-backend:type-build-runner	Cross-cutting gate runner. Dispatched in parallel with re-dispatch chain.
frontend-backend:db-guardian	DB setup, schema design, RLS, every migration. Sole DB writer.
frontend-backend:dept-verifier	Federation department member (visual/functional/console/network/dom/security/storage/realtime/seo/i18n/mobile_touch/pwa/analytics/cross_page). Dispatched by verify-coordinator.
frontend-backend:verify-coordinator	Federation conductor — dispatched by comprehensive-verify skill.
Project-registered domain primaries	Slot in via Agent introspection or user config. Use general-purpose with role-specific prompt when none match.

Conflict prevention

Helpers are read-only — intra-quartet conflict zero. Inter-quartet checks:

1. List files each PRIMARY will touch. Same path in two primaries → not independent. Collapse, sequence, or carve a preliminary quartet for shared helper.
2. List DB rows each primary will mutate. Same row in two primaries → not independent.
3. List migrations each primary will write. Two on same table → sequence or merge.

Integration phase (streaming, not batched)

1. Per-helper instant. Background helper returns BLOCKING/HIGH AND primary diff is in hand → fire source agent's re-dispatch in same turn. Don't wait for other helpers.
2. Mistake-monitor re-dispatch loop. Per BLOCKING/HIGH finding, re-dispatch source in ONE message with explicit fix list. N=3 cap.
3. Cross-quartet diff. Confirm zero file overlap.
4. Cross-cutting checks (once): npm run type-check + lint + build (if build-affecting) + knip:check (if exports touched).
5. Final mistake-monitor sweep — only when ≥ 2 quartets ran. ONE pass against combined diff for seam issues.
6. Browser verification — tiered. UI changed → frontend-backend:browser-verify. T1 = smoke. T2/T3 = comprehensive-verify federation.
7. Adjacent-page smoke (production-safety).
8. Commit per logical unit. One commit per primary's domain.

Common patterns

Pattern A — N broken Sentry issues

One quartet per issue. Each primary starts with Sentry MCP analyze_issue_with_seer.

Pattern B — Multi-page pixel-perfect after design-token change

One quartet per route. Primary = visual-verify-observer. Re-dispatch source agent named in each reDispatchTo until zero 🔴 zones.

Pattern C — Independent schema mismatches

One quartet per table. Primary = domain auditor or general-purpose. Validator audits naming + RLS + gotcha hits. Monitor catches FE↔BE drift.

Pattern D — Multi-area cleanup sweep

One quartet per area. Primary = general-purpose running knip + dead-code. Explorer confirms nothing referenced from outside scope.

Pattern E — Department federation (T2/T3 browser verification)

Dispatch via frontend-backend:comprehensive-verify → verify-coordinator fans out 6 (T2) or 15 (T3) dept-verifier instances + visual-verify-observer (visual dept) + perf-auditor (performance dept) in ONE message, all run_in_background: true, each with assigned tabId. De-dup key extends to (file, line-range, category, department).

Anti-patterns

• Quartet for a one-line fix (T0 inline, T1 primary alone).
• Skipping mistake-monitor on T2/T3.
• Orchestrator silently fixing monitor's findings (source agent should own its mistakes).
• Spawning agents serially across turns.
• Helpers writing.
• Vague prompts ("fix the page") — quote error, list paths, name verification gate.
• Skipping primary pre-flight (two primaries on same file = avoidable merge conflict).
• Verifying only one of N changed pages.
• Bare verification claims.

Reporting

## Parallel dispatch — <topic> @ <commit>

| Domain | Primary | Explorer | Validator | Monitor | Rounds | Files | Screenshots |
| ------ | ------- | -------- | --------- | ------- | ------ | ----- | ----------- |
| <r-A>  | <p>     | 7 deps   | 2/0 open  | 3/0 open | 1     | 3     | 4 uploaded  |

Cross-cutting:
- type-check ✅ | lint ✅ | build ✅ | knip ✅
- adjacent smoke: <list> ✅
- final mistake-monitor sweep: ✅ clean
- conflicts: none

Per-quartet root causes:
1. <one line>

Mistake-monitor re-dispatch summary:
- <quartet>: <N findings → re-dispatched <agent> → ✅ clean>