| name | parallel-dispatch |
| description | Parallel worker dispatch for the Build node — task grouping rules (disjoint file paths, max 4 groups, domain split), worktree lifecycle, sequential merge strategy |
| allowed-tools | ["Agent","Bash","Read","Glob","Grep"] |
Parallel Dispatch — Concurrent Worker Execution
Overview
Parallel dispatch is the Build node's task execution layer. The Build node dispatches up to 4 concurrent cks:prd-executor-worker agents, each in a git worktree with disjoint file domains. All agents run in a single message (concurrent). Results are merged sequentially back into the feature branch. This isolates workers from each other, prevents merge conflicts during concurrent editing, and enables parallel development at scale.
Task Grouping Rules
Groups MUST have no shared file paths. Disjointness is enforced at the file level, not directory level.
Max 4 groups per dispatch — this is a hard message limit. Agent message count cannot exceed 4 agents per message.
Default domain split when PLAN.md grouping is ambiguous:
- Domain A:
tools/, scripts/, .claude-plugin/
- Domain B:
agents/, pipelines/
- Domain C:
commands/
- Domain D:
docs/, skills/, .github/
If two groups share a domain but touch different files, they are safe to parallelize. Example: Group 1 modifies commands/foo.md and Group 2 modifies commands/bar.md — disjoint files, parallel-safe.
If grouping is unclear after checking PLAN.md, default to 2 groups: backend/tools (Domains A+B) vs commands/docs (Domains C+D). Never leave grouping implicit — always validate disjointness before dispatch.
Worktree Lifecycle
Step-by-step execution of parallel workers:
1. Dispatch Phase
Runner calls Agent(subagent_type="cks:prd-executor-worker", isolation="worktree", prompt=taskGroup) for each group — ALL in one message. Workers execute concurrently.
2. Worker Phase
Each worker has its own isolated worktree; it cannot see or touch other workers' files. Worker is independent: it reads its own code, writes/commits its own changes, generates SUMMARY.md, and returns to the runner.
3. Collection Phase
Runner reads each SUMMARY.md from completed workers. Collects results in memory.
4. Merge Phase
For each worktree with changes: merge branch into feature branch (sequential, one at a time). For each worktree with no changes: auto-cleaned (no branch created, no merge needed).
5. State Recording Phase
Runner updates PRD-STATE worktree_summaries array with all merge results: which worktrees succeeded, which failed, which had no changes.
Sequential Merge Strategy
Merges happen ONE AT A TIME after all workers complete. Order: merge group 1, then group 2, then group 3, then group 4.
Why sequential: Parallel merges cause branch conflicts. If Worker A and Worker B both try to update the feature branch at the same instant, git will reject one of the merges. Sequential execution prevents this entirely.
On conflict: When a merge fails (two workers unknowingly touched the same file): log the conflict, mark mergeStatus: "conflict" in that worktree's summary entry, skip that branch, and continue with the next merge. Runner continues with partial results — a failed worker does not block other merges. The team lead resolves conflicts manually after the build node completes.
Common Rationalizations
| Rationalization | Reality |
|---|
| "These two groups touch the same directory, that's close enough to disjoint" | Directory ≠ file. Two groups touching commands/foo.md and commands/bar.md are safe. Two groups both touching commands/foo.md are not. |
| "I can dispatch 6 workers, the limit is per message not per node" | Max 4 per message is a hard limit. Collapse excess groups. |
| "I'll merge all worktrees at once to save time" | Parallel merges cause conflicts. Always sequential. |
| "The PLAN.md doesn't specify groups, I'll figure it out at runtime" | Default to Domain A+B vs C+D split. Never leave grouping implicit. |
| "A worker with no changes still needs a merge step" | No-change worktrees are auto-cleaned. No merge, no PR. |
Verification
