Parallel Sub-Agent Orchestration

Launch multiple specialized Claude agents simultaneously to maximize productivity. Achieves 3-5x speedup on independent tasks like benchmarking, documentation, and analysis.

When to use

• Multiple independent tasks that can run concurrently
• Each task takes >1 minute to complete (worthwhile parallelism)
• Tasks produce concrete deliverables (files, reports, code)
• You need specialized agents (Explore for codebase analysis, general-purpose for benchmarks)
• Time-sensitive projects where speed matters

When NOT to use

• Tasks have sequential dependencies (Task B needs Task A's output)
• Quick operations (<30 seconds) - overhead not worth it
• Single task that can't be split
• When you need to iterate based on results (exploratory work)

Instructions

Step 1: Identify Parallelizable Tasks

Good candidates:

• ✅ Running benchmarks + writing docs + security audit (all independent)
• ✅ Analyzing 3 different codebases simultaneously
• ✅ Creating examples + running tests + generating reports
• ✅ Exploring multiple architecture options in parallel

Bad candidates:

• ❌ Read file → analyze → write report (sequential dependency)
• ❌ Five trivial operations (<10 seconds each)
• ❌ Interactive tasks needing user input between steps

Step 2: Choose Agent Types

Available agents:

Selection guide:

• Codebase analysis? → Explore agent

  • "Analyze module dependencies"
  • "Find all unsafe code"
  • "Map data flow through pipeline"

• Running commands? → general-purpose agent

  • "Run benchmarks and create report"
  • "Generate usage examples"
  • "Perform security audit"

Step 3: Craft Clear, Independent Prompts

Each prompt must:

1. Be self-contained (no references to other agents)
2. Specify concrete deliverable (file path, format)
3. Include success criteria (what done looks like)
4. Provide context if agent needs background

Step 4: Launch Agents in Single Message

CRITICAL: Use one message with multiple Task tool calls for true parallelism.

Wait for all agents to complete, then review results.

Step 5: Synthesize Results

After agents complete:

1. Read all generated files
2. Check for conflicts or contradictions
3. Integrate findings into summary
4. Identify any gaps that need follow-up

Examples

Example 1: Validating a Project

Scenario: Need to validate codebase architecture, performance, examples, and security

Agents launched (4 in parallel):

1. Explore Agent - Codebase architecture analysis

   • Analyzed 7 modules, mapped dependencies
   • Identified 9 unsafe blocks
   • Found hot paths (ring buffer, orderbook, TSC)
   • Output: Inline architecture analysis (48KB)

2. General-Purpose Agent - Run benchmarks

   • Executed 3 benchmark suites
   • Found bug in bundle.rs (array bounds check)
   • Results: Exceeded all targets by 12-69x
   • Output: BENCHMARKS.md (9.5KB)

3. General-Purpose Agent - Generate examples

   • Created 5 production-ready examples
   • Each with runnable code + explanations
   • Output: examples/README.md (20KB)

4. General-Purpose Agent - Security audit

   • Validated all 9 unsafe blocks
   • Checked atomic ordering
   • Safety score: 9.5/10
   • Output: SAFETY_AUDIT.md (25KB)

Results:

• Total time: ~7 minutes (parallel)
• Sequential would take: ~25+ minutes
• Speedup: 3.5x
• Bonus: Benchmark agent found real bug!

Example 2: Analyzing Multiple Codebases

Scenario: Compare 3 different queue implementations

Agents launched (3 in parallel):

Agent 1: Analyze crossbeam-queue Agent 2: Analyze tokio mpsc Agent 3: Analyze custom lock-free queue

Each agent produces:

• API surface analysis
• Memory ordering used
• Performance characteristics
• Trade-offs

Result: Comparison table in 10 minutes vs 30+ minutes sequential

Example 3: Documentation Sprint

Scenario: Need README, API docs, examples, and architecture docs

Agents launched (4 in parallel):

Agent 1: Write README.md (getting started, install, basic usage) Agent 2: Generate API documentation from code Agent 3: Create examples/ directory with 5 examples Agent 4: Write ARCHITECTURE.md (system design, data flow)

Result: Complete documentation suite in 15 minutes

Best Practices

✅ Do

• Launch 3-5 agents max - More causes context switching overhead
• Make prompts independent - No cross-references between agents
• Specify file paths - Clear deliverables
• Check results immediately - Agents might misunderstand
• Use Explore for codebase tasks - Specialized for code analysis
• One message, multiple tasks - True parallelism

❌ Don't

• Don't create dependencies - Agent A shouldn't need Agent B's output
• Don't overload - >5 agents gets chaotic
• Don't use for trivial tasks - <30 second operations not worth it
• Don't forget to synthesize - Review all outputs together
• Don't launch sequentially - Multiple separate messages = no parallelism

Common Pitfalls

Pitfall 1: Sequential messages

Wrong:

Message 1: Task tool call for Agent 1
[wait for result]
Message 2: Task tool call for Agent 2
[wait for result]

Correct:

Message 1: Task tool calls for Agent 1, 2, 3, 4 (all in one message)
[all run in parallel]

Pitfall 2: Creating dependencies

Wrong:

Agent 1: Analyze codebase and save to /tmp/analysis.txt
Agent 2: Read /tmp/analysis.txt and write report

• Agent 2 depends on Agent 1 completing first
• This is sequential, not parallel!

Correct:

Agent 1: Analyze codebase and write ANALYSIS.md
Agent 2: Run benchmarks and write BENCHMARKS.md
(No dependency between them)

Pitfall 3: Vague prompts

Wrong:

"Look at the code and tell me about performance"

• What code? Where?
• What aspects of performance?
• What deliverable?

Correct:

"Run all benchmarks in benches/ directory:
1. Execute each with cargo bench
2. Extract P50/P99 latencies
3. Compare against targets in README
4. Create BENCHMARKS.md with results table"

Measuring Success

Indicators it worked:

• ✅ All agents completed successfully
• ✅ Time saved vs sequential (calculate speedup)
• ✅ Deliverables are high quality
• ✅ No contradictions between agents
• ✅ Found insights you would have missed (bonus!)

Indicators it failed:

• ❌ Agents blocked waiting for each other
• ❌ Had to redo work due to vague prompts
• ❌ Results conflicted and needed reconciliation
• ❌ Spent more time managing agents than working

Advanced Patterns

Pattern 1: Explore + Implement

Agent 1 (Explore): Analyze existing authentication system
Agent 2 (Explore): Find all security vulnerabilities
Agent 3 (general-purpose): Draft secure auth implementation plan

Then (after review): Implement based on findings

Pattern 2: Test Coverage Expansion

Agent 1: Create unit tests for module A
Agent 2: Create unit tests for module B
Agent 3: Create integration tests
Agent 4: Create property tests

Result: Full test suite in fraction of time

Pattern 3: Multi-Platform Validation

Agent 1: Build and test on Linux
Agent 2: Build and test on macOS
Agent 3: Build and test on Windows
Agent 4: Run cross-compilation tests

(Note: Requires appropriate build environments)

Integration with Workflows

With Code Review

Before submitting PR:

Agent 1: Run all tests + generate coverage report
Agent 2: Run linters + format checks
Agent 3: Run benchmarks + compare to main
Agent 4: Generate changelog from commits

Results ready in minutes instead of running sequentially

With CI/CD

Parallel agents can pre-validate before pushing:

Agent 1: Security scan
Agent 2: Performance regression check
Agent 3: Documentation check
Agent 4: License compliance

Push only if all pass

Related skills

• plan-first-development - Plan what agents should do
• incremental-validation - Use agents for validation steps
• documentation-while-fresh - Agents generate documentation

Skill Version: 1.0 Last Updated: 2025-01-06