/parallel-dispatch

name: parallel-dispatch
description: Dispatches concurrent agents for independent tasks. Use when 2 or more tasks can proceed without shared state or sequential dependencies, such as multiple test files that fail with different root causes or multiple subsystems that are broken independently. Applies when tasks touch different files and do not share state.

<!-- TOKEN BUDGET: 220 lines / ~660 tokens -->

Dispatching Parallel Agents

Overview

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.

<activation>

When to Use

• 2+ independent tasks that can be worked on without shared state or sequential dependencies
• 3+ test files failing with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• Multiple independent plan tasks can run concurrently

When NOT to Use

• Failures are related (fix one might fix others) -- investigate together first
• Need to understand full system state before acting
• Agents would interfere with each other (editing same files, using same resources)
• Exploratory debugging where you don't know what's broken yet

Teams vs Subagents

When Claude Code Agent Teams is enabled (`SHIPYARD_TEAMS_ENABLED=true`):

• **Teammates** are independent Claude Code instances with their own context windows. They share a task list and mailbox but NOT your conversation history.
• **Subagents** (Task tool) are spawned within your session. They share your working directory but have fresh context.

Shipyard Dispatch Pattern

Shipyard multi-agent commands (`build`, `plan`, `map`, `ship`) use a standardized detect/ask/branch flow when dispatching agents:

1. **Detect:** Check `SHIPYARD_TEAMS_ENABLED` env var (set when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) 2. **Ask:** If enabled, prompt the user via `AskUserQuestion`: "Team mode (parallel teammates)" vs "Agent mode (subagents)" 3. **Branch:** Store the choice as `dispatch_mode` (`team` or `agent`) and use it at every dispatch point 4. **Silent fallback:** If teams are not enabled, silently use agent mode with no prompt

**Team mode lifecycle (per wave):**

• `TeamCreate` with name `shipyard-{command}-phase-{N}-wave-{W}`
• `TaskCreate` for each unit of work + `TaskUpdate` to pre-assign owners
• `Task(team_name, name, subagent_type)` to spawn teammates
• Monitor via `TaskList` until all tasks reach terminal state
• `SendMessage(shutdown_request)` + `TeamDelete` for cleanup

**Key rules:**

• Single-agent steps (verifier, auditor, simplifier, documenter) always use Task dispatch regardless of mode
• Team mode provides real value only for parallel steps (multiple builders per wave, multiple reviewers per wave, multiple mappers)
• Team cleanup (shutdown + delete) is mandatory, even on error
• Pre-assign tasks before spawning to avoid race conditions

**When to choose each mode:**

• **Use team mode when:** Multiple agents work in parallel on independent tasks within the same wave (build plans, map focus areas). Each takes significant time (>5 min) and isolation prevents cross-contamination.
• **Use agent mode when:** Tasks are sequential, single-agent, or need results fed back into your current context. Also preferred when coordination is tight (same files, dependent changes).
• **When teams are NOT enabled:** This entire section has no effect — use subagents as normal.

Natural Language Triggers

• "run in parallel", "do these at the same time", "parallel tasks", "concurrent agents"

</activation>

Decision Flow

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

<instructions>

The Pattern

1. Identify Independent Domains

Group failures by what's broken:

• File A tests: Tool approval flow
• File B tests: Batch completion behavior
• File C tests: Abort functionality

Each domain is independent -- fixing tool approval doesn't affect abort tests.

2. Create Focused Agent Tasks

Each agent gets:

• **Specific scope:** One test file or subsystem
• **Clear goal:** Make these tests pass
• **Constraints:** Don't change other code
• **Expected output:** Summary of what you found and fixed

3. Dispatch in Parallel

// Claude Code — all three dispatched in the same message
Task(subagent_type: "general-purpose", prompt: "Fix agent-tool-abort.test.ts failures...")
Task(subagent_type: "general-purpose", prompt: "Fix batch-completion-behavior.test.ts failures...")
Task(subagent_type: "general-purpose", prompt: "Fix tool-approval-race-conditions.test.ts failures...")
// All three run concurrently

4. Review and Integrate

When agents return:

• Read each summary
• Verify fixes don't conflict
• Run full test suite
• Integrate all changes

Agent Prompt Structure

Good agent prompts are: 1. **Focused** -- One clear problem domain 2. **Self-contained** -- All context needed to understand the problem 3. **Specific about output** -- What should the agent return?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interru