Parallel Agents

Pattern 2: Staged Pipeline (Serial Stages, Parallel within Stage)

For workflows with dependencies between phases:

// Stage 1: Research (all independent — run in parallel)
const [requirements, bestPractices, existingCode] = await Promise.all([
  task({ description: "Analyze requirements from specs/", subagent_type: "researcher" }),
  task({ description: "Research best practices for auth implementation", subagent_type: "researcher" }),
  task({ description: "Audit existing auth code for issues", subagent_type: "security" }),
]);

// Stage 2: Implementation (depends on Stage 1 results — can still partially parallelize)
const [coreImpl, tests] = await Promise.all([
  task({
    description: `Implement auth based on: ${requirements} and ${bestPractices}`,
    subagent_type: "coder"
  }),
  task({
    description: `Write test cases for auth based on requirements: ${requirements}`,
    subagent_type: "testing"
  }),
]);

// Stage 3: Validation (depends on Stage 2)
const validationResult = await task({
  description: `Validate the implementation against tests: impl=${coreImpl}, tests=${tests}`,
  subagent_type: "validator"
});

Pattern 3: Map-Reduce for Large Codebases

When processing a large number of independent files:

// Map: process each module independently
const moduleResults = await Promise.all(
  modules.map(module => task({
    description: `Refactor ${module.path} to use async/await instead of callbacks. Rules: [...]`,
    subagent_type: "coder"
  }))
);

// Reduce: combine all refactored modules
const summary = await task({
  description: `Review and integrate these refactored modules: ${moduleResults.join('\n')}`,
  subagent_type: "validator"
});

Pattern 4: Speculative Execution

When uncertain which approach will work:

// Try multiple approaches in parallel, use the first one that succeeds
const [approach1, approach2] = await Promise.allSettled([
  task({
    description: "Fix the failing test using approach A: mock the database",
    subagent_type: "coder"
  }),
  task({
    description: "Fix the failing test using approach B: use in-memory SQLite",
    subagent_type: "coder"
  }),
]);

// Use whichever succeeded, or evaluate both

📊 Dependency Analysis — Critical Step

Before parallelizing, map out task dependencies:

Task dependency graph:
A ──┐
B ──┼──> E ──> F (final)
C ──┘
D ─────────────> F

Execution plan:
- Round 1 (parallel): A, B, C, D
- Round 2 (serial):   E (needs A, B, C)
- Round 3 (serial):   F (needs D + E)

Max parallelism: 4 concurrent tasks in Round 1

Dependency detection questions:

1. Does task X need OUTPUT from task Y? → Serial
2. Does task X WRITE to a resource that task Y READS? → Serial or conflict
3. Are tasks X and Y completely independent? → Parallel ✅

🚦 When NOT to Parallelize

💡 Passing Context Between Parallel Tasks

When parallel tasks need shared context, pass it in the task description:

// Prepare shared context ONCE before fan-out
const sharedContext = `
  Project: ${projectName}
  Language: TypeScript 5.0
  Conventions: Use functional style, no classes, strict null checks
  Current branch: ${currentBranch}
`;

// Each task gets the full context
const [implResult, testResult] = await Promise.all([
  task({ description: `${sharedContext}\n\nTask: Implement the UserService`, subagent_type: "coder" }),
  task({ description: `${sharedContext}\n\nTask: Write tests for UserService`, subagent_type: "testing" }),
]);

✅ Parallel Execution Checklist

• Listed all subtasks
• Mapped dependencies between them
• Grouped independent tasks for parallel execution
• Identified serial stages where outputs feed next stage
• Ensured shared context is passed to each parallel task
• Planned fan-in synthesis step after parallel fan-out