parallel-subagents

name: parallel-subagents description: Coordinate independent teammates concurrently in Agent Teams for 50-70% speedup. Launch multiple teammates simultaneously.

SKILL: Parallel Teammates (Agent Teams Coordination)

Purpose: Concurrent teammate execution for independent tasks, 50-70% speedup Target: Team Leads coordinating multiple independent SCs/tasks in Agent Teams

Quick Start

When to Use This Skill

Multiple independent SCs (no shared files, no dependencies)
Independent code changes (different files/directories)
Parallel verification (testing, type-check, linting)
Multi-angle review (code-reviewer, security-analyst in parallel)

Quick Reference

# Spawn teammates for independent SCs (from execute-plan Step 3)
Spawn teammate "sc1-impl" with prompt:
  "You are a $SC_AGENT. Execute SC-1: Create authentication service.
  Skills: tdd, ralph-loop, vibe-coding. Mark task done when complete."

Spawn teammate "sc2-impl" with prompt:
  "You are a $SC_AGENT. Execute SC-2: Create user service.
  Skills: tdd, ralph-loop, vibe-coding. Mark task done when complete."

Spawn teammate "sc3-impl" with prompt:
  "You are a $SC_AGENT. Execute SC-3: Create database migrations.
  Skills: tdd, ralph-loop, vibe-coding. Mark task done when complete."

Note: $SC_AGENT is selected per-SC (not per-plan) in execute-plan Step 3 based on each SC's file paths and keywords. Different SCs may use different specialized agents (e.g., SC-1 → frontend-engineer, SC-2 → backend-engineer).

⚠️ What "Parallel" Means (CRITICAL)

Parallel = Multiple teammates spawned simultaneously in Agent Team:

# ✅ TRUE PARALLEL (single response, multiple Spawn calls)
Spawn teammate "sc1-impl" with prompt: "Execute SC-1..."
Spawn teammate "sc2-impl" with prompt: "Execute SC-2..."
Spawn teammate "sc3-impl" with prompt: "Execute SC-3..."

Sequential = One teammate per response (loop dispatch):

# ❌ NOT PARALLEL (even if called "parallel")
for SC in $SC_LIST; do
    Spawn teammate "impl-$SC" with prompt: "Execute $SC..."
done

Team Lead delegate mode: Coordinate only (Shift+Tab), never implement directly

Core Concepts

Parallel Execution Patterns

Pattern 1: Independent SCs

Spawn teammate "explore-auth" with prompt:
  "You are an explorer. Search for auth patterns. Share findings via Message."

Spawn teammate "explore-db" with prompt:
  "You are an explorer. Search for database patterns. Share findings via Message."

Spawn teammate "explore-api" with prompt:
  "You are an explorer. Search for API patterns. Share findings via Message."

Pattern 2: Parallel Verification

Spawn teammate "test-reviewer" with prompt:
  "You are a tester. Run tests and verify coverage. Mark task done when complete."

Spawn teammate "quality-reviewer" with prompt:
  "You are a validator. Run type check and lint. Mark task done when complete."

Spawn teammate "deep-reviewer" with prompt:
  "You are a code-reviewer (Opus). Review for async bugs. Mark task done when complete."

Pattern 3: Multi-Angle Review

Spawn teammate "plan-review" with prompt:
  "You are a plan-reviewer. Review plan completeness. Message other reviewers with findings."

Spawn teammate "code-review" with prompt:
  "You are a code-reviewer. Review code quality. Message other reviewers with findings."

Spawn teammate "security-review" with prompt:
  "You are a security-analyst. Review security issues. Message other reviewers with findings."

Dependency Analysis

Before launching parallel teammates, check for conflicts:

File Overlap: Do SCs mention same files?
Dependency Keywords: "after", "depends", "requires", "follows"
ParallelGroup Annotation: Group independent SCs in plan

Coordination

Result Integration:

Wait for all parallel teammates to complete (TaskCompleted hook auto-verifies)
Check for file conflicts (rare if analysis correct)
Aggregate results from completed teammates

Performance: 50-70% faster for independent tasks

Anti-Patterns

Don't parallelize:

Tasks with shared file modifications (causes merge conflicts)
Tasks with dependencies (later task will fail)
Sequential workflows (e.g., build then test)

Test Execution Concurrency

Critical: Multiple tester teammates in parallel can cause worker explosion (6 teammates × 16 workers = 96 processes, Load 85+)

Pattern: Test type-aware concurrency

E2E/Integration: Sequential execution (E2E sequential, one at a time)
Unit/Lint/Type: Parallel allowed with --maxWorkers=50% (unit parallel)

Detection (from execute-plan Step 3):

Path: **/e2e/**, **/integration/**, **/*.e2e.*
Keywords: "e2e", "integration", "playwright", "cypress"
Fail-safe: Unknown → unit (parallel with worker limit)

Implementation: @.claude/agents/tester.md applies --maxWorkers=50% (Jest) or --workers=1 (Playwright E2E)

Full examples: See @.claude/skills/parallel-subagents/REFERENCE.md#test-execution-concurrency

Single Teammate Delegation Pattern

When to Use

Single SC execution (no parallelism needed)
Sequential workflow steps
Context protection for Team Lead

Why Delegate Single Tasks

Team Lead context is limited (~200K tokens). By delegating:

Teammate runs in isolated context (~80K tokens internally)
Returns concise summary (~1K tokens via Task List)
Team Lead maintains clean context for coordination

Pattern

Spawn teammate "[role-name]" with prompt:
  """
  You are a [agent-type] (see @.claude/agents/[agent-type].md).
  [Clear task description with all context needed]
  Skills to use: [skill1, skill2]
  When complete, mark task as done. If blocked, message the team lead.
  """

Examples

Single Coder Delegation:

Spawn teammate "sc1-impl" with prompt:
  """
  You are a coder (see @.claude/agents/coder.md).
  Execute SC-1: Create authentication service from $PLAN_PATH.
  Skills to use: tdd, ralph-loop, vibe-coding.
  When complete, mark task as done. If blocked, message the team lead.
  """

Single Plan-Reviewer Delegation:

Spawn teammate "plan-review" with prompt:
  """
  You are a plan-reviewer (see @.claude/agents/plan-reviewer.md).
  Review plan at $PLAN_FILE for gaps and issues.
  Review criteria: requirements coverage, success criteria clarity.
  When complete, mark task as done. If blocked, message the team lead.
  """

Single Documenter Delegation:

Spawn teammate "doc-sync" with prompt:
  """
  You are a documenter (see @.claude/agents/documenter.md).
  Invoke the three-tier-docs skill to sync documentation.
  Project root: $PROJECT_ROOT.
  When complete, mark task as done. If blocked, message the team lead.
  """

Verification

# Launch 3 independent teammates
Spawn teammate "find-ts" with prompt: "You are an explorer. Find TypeScript files."
Spawn teammate "find-tests" with prompt: "You are an explorer. Find test files."
Spawn teammate "find-config" with prompt: "You are an explorer. Find config files."

# Team Lead operates in delegate mode (Shift+Tab)
# TaskCompleted hook auto-verifies quality gates
# Shared Task List shows completion status