Dispatching Parallel Agents

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

Copy code
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:

Copy code
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

typescriptCopy code
// In Claude Code / AI environment
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")
// All three run concurrently

→ 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

Copy code
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

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 - N problems solved in time of 1

Navigation

Pattern Reference

• Coordination Patterns - Dispatch strategies, domain identification, integration workflows

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

• pm-workflow - PM coordination and task management
• test-driven-development - TDD patterns that benefit from parallel fixing
• verification-before-completion - Integration verification

Key Reminders

1. Independence is mandatory - Related failures need single-agent investigation
2. Focus beats breadth - Narrow scope per agent prevents confusion
3. Always verify integration - Don't blindly merge agent work
4. Clear outputs required - Every agent returns summary of changes
5. 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