parallel-dispatch

name	parallel-dispatch
description	MECE task decomposition, file ownership enforcement, DAG-based execution, and safe merge protocol for intra-domain parallel dispatch. The safety invariants that prevent merge chaos when multiple agents write in parallel. Applies recursively at every nesting depth.

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

### 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 Definition Protocol for sub-agents: When spawning sub-agents that have role files in .agents/agents/, 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

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:

| 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