| name | Dispatching Parallel Agents |
| description | Use multiple Claude agents to investigate and fix independent problems concurrently |
| when_to_use | when facing 3+ independent failures that can be investigated without shared state or dependencies |
| version | 2.0.0 |
| progressive_disclosure | {"entry_point":{"summary":"Dispatch one agent per independent problem domain to solve multiple unrelated failures concurrently","when_to_use":"When you have 3+ independent failures in different test files/subsystems with no shared state or dependencies","quick_start":"1. Identify independent domains 2. Create focused agent tasks 3. Dispatch in parallel 4. Review summaries 5. Verify no conflicts and integrate"},"references":["coordination-patterns.md","agent-prompts.md","examples.md","troubleshooting.md"]} |
| effort | medium |
Dispatching Parallel Agents
SCOPE: ORCHESTRATOR / PM-LEVEL ONLY (#581). This skill describes the
top-level orchestrator (PM) capability to spawn parallel agents via the
Agent/Task tool. Subagents do not have access to the Agent tool and
cannot spawn sub-subagents — agent-spawning is harness-enforced at the
top level. If you are a subagent (engineer, qa, research, etc.), this skill
does not apply to you: complete your assigned scope and return results to
the PM. (This skill is intentionally not deployed to subagents; see
config/skill_to_agent_mapping.yaml.)
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 This Skill
Activate this skill when you're facing:
- 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem is self-contained - can be understood without context from others
- No shared state between investigations
- Clear domain boundaries - fixing one won't affect others
Don't use when:
- Failures are related (fix one might fix others)
- Need to understand full system state first
- Agents would interfere with each other (editing same files)
- Exploratory debugging (don't know what's broken yet)
The Iron Law
One agent, one problem domain, one clear outcome.
Never overlap scopes. Never share state. Always integrate consciously.
Core Principles
Independence is Key
Problems must be truly independent - no shared files, no related root causes, no dependencies between fixes.
Focus Over Breadth
Each agent gets narrow scope: one test file, one subsystem, one clear goal. Broad tasks lead to confusion.
Clear Output Required
Every agent must return a summary: what was found, what was fixed, what changed. No silent fixes.
Conscious Integration
Don't blindly merge agent work. Review summaries, check conflicts, run full suite, verify compatibility.
Quick Start
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
→ agent-prompts.md for prompt templates and examples
3. Dispatch in Parallel
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
→ coordination-patterns.md for dispatch strategies
4. Review and Integrate
When agents return:
- Read each summary - understand what changed
- Verify fixes don't conflict - check for same file edits
- Run full test suite - ensure compatibility
- Spot check changes - agents can make systematic errors
→ troubleshooting.md for conflict resolution
Decision Tree
Multiple failures?
└→ Are they independent?
├→ NO (related) → Single agent investigates all
└→ YES → Can they work in parallel?
├→ NO (shared state) → Sequential agents
└→ YES → Parallel dispatch ✓
Key Benefits
- Parallelization - Multiple investigations happen simultaneously
- Focus - Each agent has narrow scope, less context to track
- Independence - Agents don't interfere with each other
- Speed - N problems solved in time of 1
Navigation
Pattern Reference
Agent Management
- Agent Prompts - Prompt structure, templates, common mistakes, constraints
Learning Resources
- Examples - Real-world scenarios, case studies, time savings analysis
Problem Solving
- Troubleshooting - Conflict resolution, verification strategies, common pitfalls
Related Skills
Key Reminders
- Independence is mandatory - Related failures need single-agent investigation
- Focus beats breadth - Narrow scope per agent prevents confusion
- Always verify integration - Don't blindly merge agent work
- Clear outputs required - Every agent returns summary of changes
- Parallelization has overhead - Only worth it for 3+ independent problems
Red Flags - STOP
STOP immediately if:
- Agents are editing the same files (scope overlap)
- Fixes from one agent break another's work (hidden dependencies)
- You can't clearly separate problem domains (not independent)
- Agents return no summary (can't verify changes)
- Integration requires major refactoring (conflicts)
When in doubt: Start with one agent, understand the landscape, then dispatch if truly independent.
Integration with Other Skills
Prerequisite: Basic understanding of problem domains and test structure
Complementary: pm-workflow for coordinating multiple agents
Domain-specific: Testing skills for understanding test failures
Real-World Impact
From debugging session (2025-10-03):
- 6 failures across 3 test files
- 3 agents dispatched in parallel
- All investigations completed concurrently
- Zero conflicts between agent changes
- Time saved: 3 problems solved in parallel vs sequentially
→ examples.md for detailed case study
