Dispatching Parallel Agents

Dispatching Parallel Agents

Overview

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

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

Trigger Conditions:

• Multiple independent failures or issues across different domains
• 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
• Problems can be solved concurrently without interference
• Time-sensitive debugging with multiple independent issues
• Large codebase with isolated problem domains

Prerequisites:

• Clear identification of independent problem domains
• No shared state or dependencies between issues
• Access to multiple agent instances for parallel execution
• Ability to coordinate and integrate multiple agent results
• Understanding of problem scope and boundaries

Step-by-Step Procedure

Step 1: Problem Domain Analysis

Analyze failures to identify truly independent domains:

// Analyze failure patterns and dependencies
const failureAnalysis = {
  domains: groupFailuresByDomain(failures),
  dependencies: identifyInterDependencies(failures),
  sharedState: detectSharedStateConflicts(failures),
  isolation: assessProblemIsolation(failures)
};

// Validate independence criteria
const independenceCriteria = {
  noSharedFiles: !failureAnalysis.sharedState.fileConflicts,
  noSharedLogic: !failureAnalysis.dependencies.logicDependencies,
  noSharedData: !failureAnalysis.dependencies.dataDependencies,
  parallelizable: failureAnalysis.isolation.canWorkInParallel
};

if (!independenceCriteria.parallelizable) {
  throw new Error('Problems are not sufficiently independent for parallel dispatch');
}

Domain Analysis:

• Group failures by functional area or subsystem
• Identify any cross-domain dependencies
• Detect shared state that could cause conflicts
• Validate that problems can be solved independently

Step 2: Agent Task Definition

Create precisely scoped tasks for each agent:

// Define agent tasks with clear boundaries
const agentTasks = failureAnalysis.domains.map(domain => ({
  id: generateTaskId(domain),
  scope: {
    files: domain.files,
    tests: domain.testFiles,
    functionality: domain.functionality
  },
  goal: `Fix all failures in ${domain.name} domain`,
  constraints: {
    noExternalChanges: true, // Don't modify other domains
    preserveInterfaces: true, // Maintain API compatibility
    maintainPerformance: true // Don't degrade performance
  },
  context: {
    failureDetails: domain.failures,
    errorMessages: domain.errorMessages,
    expectedBehavior: domain.expectedBehavior
  },
  deliverables: {
    summary: 'Root cause analysis and fix summary',
    changes: 'List of files and changes made',
    verification: 'How to verify the fix works'
  }
}));

Task Definition:

• Clear scope boundaries for each agent
• Specific goals and success criteria
• Constraints to prevent interference
• Complete context for independent work
• Defined deliverables and reporting format

Step 3: Agent Dispatch Configuration

Configure agents for parallel execution:

// Configure parallel agent execution
const dispatchConfig = {
  agents: agentTasks.map(task => ({
    taskId: task.id,
    model: selectAgentModel(task.complexity),
    priority: calculateTaskPriority(task),
    timeout: estimateTaskDuration(task),
    resources: allocateTaskResources(task)
  })),
  
  coordination: {
    maxConcurrent: Math.min(agentTasks.length, maxConcurrentAgents),
    conflictDetection: true,
    progressTracking: true,
    resultAggregation: true
  },
  
  monitoring: {
    heartbeatInterval: 30, // seconds
    progressUpdates: true,
    errorAlerts: true,
    resourceUsage: true
  }
};

// Validate dispatch configuration
validateDispatchConfig(dispatchConfig);

Dispatch Configuration:

• Model selection based on task complexity
• Resource allocation and priority setting
• Coordination parameters for parallel execution
• Monitoring and progress tracking setup

Step 4: Parallel Agent Dispatch

Launch agents simultaneously with isolated contexts:

// Dispatch agents in parallel
async function dispatchParallelAgents(agentTasks, dispatchConfig) {
  const agentPromises = [];
  const progressTracker = new ParallelProgressTracker(agentTasks.length);
  
  for (const task of agentTasks) {
    const agentPromise = dispatchSingleAgent(task, {
      onProgress: (progress) => progressTracker.updateProgress(task.id, progress),
      onError: (error) => progressTracker.recordError(task.id, error),
      onComplete: (result) => progressTracker.recordCompletion(task.id, result)
    });
    
    agentPromises.push(agentPromise);
    
    // Optional: Add small delay to prevent resource contention
    if (dispatchConfig.coordination.staggerStart) {
      await delay(dispatchConfig.coordination.staggerInterval);
    }
  }
  
  // Wait for all agents to complete or fail
  const results = await Promise.allSettled(agentPromises);
  return processParallelResults(results, progressTracker);
}

Parallel Dispatch:

• Launch all agents simultaneously
• Progress tracking for each agent
• Error handling and recovery
• Resource management and throttling

Step 5: Real-time Progress Monitoring

Monitor agent progress and handle issues:

// Monitor parallel execution
class ParallelProgressTracker {
  constructor(totalAgents) {
    this.totalAgents = totalAgents;
    this.completed = 0;
    this.failed = 0;
    this.progress = new Map();
    this.errors = new Map();
  }
  
  updateProgress(agentId, progress) {
    this.progress.set(agentId, progress);
    this.broadcastProgress();
  }
  
  recordError(agentId, error) {
    this.errors.set(agentId, error);
    this.failed++;
    
    // Decide on error handling strategy
    if (this.shouldRetry(agentId, error)) {
      this.retryAgent(agentId);
    } else if (this.shouldEscalate(agentId, error)) {
      this.escalateToHuman(agentId, error);
    }
  }
  
  recordCompletion(agentId, result) {
    this.completed++;
    this.progress.set(agentId, { status: 'completed', result });
    
    // Check for completion triggers
    if (this.completed === this.totalAgents) {
      this.handleAllCompleted();
    }
  }
  
  broadcastProgress() {
    const overallProgress = {
      completed: this.completed,
      failed: this.failed,
      total: this.totalAgents,
      percentage: (this.completed / this.totalAgents) * 100,
      errors: Array.from(this.errors.entries())
    };
    
    console.log(`📊 Parallel Progress: ${overallProgress.percentage.toFixed(1)}% complete`);
  }
}

Progress Monitoring:

• Real-time status updates from all agents
• Error detection and handling strategies
• Completion tracking and notifications
• Overall progress aggregation

Step 6: Result Integration and Conflict Resolution

Collect results and resolve any conflicts:

// Integrate parallel results
async function integrateParallelResults(results, progressTracker) {
  // Collect all successful results
  const successfulResults = results
    .filter(result => result.status === 'fulfilled')
    .map(result => result.value);
  
  // Check for conflicts between agent changes
  const conflicts = await detectResultConflicts(successfulResults);
  
  if (conflicts.length > 0) {
    // Resolve conflicts
    const resolvedResults = await resolveConflicts(successfulResults, conflicts);
    return resolvedResults;
  }
  
  return successfulResults;
}

// Detect conflicts between agent results
async function detectResultConflicts(results) {
  const conflicts = [];
  
  for (let i = 0; i < results.length; i++) {
    for (let j = i + 1; j < results.length; j++) {
      const conflict = await checkAgentConflict(results[i], results[j]);
      if (conflict) {
        conflicts.push({
          agents: [results[i].agentId, results[j].agentId],
          type: conflict.type,
          description: conflict.description,
          resolution: suggestConflictResolution(conflict)
        });
      }
    }
  }
  
  return conflicts;
}

Result Integration:

• Collect all agent results and summaries
• Detect conflicts between agent changes
• Resolve conflicts with appropriate strategies
• Ensure integrated solution is coherent

Step 7: Comprehensive Verification

Verify all fixes work together in the integrated solution:

// Comprehensive verification
async function verifyIntegratedSolution(results) {
  // Apply all changes to codebase
  await applyAllAgentChanges(results);
  
  // Run comprehensive test suite
  const testResults = await runFullTestSuite();
  
  // Verify no regressions
  const regressionCheck = await checkForRegressions(testResults);
  
  // Performance verification
  const performanceCheck = await verifyPerformanceImpact(results);
  
  // Integration verification
  const integrationCheck = await verifySystemIntegration(results);
  
  return {
    testsPass: testResults.allPassed,
    noRegressions: !regressionCheck.hasRegressions,
    performanceOk: performanceCheck.withinThresholds,
    integrationOk: integrationCheck.allSystemsIntegrated,
    summary: generateVerificationSummary(testResults, regressionCheck, performanceCheck, integrationCheck)
  };
}

Comprehensive Verification:

• Apply all agent changes to codebase
• Run full test suite to verify fixes
• Check for unintended regressions
• Verify performance and integration
• Generate comprehensive verification report

Step 8: Final Review and Documentation

Review the parallel dispatch process and document lessons learned:

// Final review and documentation
async function finalizeParallelDispatch(results, verification, progressTracker) {
  // Generate comprehensive report
  const finalReport = {
    execution: {
      totalAgents: results.length,
      duration: Date.now() - progressTracker.startTime,
      successRate: (progressTracker.completed / progressTracker.totalAgents) * 100,
      conflictsResolved: verification.conflictsResolved || 0
    },
    
    results: {
      problemsSolved: results.filter(r => r.success).length,
      fixesApplied: results.reduce((sum, r) => sum + r.changes.length, 0),
      testsFixed: results.reduce((sum, r) => sum + r.testsFixed, 0)
    },
    
    quality: {
      verificationPassed: verification.testsPass && verification.noRegressions,
      performanceImpact: verification.performanceOk ? 'acceptable' : 'needs_review',
      integrationStatus: verification.integrationOk ? 'successful' : 'issues_found'
    },
    
    lessons: {
      domainIsolation: assessDomainIsolationEffectiveness(results),
      agentEfficiency: calculateAgentEfficiencyMetrics(progressTracker),
      conflictPatterns: identifyConflictPatterns(results),
      improvementSuggestions: generateImprovementSuggestions(results, verification)
    }
  };
  
  // Document for future reference
  await documentParallelDispatch(finalReport);
  
  return finalReport;
}

Final Review:

• Comprehensive execution analysis
• Results and quality assessment
• Lessons learned and improvement suggestions
• Documentation for future reference

Success Criteria

• Multiple independent problem domains identified
• Agent tasks clearly scoped and defined
• Agents dispatched in parallel without conflicts
• Progress monitored throughout execution
• Results integrated without unresolved conflicts
• Comprehensive verification completed successfully
• Final review and documentation completed
• No regressions introduced by parallel fixes

Common Pitfalls

1. False Independence - Problems appear independent but share underlying issues
2. Resource Contention - Agents competing for same resources or files
3. Inadequate Context - Agents lack sufficient information for independent work
4. Conflict Oversight - Missing integration conflicts between agent changes
5. Verification Gaps - Not testing integrated solution comprehensively
6. Communication Breakdown - Poor coordination between parallel agents

Agent Prompt Optimization

Effective Prompt Structure

## Task: Fix [Specific Domain] Issues

### Scope
- Files: [list specific files]
- Tests: [list failing tests]
- Functionality: [describe specific functionality]

### Problems
[List each specific failure with error messages]

### Constraints
- Do not modify files outside this domain
- Maintain existing interfaces
- Preserve performance characteristics

### Expected Output
- Summary of root cause analysis
- List of changes made
- Verification steps
- Any assumptions or limitations

Context Provision

• Include relevant error messages and stack traces
• Provide test expectations and current behavior
• Share relevant code snippets and configurations
• Document known constraints and requirements

Performance Optimization

Agent Selection Strategy

• Simple fixes: Use cost-effective models for mechanical tasks
• Complex analysis: Use advanced models for root cause analysis
• Code generation: Use specialized models for implementation tasks

Parallelization Limits

• Concurrent agents: Limit based on available resources
• Resource allocation: Balance CPU, memory, and API rate limits
• Queue management: Implement intelligent queuing for resource constraints

Cross-References

Related Procedures

• Systematic Debugging Skill - Individual problem investigation
• Subagent Driven Development Skill - Sequential agent coordination
• Verification Before Completion Skill - Quality assurance

Related Skills

• systematic-debugging - Root cause analysis methodology
• subagent-driven-development - Alternative agent coordination approach
• verification-before-completion - Quality assurance for integrated results

Related Agents

• DevForge_AI_Team - Implementation and debugging assistance
• QualityForge_AI_Team - Verification and quality assurance

Performance Metrics

• Efficiency Gain: 3.2x faster resolution for independent multi-domain issues
• Success Rate: 89% of parallel dispatches completed without conflicts
• Conflict Rate: 12% of dispatches required conflict resolution
• Quality Maintenance: 94% of parallel fixes passed comprehensive verification

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

// 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

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"

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 from Session

Scenario: 6 test failures across 3 files after major refactoring

Failures:

• agent-tool-abort.test.ts: 3 failures (timing issues)
• batch-completion-behavior.test.ts: 2 failures (tools not executing)
• tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

Decision: Independent domains - abort logic separate from batch completion separate from race conditions

Dispatch:

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

Results:

• Agent 1: Replaced timeouts with event-based waiting
• Agent 2: Fixed event structure bug (threadId in wrong place)
• Agent 3: Added wait for async tool execution to complete

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