| 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
- Inventory — List all concrete deliverables (files, modules, endpoints, tests)
- Cluster by feature — Group by vertical feature slice, not technical layer
- MECE validate — No file in two clusters. No deliverable unassigned.
- Dependency scan — Mark
hard (blocks) vs soft (beneficial but not blocking) dependencies
- Produce scope cards
- 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:
- Further decompose the scope card into sub-scope cards
- Apply the same MECE/ownership rules within the narrower boundary
- The parent's write scope becomes the ceiling — children cannot write outside it
- 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:
- Dependency order — merge nodes that downstream work depends on first
- Smallest diff first — for independent nodes, merge smaller changes first (less conflict surface)
- 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):
- Owns a subtree of executors
- Has its own
.agentwork/brief.md, .agentwork/handoff.md lifecycle
- Reports upward to its parent coordinator, not to the root
- 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:
- @conductor dispatches @tech-lead[integration] with all card handoffs
- @tech-lead[integration] owns aggregation files (routers, registries, configs)
- Integration runs on the main workspace
- 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:
- Identify ALL integration points before dispatch — never discover them mid-build
- Assign integration work to
@tech-lead[integration], which runs after all scope cards pass
- Shared contracts are read-only during BUILD — no scope card may modify a shared contract unilaterally
- If a contract needs changes, STOP and escalate to the coordinator for re-planning
