irahardianto / 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

### 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

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:

| 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

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

5. Hierarchical Decomposition

When work spans multiple scope cards, decompose into coordinator subtrees — not a flat fan-out of executors.

Decision: Flat vs. Hierarchical

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

Total budget: 4 layers max (L0 supervisor + 3 active layers). Recommended: 3 for typical features (Overseer → Conductor → Builders).

Workspace Strategy by Layer

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

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