parallel-dispatch

Dispatching Parallel Agents

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"

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.

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"];
}

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 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

Common Mistakes

Too broad: "Fix all the tests" -- agent gets lost Specific: "Fix agent-tool-abort.test.ts" -- focused scope

No context: "Fix the race condition" -- agent doesn't know where Context: Paste the error messages and test names

No constraints: Agent might refactor everything Constraints: "Do NOT change production code" or "Fix tests only"

Vague output: "Fix it" -- you don't know what changed Specific: "Return summary of root cause and changes"

Parallel Dispatch Examples

Good: Independent tasks dispatched in parallel

Scenario: 6 test failures across 3 files after major refactoring.

Analysis: Abort logic, batch completion, and race condition handling are separate subsystems with no shared code paths. Fixing one cannot fix or break another.

Agent 1 -> Fix agent-tool-abort.test.ts (3 timing failures)
Agent 2 -> Fix batch-completion-behavior.test.ts (2 event structure failures)
Agent 3 -> Fix tool-approval-race-conditions.test.ts (1 async failure)

Result: All three agents return independently. Fixes don't conflict. Full suite green after integration.

Bad: Dependent tasks dispatched in parallel

Scenario: Auth module refactored. Login tests fail, and downstream API tests also fail because they depend on the auth module.

Agent 1 -> Fix login.test.ts failures
Agent 2 -> Fix api-protected-routes.test.ts failures

Why this fails: Agent 2 cannot succeed until Agent 1 fixes the auth module. The API route failures are a symptom of the auth bug, not independent problems. Agent 2 will either duplicate Agent 1's fix (conflict) or fail entirely.

Correct approach: Fix auth first (single agent), then assess whether API route failures remain.

Bad: Shared file creates conflicts

Scenario: Two agents both need to modify src/config.ts to fix their respective issues.

Agent 1 -> Fix database connection pooling (needs to change config.ts)
Agent 2 -> Fix cache TTL settings (needs to change config.ts)

Why this fails: Both agents will edit the same file. Their changes will conflict during integration. Run these sequentially instead.

Verification

After agents return:

1. Review each summary -- Understand what changed
2. Check for conflicts -- Did agents edit same code?
3. Run full suite -- Verify all fixes work together
4. Spot check -- Agents can make systematic errors