parallel-dispatch

# Parallel Dispatch Safe parallel execution of multiple agents within the same domain. This skill defines the **safety invariants** — the constraints that, if maintained, guarantee conflict-free merges by construction. > **Recursive by design.** These invariants apply at every nesting depth. A `@backend-engineer[auth]` that spawns sub-subagents for `[auth-login]` and `[auth-registration]` must apply the same decomposition, ownership, and merge rules internally. ## When to Invoke - Before dispatching multiple instances of the same agent type within a primitive - When any agent (at any depth) needs to parallelize its own workload across sub-subagents - When re-planning after a sub-task failure ## 1. Decomposition Break work into parallelizable, MECE sub-tasks. Each gets a **scope card**. ### Protocol 1. **Inventory** — List all concrete deliverables (files, modules, endpoints, tests) 2. **Cluster by feature** — Group by vertical feature slice, not technical layer 3. **MECE validate** — No file in two clusters. No deliverable unassigned. 4. **Dependency scan** — Mark `hard` (blocks) vs `soft` (beneficial but not blocking) dependencies 5. **Produce scope cards** 6. **Cap check** — >5 instances of same agent type → prompt user **Critical anti-pattern:** Layer-based decomposition (`handlers/`, `services/`, `repos/`) creates cross-cutting dependencies. Always use feature-based clustering (`auth/`, `tasks/`, `notifications/`). ### Scope Card Format ```markdown ### Scope Card: @<agent-type>[<scope>] - **Deliverables**: <list of concrete outputs> - **Write Scope**: <glob pattern for exclusive write access> - **Shared Reads**: <glob patterns for read-only access> - **Hard Dependencies**: <scope cards that must complete first> - **Soft Dependencies**: <scope cards that are beneficial but not blocking> ``` Rules: - Every card has at least one concrete deliverable - Every card has a write scope (glob pattern) - Write scopes between agents MUST be disjoint - Scope names use kebab-case: `[auth]`, `[task-crud]`, `[user-profile]` - Empty scope cards are invalid — merge with adjacent cluster ### Recursive Decomposition When an agent receives a scope card and the work is still too broad: 1. Further decompose the scope card into sub-scope cards 2. Apply the same MECE/ownership rules within the narrower boundary 3. The parent's write scope becomes the ceiling — children cannot write outside it 4. Children inherit shared reads from parent plus parent's own outputs ``` @backend-engineer[auth] ← scope card from orchestrator └─ @backend-engineer[auth-login] ← sub-scope card (self-decomposed) └─ @backend-engineer[auth-register] ← sub-scope card (self-decomposed) └─ @backend-engineer[auth-integration] ← wires sub-features together ``` **Agent Spawn Protocol for sub-agents:** When spawning sub-agents that have role files in `.agents/agents/`, use `TypeName="self"` with a descriptive `Role` name and reference the role file in their system prompt: `"Your role, domain, skills, boundaries, and protocols are defined in file://{workspace}/.agents/agents/{agent-type}.md. Read this file FIRST."` Never paraphrase the role file from memory. ## 2. Ownership The safety invariant: **one writer per file**. If ownership is valid, merges are conflict-free by construction. ### Three Zones | Zone | Access | Mutability | |---|---|---| | **Exclusive Write** | Read + Write by exactly one sub-task | Mutable only by owner | | **Shared Read** | Read by any sub-task | Immutable during BUILD | | **Contracts Layer** | Read by all BUILD agents | Produced by DESIGN, frozen for BUILD | > When contracts are authored using the `structured-spec` standard, the generated manifest (`specification.md` §7-8) provides machine-parseable work package partitioning by contract ID, contract type, requirement closure, or stack category. See `structured-spec/specification.md` §8 (Multi-Agent Slicing). If a BUILD agent discovers a contract needs changes → **STOP and escalate** for DESIGN revision. Never silently modify frozen contracts. ### Integration Sub-Task Aggregation files (routers, registries, main entry points, config) inherently collect contributions from multiple features. Handle with a dedicated `[integration]` sub-task: - Runs **after** all parallel sub-tasks for its agent type - Owns **only** aggregation files - Merges **last** This pattern applies recursively — a deeply nested agent that parallelizes can have its own integration sub-task. ### Ownership Matrix Before dispatch, build a matrix from scope cards: ```markdown | Sub-Task | Write Scope (exclusive) | Shared Reads | |----------|------------------------|--------------| | @agent[scope-1] | `features/<scope-1>/**` | `types/**`, `config/**` | | @agent[scope-2] | `features/<scope-2>/**` | `types/**`, `config/**` | | @agent[integration] | `router/**`, `main.*` | All feature dirs (read-only) | ``` Validate before dispatch: - Write scopes are **disjoint** (zero file overlap between writers at same level) - Write scopes are **exhaustive** (every file that needs modification is owned) - No BUILD agent writes to contracts layer - Integration sub-tasks are at a later DAG level than their parallel peers ## 3. Execution ### DAG Levels Group scope cards into levels by dependency depth: - **Level 0**: No dependencies — dispatch in parallel - **Level N**: All dependencies satisfied by levels 0 through N-1 All nodes at the same level are independent — dispatch in parallel. Between levels: merge completed branches, run quality gate, then proceed to next level. If a node fails: Retry once with failure context → re-assign to different specialist → escalate to parent coordinator. If failure changes scope, re-decompose the affected sub-tree only — already-completed nodes outside the failure are preserved. ### Merge Order Within a level, merge in this priority: 1. **Dependency order** — merge nodes that downstream work depends on first 2. **Smallest diff first** — for independent nodes, merge smaller changes first (less conflict surface) 3. **Integration last** — `[integration]` sub-tasks always merge after feature branches ### Conflict Classification | Type | Description | Resolution | |---|---|---| | **Textual** | Same line modified by two branches | Analyze intent, pick correct or combine | | **Semantic** | Different changes that interact logically | Requires understanding both; may need new code | | **Structural** | File reorganization conflicts | Re-apply changes on new structure | | **Integration** | Both add routes/config entries | Combine additions, order by convention | > If the same conflict pattern repeats across merges, the **decomposition was flawed** — re-decompose, don't keep patching conflicts. ## 4. Read-Only Agents Read-only agents (scout, reviewer, security-engineer, ux-craftsman, incident-responder) use MECE scoping for **coverage guarantees**, not conflict prevention: - Each instance covers a disjoint area - Union covers 100% of relevant scope - No merge step — they produce documents/findings passed as context to downstream agents ## Anti-Patterns | Anti-Pattern | Why It Fails | Fix | |---|---|---| | Layer-based decomposition | Cross-cutting deps, every sub-task touches every feature | Feature-based clustering | | Shared write access | Merge conflicts guaranteed | One writer per file, extract to contract layer | | Scope too small (<1 file) | Overhead exceeds benefit | Merge into adjacent cluster | | Scope too broad (entire domain) | No parallelism gained | Break into feature slices | | Decomposing without DESIGN output | No contracts → incompatible assumptions | DESIGN before BUILD decomposition | | Modifying frozen contracts in BUILD | Downstream agents built against wrong interface | STOP, escalate for DESIGN revision | | Skipping MECE validation | Gaps → missed work, overlaps → conflicts | Always validate before dispatch | ## 5. Hierarchical Decomposition When work spans multiple scope cards, decompose into coordinator subtrees — not a flat fan-out of executors. ### Decision: Flat vs. Hierarchical | Signal | Dispatch Model | |---|---| | ≤5 scope cards, single domain | Flat (direct builder dispatch) | | >5 scope cards OR multi-domain | Hierarchical (@tech-lead per domain) | | Cross-cutting dependencies between domains | Hierarchical with @tech-lead[integration] | ### Coordinator Pattern A coordinator agent (@overseer, @conductor, @tech-lead): 1. Owns a subtree of executors 2. Has its own `.agentwork/brief.md`, `.agentwork/handoff.md` lifecycle 3. Reports upward to its parent coordinator, not to the root 4. Never writes production code (Tech-Lead may write integration/wiring code) ### Nesting Budget — 4 Layers Max | Layer | Role | Max Agents | |---|---|---| | 0 | @overseer (pipeline supervisor) | 1 | | 1 | @conductor | 1 | | 2 | @tech-lead / builders / @reviewer / @red-team-lead | As needed | | 3 | Specialists within tech-lead or red-team-lead | As needed | Total budget: **4 layers max** (L0 supervisor + 3 active layers). Recommended: **3** for typical features (Overseer → Conductor → Builders). ### Workspace Strategy by Layer | Layer | Workspace Mode | Rationale | |---|---|---| | 0 | `inherit` | Overseer reads the main workspace | | 1 | `inherit` | Conductor reads the main workspace | | 2 (writers) | `inherit` or `share` | Tech-Lead and builders share workspace | | 2 (readers) | `inherit` | Reviewer and scouts read the workspace | | 3 | `inherit` | Specialists within tech-lead/red-team share workspace | ### Integration Between Scope Cards After all scope cards pass their individual checks: 1. @conductor dispatches @tech-lead[integration] with all card handoffs 2. @tech-lead[integration] owns aggregation files (routers, registries, configs) 3. Integration runs on the main workspace 4. A final @reviewer runs cross-card verification before completion ## 6. Scope Sizing & Integration Points ### Scope Sizing Heuristics | Signal | Action | |---|---| | Scope card requires **>4 workers** | Too large — split into sub-cards | | Scope card is **1 worker editing ≤3 files** | Too small — merge with adjacent card | | Scope card spans **>8 files** | Too broad — find a natural seam to split | | Scope card touches **<1 file** | Phantom card — remove or merge | **Sweet spot:** 3–8 files per scope card, 1–3 workers, completable by 1 tech-lead with ≤4 specialists. ### Integration Point Identification Integration points are where scope cards touch each other: - Shared API contracts (request/response types, proto files) - Database schemas and migrations - Event bus topics and message formats - Configuration files and environment variables Rules: 1. Identify ALL integration points **before** dispatch — never discover them mid-build 2. Assign integration work to `@tech-lead[integration]`, which runs **after** all scope cards pass 3. Shared contracts are **read-only during BUILD** — no scope card may modify a shared contract unilaterally 4. If a contract needs changes, **STOP and escalate** to the coordinator for re-planning