parallel-agent-dispatch

What this skill does

# Parallel Agent Dispatch

Conventions that apply every time more than one agent runs in parallel.
Prevents the top failure modes observed across real multi-agent sessions:
dirty-worktree cross-contamination, context overflow mid-task, and silent
exits that require manual salvage from orphan branches.

For lookup tables, worked examples, evidence trails, and the detailed
salvage / recovery routines, see [REFERENCE.md](REFERENCE.md).

## When to Use This Skill

| Use this skill when... | Use `agent-teams` instead when... |
|---|---|
| Spawning >1 agent via plain `Agent` tool fan-out (N concurrent invocations) | Single-agent delegation or one-off subagent spawn |
| Using `TeamCreate` + teammate spawn for coordinated parallel work | A simple background task with no parallel siblings |
| Running worktree-isolated parallel implementation across repos/features | A read-only inline subagent that does not write to disk |
| Coordinating parallel investigation or audit swarms | The work fits in the current session without forking |

## Dispatch from the Main Thread When Possible

`Agent`, `TeamCreate`, and other parallel-spawn tools may not be present in a
sub-agent's sandbox even when they are available in the main conversation.
Designing a fan-out from inside a coordinating sub-agent risks silent
degradation to sequential single-thread execution — the wall-clock cost of a
5-way design landing in a 5× slower sequential mode.

When planning a parallel dispatch:

- **Default**: dispatch from the main conversation. The full tool surface is
  guaranteed.
- **Sub-agent orchestrator**: only when the team's outputs do not need to feed
  back into the main thread. Brief the sub-agent to verify tool availability up
  front and report sequential fallback as a first-class outcome (see
  `agent-teams` → "Sub-Agent Caveat: Spawn Teams from the Main Thread" for the
  detection contract).

## The Three Pillars

### 1. Worktree Preflight

Before spawning, the orchestrator must verify:

| Check | Rationale |
|-------|-----------|
| Main working tree is clean (`git status --porcelain` empty) | Agents inherit cwd; uncommitted changes cross-contaminate worktrees |
| No existing worktree at each planned path (`git worktree list`) | Nested or duplicate worktrees are the #1 source of salvage work |
| Each agent gets a **unique** branch name | Prevents commits landing on the wrong branch when cwd resolution drifts |
| Shared counters snapshot (next ADR/PRP number, feature-tracker IDs) | Prevents numbering collisions in parallel doc writes |

If any check fails, **refuse to dispatch** and report the blocker. Do not
"clean up" uncommitted user work — surface it and ask.

#### Transient worktree leaks while a wave runs

`Agent(isolation: "worktree")` is supposed to be a sealed filesystem view,
but issue [#1319](https://github.com/laurigates/claude-plugins/issues/1319)
documents a transient leak: a file the child wrote inside its worktree
briefly appears in the **parent** as an untracked entry at the same
relative path, then vanishes when the child commits. While a wave is
running, the orchestrator must:

- Treat untracked files in the parent checkout as **potentially leaked
  from a child agent**. Do not stash, restore, or commit them.
- Wait for the child's completion notification, then diff the parent's
  orphan against the child's commit. Identical contents = leak; safe to
  let the child's branch reclaim it.
- Avoid `git commit` on the parent branch while child worktree agents
  are still running — a leaked file caught by `git add -A` lands on the
  wrong branch.

`/git:coworker-check` raises the verdict `worktree_leak_suspected` when
an untracked file in the parent matches a path in any linked worktree.
Run it before every parent-side commit during a wave.

#### cwd-reset leaking git writes into the main repo

Distinct from the transient-leak shape above: issue
[#1480](https://github.com/laurigates/claude-plugins/issues/1480)
documents a git-write agent under `isolation: "worktree"` whose bare `git`
commands ran against the **main checkout**, not its worktree — the agent
thread's bash cwd reset between calls landed on the session's primary cwd
(the main repo root), so every `git fetch` / `git checkout -B` /
`git rebase --autostash` mutated `main`. Brief every git-**write** agent:

- **Never assume `cwd == worktree`.** Pin the root once
  (`git rev-parse --show-toplevel` → `$WORKTREE`) and prefix every git call with `git -C "$WORKTREE" …` — the cwd does not persist between calls.
- **Forbid bare branch-switching / autostash.** Confirm the agent is inside
  its worktree before any `git checkout -B` / `git rebase --autostash` — in
  the main repo these swallow the user's uncommitted work.

After the agent returns, run the **post-run main-repo integrity check** (see
[REFERENCE.md](REFERENCE.md) "Worktree cwd-reset guardrail (#1480)"): a changed
branch or new dirty state is silent main-repo mutation — salvage it like a
missing Return Contract before reporting done.

### 2. Scope Budget (per-agent prompt rules)

Every agent prompt must declare:

- **File scope**: exclusive write paths (glob or explicit list). No agent may
  write outside its declared scope. Out-of-scope discovery → stop and report
  (see `agent-teams`).
- **Read budget**: soft cap on files examined before producing output. A
  reasonable default is "≤10 files per exploration hop, ≤3 hops before
  returning a result."
- **Output budget**: expected length of the return summary. Discourages agents
  from echoing full file contents when a diff or line reference will do.

These budgets are what prevents the "security audit agent hit context limits"
and "prompt is too long" failure modes — without them, a well-intentioned
agent exhausts its window on exploration and truncates its actual deliverable.

#### Shared-File Exclusion List

Even when each agent's declared file scope is disjoint, a second list of
**orchestrator-only files** must be excluded from every agent's write-path.
These are the files that many agents are tempted to touch because their work
"relates to" them, and where last-writer-wins silently destroys earlier work.

Adapt this template to the repository's stack:

- Blueprint manifest (`docs/blueprint/manifest.json`) — ID registry, agents
  risk clobbering each other's pre-allocated IDs
- Per-project feature tracker (stats, phases, notes) — touched by every slab
- Top-level plan / roadmap docs — agents cite these, they do not edit them
- Build manifests (`CMakeLists.txt`, `pyproject.toml`, `package.json`,
  `Cargo.toml`, `go.mod`) — added-dependency edits are cross-cutting
- `justfile` / `Makefile` — new recipes land through the orchestrator so
  conflicting recipe names surface at review time
- Local task-queue stores (e.g. `~/.task/` for taskwarrior) — serialised
  writes, never concurrent

Every dispatched agent brief must call these out explicitly as **not in
scope**, regardless of what the agent's declared write-paths say. The
exclusion list belongs under a `### Orchestrator-only files` heading in the
brief, not buried in prose.

> Evidence: five-agent parallel dispatch, zero merge conflicts (2026-04-23).
> Before this discipline, informal dispatches suffered silent manifest clobbers
> because each agent independently "also" updated the manifest.

#### Pre-Allocated Blueprint IDs

The Worktree Preflight table's **shared counter snapshot** must expand into
**explicit per-agent ID assignment** in each brief — "Use WO-012 for this
slice. Other agents claim WO-013 and WO-014."

"Pick the next free ID" is a race condition under parallelism: two agents read
the same counter, both allocate the same number, the second commit silently
overwrites the first's manifest entry. Pre-allocation eliminates the race —
the orchestrator, running alone, is the only writer. The same discipline
applies to any shared monotonic identifier: ADR numbers, migration sequences,
feature-request codes, PRP slugs.

#### Wave Splits for