OpenAgentsControl/plugins/claude-code/skills/parallel-execution/SKILL.md

---

name: parallel-execution

description: Execute multiple independent tasks in parallel using Claude Code's agent teams or multiple subagent invocations. Use when you have independent tasks with no dependencies, need to speed up multi-component features, or when task-manager marks tasks with parallel:true.

Parallel Execution Skill

Execute multiple independent tasks simultaneously to dramatically reduce implementation time for multi-component features.

When to Use This Skill

Invoke parallel execution when:

• Multiple independent tasks — Tasks with no shared files or dependencies
• Task-manager marks parallel:true — TaskManager identified parallelizable work
• Multi-component features — Frontend + backend + tests can run simultaneously
• Time-sensitive delivery — Need to reduce total execution time
• Isolated work streams — Different agents working on different areas
• Batch operations — Converting multiple files, running multiple tests

When NOT to Use

Avoid parallel execution when:

• ❌ Tasks modify the same files — Will cause merge conflicts
• ❌ Tasks have dependencies — One task needs output from another
• ❌ Shared state or resources — Database migrations, global config changes
• ❌ Sequential logic required — Steps must happen in specific order
• ❌ Single small task — Overhead not worth it for simple operations

How Parallel Execution Works

Approach A: Multiple Subagent Invocations (Native)

Claude Code natively supports parallel work via multiple tool calls in one message.

When you make multiple independent task() calls in a single response, Claude Code executes them in parallel:

I'll execute these three tasks in parallel:

task(subagent_type="CoderAgent", description="Implement auth service", prompt="...")
task(subagent_type="CoderAgent", description="Implement user service", prompt="...")
task(subagent_type="TestEngineer", description="Create integration tests", prompt="...")

Key points:

• All three tasks start simultaneously
• Each runs in isolated context
• Main agent waits for ALL to complete before proceeding
• Results are collected and can be integrated

Approach B: Agent Teams (Experimental)

Requires: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

Agent teams allow multiple agents to collaborate on a shared workspace:

I'll create an agent team for this feature:

team(
  name="auth-implementation",
  agents=[
    {type: "CoderAgent", task: "Backend auth service"},
    {type: "OpenFrontendSpecialist", task: "Login UI components"},
    {type: "TestEngineer", task: "E2E auth tests"}
  ],
  shared_context=".tmp/sessions/auth-context.md"
)

Key points:

• Agents share context file for coordination
• Can communicate via shared state
• More complex but enables tighter integration
• Experimental feature, may change

Integration with Task-Manager

TaskManager automatically identifies parallel tasks and marks them with parallel: true:

Task Structure Example

task.json:

{
  "id": "user-dashboard",
  "subtask_count": 5,
  "context_files": [".opencode/context/core/standards/code-quality.md"]
}

subtask_01.json (parallel):

{
  "id": "user-dashboard-01",
  "seq": "01",
  "title": "Create user profile API",
  "parallel": true,
  "depends_on": [],
  "suggested_agent": "CoderAgent"
}

subtask_02.json (parallel):

{
  "id": "user-dashboard-02",
  "seq": "02",
  "title": "Design dashboard UI components",
  "parallel": true,
  "depends_on": [],
  "suggested_agent": "OpenFrontendSpecialist"
}

subtask_03.json (sequential - depends on 01 and 02):

{
  "id": "user-dashboard-03",
  "seq": "03",
  "title": "Integrate API with UI",
  "parallel": false,
  "depends_on": ["01", "02"],
  "suggested_agent": "CoderAgent"
}

Identifying Parallel Batches

Use the task-management CLI to identify parallel tasks:

# Show which tasks can run in parallel
bash .opencode/skills/task-management/router.sh parallel user-dashboard

Output:

Batch 1 (Ready now):
- subtask_01.json (parallel: true)
- subtask_02.json (parallel: true)

Batch 2 (After Batch 1):
- subtask_03.json (depends_on: ["01", "02"])

Execution Workflow

Step 1: Analyze Task Structure

Read .tmp/tasks/{feature}/task.json
Read all subtask_NN.json files
Identify parallel batches using dependency graph

Step 2: Execute Parallel Batch

For Batch 1 (subtasks 01 and 02 are parallel):

task(
  subagent_type="CoderAgent",
  description="Execute subtask 01",
  prompt="Read .tmp/tasks/user-dashboard/subtask_01.json and implement..."
)

task(
  subagent_type="OpenFrontendSpecialist",
  description="Execute subtask 02",
  prompt="Read .tmp/tasks/user-dashboard/subtask_02.json and implement..."
)

Wait for both to complete...

Step 3: Verify Batch Completion

bash .opencode/skills/task-management/router.sh status user-dashboard

Step 4: Execute Next Batch

Once Batch 1 is complete, proceed to Batch 2:

task(
  subagent_type="CoderAgent",
  description="Execute subtask 03",
  prompt="Read .tmp/tasks/user-dashboard/subtask_03.json and integrate..."
)

Practical Examples

Example 1: Converting Multiple Subagents in Parallel

Scenario: Convert 5 subagent files from old format to new format

I'll convert these subagents in parallel:

task(subagent_type="CoderAgent", description="Convert auth-agent", 
     prompt="Convert .opencode/agent/subagents/auth-agent.md to new format...")

task(subagent_type="CoderAgent", description="Convert user-agent",
     prompt="Convert .opencode/agent/subagents/user-agent.md to new format...")

task(subagent_type="CoderAgent", description="Convert payment-agent",
     prompt="Convert .opencode/agent/subagents/payment-agent.md to new format...")

task(subagent_type="CoderAgent", description="Convert notification-agent",
     prompt="Convert .opencode/agent/subagents/notification-agent.md to new format...")

task(subagent_type="CoderAgent", description="Convert analytics-agent",
     prompt="Convert .opencode/agent/subagents/analytics-agent.md to new format...")

Time savings: 5 tasks × 10 min each = 50 min sequential → ~10 min parallel (80% faster)

Example 2: Running Tests in Parallel

Scenario: Run unit tests, integration tests, and E2E tests simultaneously

I'll run all test suites in parallel:

task(subagent_type="TestEngineer", description="Run unit tests",
     prompt="Execute unit test suite for src/auth/...")

task(subagent_type="TestEngineer", description="Run integration tests",
     prompt="Execute integration test suite for src/api/...")

task(subagent_type="TestEngineer", description="Run E2E tests",
     prompt="Execute E2E test suite for user flows...")

Time savings: 3 suites × 5 min each = 15 min sequential → ~5 min parallel (67% faster)

Example 3: Implementing Independent Features

Scenario: Build authentication system with parallel work streams

I'll implement these independent components in parallel:

task(subagent_type="CoderAgent", description="JWT service",
     prompt="Create JWT token generation and validation service...")

task(subagent_type="CoderAgent", description="Password hashing",
     prompt="Implement bcrypt password hashing utilities...")

task(subagent_type="CoderAgent", description="Session storage",
     prompt="Create Redis-based session storage layer...")

task(subagent_type="OpenFrontendSpecialist", description="Login UI",
     prompt="Design and implement login form components...")

Time savings: 4 components × 30 min each = 120 min sequential → ~30 min parallel (75% faster)

Best Practices

1. Avoid File Conflicts

✅ Good (isolated files):

task(CoderAgent, "Create src/auth/service.ts")
task(CoderAgent, "Create src/user/service.ts")
task(CoderAgent, "Create src/payment/service.ts")

❌ Bad (same file):

task(CoderAgent, "Add auth function to src/utils/helpers.ts")
task(CoderAgent, "Add validation function to src/utils/helpers.ts")

2. Size Tasks Appropriately

✅ Good (balanced tasks):

task(CoderAgent, "Implement user CRUD API (30 min)")
task(CoderAgent, "Implement auth middleware (30 min)")

❌ Bad (unbalanced):

task(CoderAgent, "Implement entire backend (2 hours)")
task(CoderAgent, "Add one import statement (1 min)")

3. Monitor Progress

After delegating parallel tasks, track completion:

# Check status periodically
bash .opencode/skills/task-management/router.sh status {feature}

# Look for:
# - subtask_01.json: status: "completed" ✓
# - subtask_02.json: status: "completed" ✓
# - subtask_03.json: status: "in_progress" ...

4. Handle Failures Gracefully

If one parallel task fails:

Batch 1 Results:
- Task 01: ✅ Completed
- Task 02: ❌ Failed (missing dependency)
- Task 03: ✅ Completed

Action: Fix Task 02 before proceeding to Batch 2

5. Coordinate Shared Context

When tasks need shared information:

✅ Good (pre-load context):

# Load context BEFORE parallel execution
Read .opencode/context/core/standards/code-quality.md
Read .opencode/context/core/standards/security-patterns.md

# Now all parallel tasks have same context
task(CoderAgent, "Implement auth service...")
task(CoderAgent, "Implement user service...")

❌ Bad (each task discovers context):

# Each task will call ContextScout separately (slower)
task(CoderAgent, "Discover context and implement auth...")
task(CoderAgent, "Discover context and implement user...")

Troubleshooting

Issue: Tasks completing out of order

Problem: Task 02 finishes before Task 01, but Task 03 depends on both

Solution: Use dependency tracking in subtask JSON:

{
  "id": "feature-03",
  "depends_on": ["01", "02"],
  "parallel": false
}

Don't start Task 03 until BOTH 01 and 02 are marked status: "completed".

Issue: File conflicts during parallel execution

Problem: Two tasks tried to modify the same file

Solution:

1. Review task breakdown - ensure true isolation
2. If tasks MUST touch same file, mark parallel: false
3. Sequence dependent tasks properly

Issue: One task blocked waiting for another

Problem: Task 01 needs output from Task 02, but both marked parallel

Solution: Fix dependency graph:

{
  "id": "feature-01",
  "depends_on": ["02"],  // Add dependency
  "parallel": false      // Mark sequential
}

Issue: Parallel tasks not actually running in parallel

Problem: Tasks executing sequentially despite parallel flags

Solution: Ensure you're making multiple task() calls in SAME message:

✅ Correct:

I'll execute these in parallel:

task(...)
task(...)
task(...)

❌ Wrong (sequential):

I'll execute task 1:
task(...)

[Wait for response]

Now I'll execute task 2:
task(...)

Performance Impact

Time Savings by Parallelization

Scenario	Sequential	Parallel	Savings
3 independent components (30 min each)	90 min	30 min	67%
5 file conversions (10 min each)	50 min	10 min	80%
4 test suites (15 min each)	60 min	15 min	75%
Frontend + Backend + Tests	120 min	40 min	67%

Optimal Batch Sizes

• 2-4 tasks: Ideal for most scenarios
• 5-8 tasks: Good if truly independent
• 9+ tasks: Consider breaking into multiple batches

Related Skills

• /task-breakdown — Creates task structure with parallel flags
• /context-discovery — Load shared context before parallel execution
• /code-review — Review all parallel outputs together

Advanced: Agent Teams

For complex features requiring tight coordination, use agent teams (experimental):

team(
  name="e-commerce-checkout",
  agents=[
    {
      type: "CoderAgent",
      role: "backend",
      tasks: ["Payment API", "Order processing", "Inventory check"]
    },
    {
      type: "OpenFrontendSpecialist", 
      role: "frontend",
      tasks: ["Checkout UI", "Payment form", "Order confirmation"]
    },
    {
      type: "TestEngineer",
      role: "qa",
      tasks: ["Integration tests", "E2E checkout flow"]
    }
  ],
  shared_context: ".tmp/sessions/checkout-context.md",
  coordination: "async"  // Agents coordinate via shared context file
)

Benefits:

• Agents can update shared context as they progress
• Enables async coordination without blocking
• Better for complex features with evolving requirements

Drawbacks:

• Experimental feature
• More complex to debug
• Requires careful context management

---

Summary

Parallel execution is a powerful technique for reducing implementation time when:

1. Tasks are truly independent (no shared files/state)
2. TaskManager marks tasks with parallel: true
3. You make multiple task() calls in same message

Key takeaways:

• ✅ Use for independent components, file conversions, test suites
• ✅ Pre-load shared context before parallel execution
• ✅ Monitor completion with task-management CLI
• ❌ Avoid for tasks with dependencies or shared files
• ❌ Don't parallelize tasks that modify same file

Time savings: 50-80% reduction in execution time for multi-component features.