parallel-execution-optimizer

Traditional sequential execution wastes time:

• •/optimize runs 5 quality checks sequentially (10-15 minutes)
• •/ship runs 5 pre-flight checks sequentially (8-12 minutes)
• •/implement processes tasks one-by-one despite no dependencies
• •Prototype screens generated sequentially when all could run in parallel

This skill analyzes operation dependencies, groups independent work into batches, and orchestrates parallel execution using multiple Task() agent calls in a single message. The result: 3-5x faster phase completion with zero compromise on quality or correctness. </objective>

<quick_start> <basic_pattern> When you detect multiple independent operations, send a single message with multiple tool calls:

Sequential (slow):

• •Send message with Task call for security-sentry
• •Wait for response
• •Send message with Task call for performance-profiler
• •Wait for response
• •Send message with Task call for accessibility-auditor
• •Total: 15 minutes

Parallel (fast):

• •Send ONE message with 3 Task calls (security-sentry, performance-profiler, accessibility-auditor)
• •All three run concurrently
• •Total: 5 minutes </basic_pattern>

<immediate_use_cases>

1. •/optimize phase: Run 5 quality checks in parallel (security, performance, accessibility, code-review, type-safety)
2. •/ship pre-flight: Run 5 deployment checks in parallel (env-vars, build, docker, CI-config, dependency-audit)
3. •/implement: Process independent task batches in parallel layers
4. •Design variations: Generate multiple mockup variations concurrently
5. •Research phase: Fetch multiple documentation sources concurrently </immediate_use_cases> </quick_start>

Scan the current phase for operations that:

• •Read different files/data sources
• •Don't modify shared state
• •Have no sequential dependencies
• •Can produce results independently

Examples:

• •Quality checks (security scan + performance test + accessibility audit)
• •File reads (spec.md + plan.md + tasks.md)
• •API documentation fetches (Stripe docs + Twilio docs + SendGrid docs)
• •Test suite runs (unit tests + integration tests + E2E tests) </step>

Build a dependency graph:

• •Layer 0: Operations with no dependencies (can run immediately)
• •Layer 1: Operations depending only on Layer 0 outputs
• •Layer 2: Operations depending on Layer 1 outputs
• •etc.

Example (/optimize):

Layer 0 (parallel):
  - security-sentry (reads codebase)
  - performance-profiler (reads codebase + runs benchmarks)
  - accessibility-auditor (reads UI components)
  - type-enforcer (reads TypeScript files)
  - dependency-curator (reads package.json)

Layer 1 (after Layer 0):
  - Generate optimization-report.md (combines all Layer 0 results)

Create batches for each layer:

• •All Layer 0 operations in single message (parallel execution)
• •Wait for Layer 0 completion
• •All Layer 1 operations in single message
• •Continue through layers

Batch size considerations:

• •Optimal: 3-5 operations per batch (balanced parallelism)
• •Maximum: 8 operations (avoid overwhelming system)
• •Minimum: 2 operations (below 2, parallelism has no benefit) </step>

Send a single message with multiple tool calls for each batch.

Critical requirements:

• •Must be a single message with multiple tool use blocks
• •Each tool call must be complete and independent
• •Do not use placeholders or forward references
• •Each agent must have all required context in its prompt

See references/execution-patterns.md for detailed examples. </step>

After each batch completes:

• •Collect results from all parallel operations
• •Check for failures or blocking issues
• •Decide whether to proceed to next layer
• •Aggregate findings into unified report

Failure handling:

• •If any operation blocks (critical security issue), halt pipeline
• •If operations have warnings (minor performance issue), continue but log
• •If operations fail (agent error), retry individually or escalate </step> </workflow>

<phase_specific_patterns> <optimize_phase> Operation: Run 5 quality gates in parallel

Dependency graph:

Layer 0 (parallel - 5 operations):
  1. security-sentry → Scan for vulnerabilities, secrets, auth issues
  2. performance-profiler → Benchmark API endpoints, detect N+1 queries
  3. accessibility-auditor → WCAG 2.1 AA compliance (if UI feature)
  4. type-enforcer → TypeScript strict mode compliance
  5. dependency-curator → npm audit, outdated packages

Layer 1 (sequential - 1 operation):
  6. Generate optimization-report.md (aggregates Layer 0 findings)

Time savings:

• •Sequential: ~15 minutes (3 min per check)
• •Parallel: ~5 minutes (longest check + aggregation)
• •Speedup: 3x

See references/optimize-phase-parallelization.md for implementation details. </optimize_phase>

<ship_preflight> Operation: Run 5 pre-flight checks in parallel

Dependency graph:

Layer 0 (parallel - 5 operations):
  1. Check environment variables (read .env.example vs .env)
  2. Validate production build (npm run build)
  3. Check Docker configuration (docker-compose.yml, Dockerfile)
  4. Validate CI configuration (.github/workflows/*.yml)
  5. Run dependency audit (npm audit --production)

Layer 1 (sequential - 1 operation):
  6. Update state.yaml with pre-flight results

Time savings:

• •Sequential: ~12 minutes
• •Parallel: ~4 minutes (build is longest operation)
• •Speedup: 3x

See references/ship-preflight-parallelization.md. </ship_preflight>

<implement_phase> Operation: Execute independent task batches in parallel

Dependency analysis:

1. •Read tasks.md
2. •Build dependency graph from task relationships
3. •Identify tasks with no dependencies (Layer 0)
4. •Group tasks by layer

Example (15 tasks):

Layer 0 (4 tasks - parallel):
  T001: Create User model
  T002: Create Product model
  T005: Setup test framework
  T008: Create API client utility

Layer 1 (3 tasks - parallel, depend on Layer 0):
  T003: User CRUD endpoints (needs T001)
  T004: Product CRUD endpoints (needs T002)
  T009: Write User model tests (needs T001, T005)

Layer 2 (2 tasks - parallel):
  T006: User-Product relationship (needs T001, T002)
  T010: Write Product model tests (needs T002, T005)

Layer 3 (sequential):
  T007: Integration tests (needs all above)

Execution:

• •Batch 1: Launch 4 agents for Layer 0 tasks (parallel)
• •Batch 2: Launch 3 agents for Layer 1 tasks (parallel)
• •Batch 3: Launch 2 agents for Layer 2 tasks (parallel)
• •Batch 4: Single agent for Layer 3

Time savings:

• •Sequential: 15 tasks × 20 min = 300 minutes (5 hours)
• •Parallel: 4 batches × 30 min = 120 minutes (2 hours)
• •Speedup: 2.5x

See references/implement-phase-parallelization.md. </implement_phase>

<prototype_screens> Operation: Generate multiple prototype screens in parallel

Use case: User wants to create 3 different screens (login, dashboard, settings)

Sequential approach (slow):

1. •Generate login screen
2. •Generate dashboard screen
3. •Generate settings screen Total: 15 minutes

Parallel approach (fast):

1. •Launch 3 screen agents in single message (login, dashboard, settings) Total: 5 minutes (all generate concurrently)

Speedup: 3x

Note: All screens share theme.yaml for consistency. </prototype_screens> </phase_specific_patterns>

<dependency_analysis> <determining_independence> Two operations are independent if:

1. •Read-only access to shared resources: Both only read the same files (safe to parallelize)
2. •Disjoint file access: They read/write completely different files
3. •No temporal dependencies: Neither requires the other's output
4. •Idempotent operations: Running them in any order produces same result

Two operations are dependent if:

1. •Write-after-read: Operation B reads file that Operation A writes
2. •Write-after-write: Both write to same file (race condition)
3. •Data dependency: Operation B needs Operation A's output as input
4. •Order-dependent side effects: Operations modify shared state </determining_independence>

<common_patterns> Independent (safe to parallelize):

• •Multiple quality checks reading codebase
• •Multiple file reads (spec.md, plan.md, tasks.md)
• •Multiple API documentation fetches
• •Multiple test suite runs (if isolated)
• •Multiple lint checks on different file types

Dependent (must sequence):

• •Generate code → Run tests on generated code
• •Fetch API docs → Generate client based on docs
• •Write file → Read file back for validation
• •Create database schema → Run migrations
• •Build project → Deploy built artifacts </common_patterns>

<edge_cases> Shared mutable state: If operations modify the same git branch, database, or filesystem location, they CANNOT run in parallel safely.

Resource contention: Even if logically independent, operations competing for same resource (CPU, memory, network) may not see speedup. Monitor system resources.

Cascading failures: If one parallel operation fails and others depend on it indirectly, you may need to cancel or retry the batch. </edge_cases> </dependency_analysis>

<auto_trigger_conditions> <when_to_apply> Automatically apply parallel execution when you detect:

1. •Multiple quality checks: ≥3 independent checks in /optimize or /ship
2. •Multiple file reads: ≥3 files to read that don't depend on each other
3. •Multiple API calls: ≥2 external API documentation fetches
4. •Batch task processing: ≥5 tasks in /implement with identifiable layers
5. •Multiple test suites: Unit, integration, E2E running independently
6. •Multiple design variations: ≥2 mockup/prototype variants requested
7. •Multiple research queries: ≥3 web searches or documentation lookups </when_to_apply>

<when_not_to_apply> Do NOT parallelize when:

1. •Sequential dependencies exist: Operation B needs Operation A's output
2. •Shared state modification: Operations write to same files/database
3. •Small operation count: <2 independent operations (no benefit)
4. •Complex coordination needed: Results must be merged in specific order
5. •User explicitly requests sequential: "Do X, then Y, then Z" </when_not_to_apply>

<proactive_detection> Scan for these phrases in phase workflows:

• •"Run these checks: A, B, C, D, E" → Parallel candidate
• •"Generate variations: X, Y, Z" → Parallel candidate
• •"Fetch documentation for: Service1, Service2, Service3" → Parallel candidate
• •"Execute tasks: T001, T002, T003 (no dependencies)" → Parallel candidate

When detected, immediately analyze dependencies and propose parallel execution strategy. </proactive_detection> </auto_trigger_conditions>

Sequential execution (15 minutes):

1. Launch security-sentry (3 min)
2. Wait for completion
3. Launch performance-profiler (4 min)
4. Wait for completion
5. Launch accessibility-auditor (3 min)
6. Wait for completion
7. Launch type-enforcer (2 min)
8. Wait for completion
9. Launch dependency-curator (2 min)
10. Wait for completion
11. Aggregate results (1 min)
Total: 15 minutes

Parallel execution (5 minutes):

1. Launch 5 agents in SINGLE message:
   - security-sentry
   - performance-profiler
   - accessibility-auditor
   - type-enforcer
   - dependency-curator
2. All run concurrently (longest is 4 min)
3. Aggregate results (1 min)
Total: 5 minutes

Implementation: See examples/optimize-phase-parallel.md </example>

Sequential execution (12 minutes):

1. Check env vars (1 min)
2. Run build (5 min)
3. Check Docker config (2 min)
4. Validate CI config (2 min)
5. Dependency audit (2 min)
Total: 12 minutes

Parallel execution (6 minutes):

1. Launch 5 checks in SINGLE message (all concurrent)
2. Longest operation is build (5 min)
3. Update workflow state (1 min)
Total: 6 minutes

Implementation: See examples/ship-preflight-parallel.md </example>

Task dependencies:

T001 (User model) → no deps
T002 (Product model) → no deps
T003 (User endpoints) → depends on T001
T004 (Product endpoints) → depends on T002
T005 (User tests) → depends on T001, T003
T006 (Product tests) → depends on T002, T004
T007 (Integration tests) → depends on T003, T004

Parallel execution plan:

Batch 1 (Layer 0): T001, T002 (parallel - 2 tasks)
Batch 2 (Layer 1): T003, T004 (parallel - 2 tasks, wait for Batch 1)
Batch 3 (Layer 2): T005, T006 (parallel - 2 tasks, wait for Batch 2)
Batch 4 (Layer 3): T007 (sequential - 1 task, wait for Batch 3)

Time savings:

• •Sequential: 7 tasks × 20 min = 140 minutes
• •Parallel: 4 batches × 25 min = 100 minutes
• •Speedup: 1.4x

Implementation: See examples/implement-batching-parallel.md </example> </examples>

<anti_patterns> <anti_pattern name="fake-parallelism"> Problem: Sending multiple messages rapidly, thinking they'll run in parallel

Wrong approach:

Send message 1: Launch agent A
Send message 2: Launch agent B
Send message 3: Launch agent C

These execute sequentially because each message waits for the previous to complete.

Correct approach:

Send ONE message with 3 tool calls (A, B, C)

Rule: Multiple tool calls in a SINGLE message = parallel. Multiple messages = sequential. </anti_pattern>

<anti_pattern name="ignoring-dependencies"> Problem: Parallelizing dependent operations causing race conditions

Wrong approach:

Parallel batch:
- Generate User model code
- Write tests for User model (needs generated code)

Second operation will fail because code doesn't exist yet.

Correct approach:

Batch 1 (sequential): Generate User model code
Batch 2 (sequential): Write tests for User model

Rule: Always build dependency graph first. Never parallelize dependent operations. </anti_pattern>

<anti_pattern name="over-parallelization"> Problem: Launching 20 agents in parallel, overwhelming system

Wrong approach:

Launch 20 agents in single message (all tasks at once)

System resources exhausted, agents may fail or slow down dramatically.

Correct approach:

Batch 1: Launch 5 agents (Layer 0)
Batch 2: Launch 5 agents (Layer 1)
Batch 3: Launch 5 agents (Layer 2)
Batch 4: Launch 5 agents (Layer 3)

Rule: Keep batches to 3-8 operations. More layers is better than huge batches. </anti_pattern>

<anti_pattern name="parallelizing-trivial-operations"> Problem: Using parallel execution for operations taking <30 seconds each

Wrong approach:

Parallel batch:
- Read spec.md (5 seconds)
- Read plan.md (5 seconds)

Overhead of parallel coordination exceeds time savings.

Correct approach:

Sequential:
- Read spec.md
- Read plan.md

Rule: Only parallelize operations taking ≥1 minute each. Below that, sequential is fine. </anti_pattern> </anti_patterns>

1. •Wall-clock time reduced: Phase completes 2-5x faster than sequential baseline
2. •All operations successful: No failures due to race conditions or dependencies
3. •Results identical: Parallel execution produces same output as sequential
4. •No resource exhaustion: System handles parallel load without failures
5. •Clear dependency graph: Can explain why operations were grouped into specific batches </success_indicators>

<testing_approach> Before parallelization:

1. •Run phase sequentially
2. •Record total time
3. •Record all outputs (files, reports, state changes)

After parallelization:

1. •Run phase with parallel batches
2. •Record total time
3. •Record all outputs

Validate:

• •Time reduced by expected factor (2-5x)
• •Outputs identical (diff files, compare checksums)
• •No errors or warnings introduced
• •Workflow state updated correctly

Rollback if:

• •Parallel version produces different outputs
• •Failures or race conditions occur
• •Time savings <20% (not worth complexity) </testing_approach> </validation>

<reference_guides> For deeper topics, see reference files:

Execution patterns: references/execution-patterns.md

• •Correct vs incorrect parallel execution patterns
• •Message structure for parallel tool calls
• •Handling tool call failures

Phase-specific guides:

• •references/optimize-phase-parallelization.md
• •references/ship-preflight-parallelization.md
• •references/implement-phase-parallelization.md

Dependency analysis: references/dependency-analysis-guide.md

• •Building dependency graphs
• •Detecting hidden dependencies
• •Handling edge cases

Troubleshooting: references/troubleshooting.md

• •Common failures and fixes
• •Performance not improving
• •Race condition debugging </reference_guides>

<success_criteria> The parallel-execution-optimizer skill is successfully applied when:

1. •Dependency graph created: All operations analyzed for dependencies before execution
2. •Batches identified: Independent operations grouped into parallel execution batches
3. •Single message per batch: Each batch executed via ONE message with multiple tool calls
4. •Time savings achieved: 2-5x speedup compared to sequential execution
5. •Correctness maintained: Parallel execution produces identical results to sequential
6. •No race conditions: No failures due to shared state or missing dependencies
7. •Appropriate scope: Only applied when ≥2 operations taking ≥1 minute each
8. •Clear documentation: Execution plan explained (layers, batches, expected speedup) </success_criteria>