--- name: parallel-execution-e08e224a45c2 description: Patterns for parallel subagent execution using the Agent tool (formerly Task). Use when coordinating multiple independent tasks, spawning dynamic subagents, or implementing features that can be parallelized. --- # Parallel Execution Patterns ### When to Load - **Trigger**: Multi-agent tasks, concurrent operations, spawning subagents, parallelizing independent work - **Skip**: Single-step tasks or sequential workflows with no parallelization opportunity ## Core Concept Parallel execution spawns multiple subagents simultaneously using the Agent tool (named `Task` before Claude Code 2.1.63; `Task` still works as an alias). Subagents run in the background by default, so N tasks run concurrently, dramatically reducing total execution time. **Critical Rule**: ALL Agent calls MUST be in a SINGLE assistant message for true parallelism. If the calls are in separate messages, they launch one after another. ## Execution Protocol ### Step 1: Identify Parallelizable Tasks Before spawning, verify tasks are independent: - No task depends on another's output - Tasks target different files or concerns - Can run simultaneously without conflicts ### Step 2: Prepare Dynamic Subagent Prompts Each subagent receives a custom prompt defining its role: ``` You are a [ROLE] specialist for this specific task. Task: [CLEAR DESCRIPTION] Context: [RELEVANT CONTEXT ABOUT THE CODEBASE/PROJECT] Files to work with: [SPECIFIC FILES OR PATTERNS] Output format: [EXPECTED OUTPUT STRUCTURE] Focus areas: - [PRIORITY 1] - [PRIORITY 2] ``` ### Step 3: Launch All Tasks in ONE Message **CRITICAL**: Make ALL Agent calls in the SAME assistant message: ``` I'm launching N parallel subagents: [Agent 1] description: "Subagent A - [brief purpose]" prompt: "[detailed instructions for subagent A]" [Agent 2] description: "Subagent B - [brief purpose]" prompt: "[detailed instructions for subagent B]" [Agent 3] description: "Subagent C - [brief purpose]" prompt: "[detailed instructions for subagent C]" ``` On Claude Code versions that still run subagents in the foreground by default, add `run_in_background: true` to each call. ### Step 4: Collect Results Each subagent returns its final result to the parent conversation automatically when it finishes. Wait until every subagent has reported before synthesizing; do not poll, and do not start dependent work early. (The separate `TaskOutput` call is deprecated.) ### Step 5: Synthesize Results Combine all subagent outputs into unified result: - Merge related findings - Resolve conflicts between recommendations - Prioritize by severity/importance - Create actionable summary ## Dynamic Subagent Patterns ### Pattern 1: Task-Based Parallelization When you have N tasks to implement, spawn N subagents: ``` Plan: 1. Implement auth module 2. Create API endpoints 3. Add database schema 4. Write unit tests 5. Update documentation Wave 1 - spawn 3 subagents (independent of each other): - Subagent 1: Implements auth module - Subagent 2: Creates API endpoints - Subagent 3: Adds database schema Wave 2 - after wave 1 has finished (these depend on its output): - Subagent 4: Writes unit tests - Subagent 5: Updates documentation ``` ### Pattern 2: Directory-Based Parallelization Analyze multiple directories simultaneously: ``` Directories: src/auth, src/api, src/db Spawn 3 subagents: - Subagent 1: Analyzes src/auth - Subagent 2: Analyzes src/api - Subagent 3: Analyzes src/db ``` ### Pattern 3: Perspective-Based Parallelization Review from multiple angles simultaneously: ``` Perspectives: Security, Performance, Testing, Architecture Spawn 4 subagents: - Subagent 1: Security review - Subagent 2: Performance analysis - Subagent 3: Test coverage review - Subagent 4: Architecture assessment ``` ## Task List Integration When using parallel execution, task tracking (`TaskCreate`/`TaskUpdate`, or `TodoWrite` on older versions) differs: **Sequential execution**: Only ONE task `in_progress` at a time **Parallel execution**: MULTIPLE tasks can be `in_progress` simultaneously ``` # Before launching parallel tasks todos = [ { content: "Task A", status: "in_progress" }, { content: "Task B", status: "in_progress" }, { content: "Task C", status: "in_progress" }, { content: "Synthesize results", status: "pending" } ] # As each subagent reports back, mark its task completed todos = [ { content: "Task A", status: "completed" }, { content: "Task B", status: "completed" }, { content: "Task C", status: "completed" }, { content: "Synthesize results", status: "in_progress" } ] ``` ## When to Use Parallel Execution **Good candidates:** - Multiple independent analyses (code review, security, tests) - Multi-file processing where files are independent - Exploratory tasks with different perspectives - Verification tasks with different checks - Feature implementation with independent components **Avoid parallelization when:** - Tasks have dependencies (Task B needs Task A's output) - Sequential workflows are required (commit -> push -> PR) - Tasks modify the same files (risk of conflicts) - Order matters for correctness ## Performance Benefits | Approach | 5 Tasks @ 30s each | Total Time | | ---------- | --------------------------- | ---------- | | Sequential | 30s + 30s + 30s + 30s + 30s | ~150s | | Parallel | All 5 run simultaneously | ~30s | Parallel execution is approximately Nx faster where N is the number of independent tasks. ## Example: Feature Implementation **User request**: "Implement user authentication with login, registration, and password reset" **Orchestrator creates plan**: 1. Implement login endpoint 2. Implement registration endpoint 3. Implement password reset endpoint 4. Add authentication middleware 5. Write integration tests **Parallel execution**: ``` Wave 1 - launching 4 subagents in parallel: [Agent 1] Login endpoint implementation [Agent 2] Registration endpoint implementation [Agent 3] Password reset endpoint implementation [Agent 4] Auth middleware implementation [Results arrive as each subagent finishes] Wave 2 - depends on wave 1: [Agent 5] Integration test writing [Synthesize into cohesive implementation] ``` ## Troubleshooting **Tasks running sequentially?** - Verify ALL Agent calls are in a SINGLE message - On older Claude Code versions, check `run_in_background: true` is set for each **Results not available?** - Results are delivered when each subagent finishes; wait for all of them - A subagent that was denied a permission may return without finishing its work; check its report **Conflicts in output?** - Ensure tasks don't modify same files - Add conflict resolution in synthesis step --- Source attribution: CloudAI-X Original project: https://github.com/CloudAI-X/claude-workflow-v2 License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gabriel Moreira Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: CloudAI-X Original project: https://github.com/CloudAI-X/claude-workflow-v2 Attribution basis: Upstream repository explicitly recorded in package mirror path Fields of work: Development & Engineering Roles: Backend Developer, Data Engineer, ML / AI Engineer Specialties: Backend Tools: Todowrite Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5ec81de24f992c89f75786ee7b3440c68767052ada9ed1c2ef83257b170bc6cb