# Dispatch Parallel Agents > Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies - Skill: `tomevault-io/dispatch-parallel-agents` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/dispatch-parallel-agents` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dispatch-parallel-agents/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/dispatch-parallel-agents --- # 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. ## When to Use ```dot 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 ## 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 Use the Task tool to dispatch multiple agents simultaneously: ``` Task("Fix UserAuthTest.php failures") Task("Fix OrderProcessingTest.php failures") Task("Fix PaymentGatewayTest.php 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? ```markdown Fix the 3 failing tests in tests/Unit/OrderProcessingTest.php: 1. "test_order_with_partial_fulfillment" - expects 'partially shipped' status 2. "test_concurrent_order_updates" - race condition on inventory count 3. "test_order_cancellation_during_processing" - expects refund to be initiated 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: - Using proper waiting mechanisms instead of arbitrary sleeps - Fixing bugs in order processing 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 OrderProcessingTest.php" - 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" ## When NOT to Use **Related failures:** Fixing one might fix others - investigate together first **Need full context:** Understanding requires seeing entire system **Exploratory debugging:** You don't know what's broken yet **Shared state:** Agents would interfere (editing same files, using same resources) ## Real Example **Scenario:** 6 test failures across 3 files after major refactoring **Failures:** - UserAuthTest: 3 failures (session timing issues) - OrderProcessingTest: 2 failures (inventory not updating) - PaymentGatewayTest: 1 failure (callback not received) **Decision:** Independent domains - auth logic separate from orders separate from payments **Dispatch:** ``` Agent 1 → Fix UserAuthTest Agent 2 → Fix OrderProcessingTest Agent 3 → Fix PaymentGatewayTest ``` **Results:** - Agent 1: Replaced sleeps with proper session state checks - Agent 2: Fixed race condition in inventory update - Agent 3: Added wait for webhook callback **Integration:** All fixes independent, no conflicts, full suite green **Time saved:** 3 problems solved in parallel vs sequentially ## Key Benefits 1. **Parallelization** - Multiple investigations happen simultaneously 2. **Focus** - Each agent has narrow scope, less context to track 3. **Independence** - Agents don't interfere with each other 4. **Speed** - 3 problems solved in time of 1 ## 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 ## Real-World Impact From debugging session (2025-10-03): - 6 failures across 3 files - 3 agents dispatched in parallel - All investigations completed concurrently - All fixes integrated successfully - Zero conflicts between agent changes --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/joshmanders) — claim your Tome and manage your conversions.