dispatching-parallel-agents

name	dispatching-parallel-agents
description	Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. Triggers: parallel agents, dispatch subagents, independent failures, multiple test files, 并行任务, 分派子代理.

Dispatching Parallel Agents

Overview

• Delegate each task to a specialized agent with isolated context.
• Write self-contained instructions; do not pass your full session history—supply only what that agent needs.
• Keep your own context available for coordination across agents.
• Core principle: Dispatch one agent per independent problem domain; run them concurrently when their work is independent.

When to Use

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

Use when:

• 3+ test files failing with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• No shared state between investigations

Don't use when:

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

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

Dispatch all agents in a single message using Cursor's Task tool. Choose subagent_type based on task nature: "generalPurpose" for code investigation/fixes, "shell" for build/test/git operations, "explore" for codebase search tasks. Default example with "generalPurpose":

Agent	Scope
1	Fix agent-tool-abort.test.ts
2	Fix batch-completion-behavior.test.ts
3	Fix tool-approval-race-conditions.test.ts

All three run concurrently when dispatched in the same message.

4. Review and Integrate

When agents return:

1. Read each summary
2. Verify fixes don't conflict
3. Run full test suite
4. Integrate all changes

After all agents return, use the AskQuestion tool:

• title: "Parallel Agents Complete"
• question prompt: "All {N} agents have returned:\n{brief summary of each agent's result}\n\nConflicts detected: {yes/no}"
• options:
  • "Integrate all changes"
  • "Review each agent's changes individually first"
  • "Discard agent {N}'s changes (I'll explain)"
  • "Run full test suite before deciding"

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"

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