| name | parallel-execution |
| description | Use when you have a multi-task action plan and want to execute tasks in parallel using automated subagent orchestration. Triggers on "split plan", "parallel tasks", "run in parallel", "execute plan in parallel" |
Parallel Execution v2
Automated subagent orchestration for parallel task execution. Give it an action plan, it analyzes dependencies, batches tasks, and dispatches subagents via the Task tool — with built-in progress tracking via TaskCreate/TaskUpdate/TaskList.
Constraint: Maximum 10 parallel subagents at any time (configurable). Tasks are dynamically scheduled as dependencies resolve.
Example: 7 tasks with 3 dependency types
├── Batch 0 (setup): shared-interfaces (soft dep contracts)
├── Batch 1 (parallel): db-schema, api-contracts, shared-types
├── Batch 2 (parallel): api-backend, unit-tests (hard dep on Batch 1)
└── Batch 3 (parallel): e2e-tests, docs (hard dep on Batch 2)
↑ dynamic re-batching: if api-backend finishes early,
e2e-tests can start before unit-tests completes
User Interaction Flow
┌─────────────────────────────────────────────────────────────────┐
│ 1. YOU: Provide action plan file (or task-spec.json) │
│ "Execute this plan in parallel" │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. SKILL: Validates inputs (Step 0) │
│ • Git repo check │
│ • Plan file exists │
│ • No conflicting parallel-execution tasks (TaskList check) │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. SKILL: Dispatches Plan subagent (Step 1) │
│ • Dependency analysis (hard / soft / optional) │
│ • Task list with IDs, complexity, file ownership │
│ • Circular dependency detection │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. SKILL: Dispatches Architect subagent (Step 2) │
│ • Batch scheduling with workload balance │
│ • Subagent type assignment per task │
│ • File conflict avoidance │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. YOU: Review & approve (Step 3) │
│ • Mermaid dependency graph │
│ • Batch schedule table │
│ • Scope isolation matrix │
│ [Approve] [Revise] [Cancel] │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. SKILL: Creates task entries (Step 4) │
│ • TaskCreate per task with full subagent prompt │
│ • Sets blockedBy/blocks for hard dependencies │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. SKILL: Executes batches (Step 5) │
│ • Announces subagents per CLAUDE.md protocol │
│ • Confirms via AskUserQuestion │
│ • Dispatches up to 10 subagents in parallel via Task tool │
│ • Reports results after each batch │
│ • Runs verification (build/test) if AutoVerify: true │
│ • TaskUpdate marks tasks completed │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 8. SKILL: Dynamic re-batching (Step 6) │
│ • After each task completes, checks for newly unblocked tasks │
│ • Starts early if running count < MaxParallelSessions │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 9. SKILL: Completion report (Step 7) │
│ • Summary table (task, status, subagent, files changed) │
│ • Verification results │
│ • Next steps (code review, commit) │
└─────────────────────────────────────────────────────────────────┘
Prerequisites
- Project must be a git repository
- Action plan file (markdown) or
task-spec.json from feature-dev Phase 1
- No other parallel-execution session running (checked via TaskList)
Configuration
Customize in project's CLAUDE.md:
## Parallel Execution Config
MaxParallelSessions: 10 # Max concurrent subagents (default: 10)
MaxRetries: 2 # Max retries per failed task (default: 2)
DynamicRebatching: true # Start tasks early when unblocked (default: true)
AutoVerify: true # Run build/test after each batch (default: true)
ScopeEnforcement: strict # strict = warn on file violations | relaxed = no checks
When NOT to Use
- Plan has fewer than 3 tasks (overhead not worth it)
- Tasks are tightly coupled (same files across tasks)
- Circular dependencies exist
- Single task with no parallelization opportunity
Usage
/parallel-execution path/to/action-plan.md
Or naturally:
Execute this plan in parallel using subagents
Dependency Types
| Type | Symbol | Meaning | Scheduling |
|---|
| Hard | → | Task B cannot start until Task A fully completes | Sequential batches, enforced via addBlockedBy |
| Soft | ⇢ | Task B needs Task A's interface defined, not full implementation | Batch 0 defines contracts, then both can parallelize |
| Optional | ⇝ | Task B benefits from Task A but can proceed independently | Same or any batch, no blocking |
Workflow Steps
Step 0: Input & Validation
- Accept plan file path (argument or ask user)
- Read and validate plan content
- Verify git repository
- Check TaskList for conflicting
[parallel-exec] tasks — block if found
- If plan is
task-spec.json, extract task definitions
Step 1: Dependency Analysis — Dispatch Plan Agent
Use Task tool with subagent_type: Plan
Prompt for Plan agent:
Analyze the following action plan and produce a dependency analysis:
1. **Task Identification**
- List all distinct tasks/steps with unique IDs
- Categorize each: database | backend-api | backend-models | frontend-ui | frontend-state | unit-tests | e2e-tests | documentation
- Estimate complexity: S (< 30 min) | M (30-90 min) | L (> 90 min)
2. **Dependency Graph (3 types)**
- **Hard dependencies** (→): Task B cannot start until Task A fully completes
- **Soft dependencies** (⇢): Task B needs Task A's interface/contract, not full implementation
- **Optional dependencies** (⇝): Task B benefits from Task A but can proceed without it
- Detect circular dependencies — report them as BLOCKING errors
3. **File Ownership Map**
- For each task, list files it will create or modify
- Flag conflicts: files claimed by multiple tasks
- Suggest resolution for conflicts (merge tasks or serialize)
4. **Interface Contracts**
- Identify shared interfaces, types, contracts between tasks
- If soft dependencies exist, define the contracts needed for Batch 0
**REQUIRED Output Format:**
Tasks:
- {task-id}: {name} | Category: {category} | Complexity: {S|M|L}
Files: {file-list}
Hard deps: {task-ids or "none"}
Soft deps: {task-ids or "none"}
Optional deps: {task-ids or "none"}
Circular Dependencies: {none | list}
File Conflicts: {none | list with resolution}
Interface Contracts: {list or "none needed"}
Plan content:
{plan_content}
Step 2: Task Design & Batching — Dispatch Architect Agent
Use Task tool with subagent_type: backend-architect
Prompt for Architect agent:
Based on this dependency analysis, design a batched execution schedule:
1. **Batch 0** (if soft dependencies exist)
- Single task to define shared interfaces/contracts
- Unblocks parallel implementation in Batch 1+
2. **Batches 1-N**
- Schedule tasks by: dependency resolution order, workload balance, file conflict avoidance
- Max 10 tasks per batch (configurable)
- Tasks in same batch should have similar complexity
- Avoid placing tasks with file conflicts in same batch
3. **Subagent Type Assignment**
Use this mapping (user can override):
| Task Category | Subagent Type |
|--------------|---------------|
| Database (tables, SPs) | backend-developer |
| Backend API (controllers, services) | backend-developer |
| Backend models/DTOs/interfaces | csharp-developer |
| Frontend UI (pages, components) | vue-expert |
| Frontend state/composables | vue-expert |
| Unit tests (.NET) | csharp-developer |
| E2E tests (Playwright) | test-automator |
| Documentation | general-purpose |
4. **Scope Isolation Matrix**
For each task, define:
- **OWN**: Files this task creates/modifies exclusively
- **DO NOT TOUCH**: Files owned by other tasks
- **READ ONLY**: Shared files for reference (e.g., interfaces, configs)
**REQUIRED Output Format:**
Batch Schedule:
- Batch 0: {task-id} (interface contracts) [if needed]
- Batch 1 (parallel): {task-id-1} [{subagent-type}], {task-id-2} [{subagent-type}], ...
- Batch 2 (parallel, after Batch 1): ...
- Batch N: ...
Scope Isolation:
- {task-id}:
OWN: {files}
DO NOT TOUCH: {files}
READ ONLY: {files}
Dependency analysis:
{analysis_from_step_1}
Step 3: Approval Presentation
Present to user with three artifacts:
1. Mermaid Dependency Graph
```mermaid
graph TD
subgraph "Batch 0"
T0[contracts: Define Interfaces]
end
subgraph "Batch 1"
T1[db-schema: Database Schema]
T2[shared-types: Shared Types]
end
subgraph "Batch 2"
T3[api-backend: Backend API]
T4[unit-tests: Unit Tests]
end
T0 -->|soft| T1
T0 -->|soft| T2
T1 -->|hard| T3
T2 -->|hard| T3
T2 -->|hard| T4
T3 -.->|optional| T4
classDef batch0 fill:#e1f5fe
classDef batch1 fill:#f3e5f5
classDef batch2 fill:#e8f5e9
class T0 batch0
class T1,T2 batch1
class T3,T4 batch2
```
2. Batch Schedule Table
| Task ID | Name | Batch | Complexity | Subagent Type |
|---------|------|-------|------------|---------------|
| contracts | Define Interfaces | 0 | S | csharp-developer |
| db-schema | Database Schema | 1 | M | backend-developer |
| shared-types | Shared Types | 1 | S | csharp-developer |
| api-backend | Backend API | 2 | L | backend-developer |
| unit-tests | Unit Tests | 2 | M | csharp-developer |
3. Scope Isolation Matrix
| Task ID | OWN (creates/modifies) | DO NOT TOUCH | READ ONLY |
|---------|----------------------|--------------|-----------|
| db-schema | Database/*.sql | Api/*, Web/* | shared-types output |
| api-backend | Api/Controllers/*, Api/Services/* | Database/*, Web/* | shared-types, db-schema |
User Gate: [Approve] / [Revise] / [Cancel] via AskUserQuestion
- Approve: Proceed to Step 4
- Revise: User provides feedback, re-run Step 2 with adjustments
- Cancel: Abort, clean up any state
Step 4: Task Creation via TaskCreate
For each task, create a TaskCreate entry:
TaskCreate:
subject: "[parallel-exec] {task-id}: {task-name}"
description: |
Full subagent prompt generated from @templates/task-prompt-template.md
Includes: scope, files, contracts, verification steps
activeForm: "Executing {task-name}"
Set dependencies using addBlockedBy / addBlocks for hard dependencies only.
Example:
Task "api-backend" → addBlockedBy: ["db-schema", "shared-types"]
Task "unit-tests" → addBlockedBy: ["shared-types"]
Step 5: Batch Execution — Subagent Dispatch
For each batch, follow the CLAUDE.md agent orchestration protocol:
-
ANNOUNCE which subagents will run:
Batch {N} requires the following subagents:
- {subagent-type} for {task-id}: {purpose}
- {subagent-type} for {task-id}: {purpose}
-
CONFIRM via AskUserQuestion before dispatching
-
INVOKE via Task tool — launch up to 10 subagents in parallel:
Task tool calls (parallel):
- subagent_type: {type}, prompt: {task-prompt from template}
- subagent_type: {type}, prompt: {task-prompt from template}
- subagent_type: {type}, prompt: {task-prompt from template}
-
COLLECT results from all subagents in batch
-
VERIFY (if AutoVerify: true):
- Run build command (e.g.,
dotnet build)
- Run relevant test suite
- Report pass/fail
-
UPDATE via TaskUpdate: mark completed tasks, report failures
-
REPORT batch results to user:
Batch {N} Complete:
| Task ID | Status | Files Changed | Notes |
|---------|--------|---------------|-------|
Error handling per task:
- If subagent fails: keep task
in_progress, offer retry (up to MaxRetries)
- If build fails: identify causing task, offer targeted retry
- If test fails: report failures, ask user: proceed or fix
- Partial batch failure: completed tasks stay completed, failed task only blocks its dependents
Step 6: Dynamic Re-batching
After each task completes (not just after each batch):
- Check TaskList for tasks where all
blockedBy are now completed
- Count currently running subagents
- If unblocked tasks exist AND running < MaxParallelSessions:
- Ask user: "Task {id} is now unblocked. Start early? [Yes/No]"
- If yes, dispatch immediately
- This is best-effort optimization — does not restructure the batch plan
Step 7: Completion Report
══════════════════════════════════════════════
PARALLEL EXECUTION COMPLETE
══════════════════════════════════════════════
Summary:
| Task ID | Status | Subagent | Files Changed |
|---------|--------|----------|---------------|
| db-schema | ✅ Completed | backend-developer | 3 files |
| shared-types | ✅ Completed | csharp-developer | 2 files |
| api-backend | ✅ Completed | backend-developer | 5 files |
| unit-tests | ✅ Completed | csharp-developer | 4 files |
Verification:
- Build: ✅ Passing
- Tests: ✅ 47/47 passing
Next Steps:
1. Review all changes (consider /code-review)
2. Commit: git add -A && git commit
3. Run full test suite
Subagent Summary
| Step | Agent | Purpose |
|---|
| 0 | — | Input validation |
| 1 | Plan | Dependency analysis (3 dep types, file ownership) |
| 2 | backend-architect | Batch scheduling, subagent assignment, scope isolation |
| 3 | — | User approval gate |
| 4 | — | TaskCreate entries with blockedBy |
| 5 | Per-task (see mapping) | Execute tasks (max 10 parallel) |
| 6 | — | Dynamic re-batching check |
| 7 | — | Completion report |
Total agents dispatched: 2 (analysis) + N (execution, max 10 at a time)
Subagent Type Mapping
| Task Category | Subagent Type |
|---|
| Database (tables, SPs) | backend-developer |
| Backend API (controllers, services) | backend-developer |
| Backend models/DTOs/interfaces | csharp-developer |
| Frontend UI (pages, components) | vue-expert |
| Frontend state/composables | vue-expert |
| Unit tests (.NET) | csharp-developer |
| E2E tests (Playwright) | test-automator |
| Documentation | general-purpose |
User can override any assignment during Step 3 approval.
Task Prompt Template
See @templates/task-prompt-template.md
Additional Resources
| Resource | Content |
|---|
| EXAMPLES.md | Complete examples with Mermaid graphs, batch execution, and completion reports |
| TROUBLESHOOTING.md | Subagent failure handling, retry logic, recovery procedures |
Integration
- feature-dev: Accepts
task-spec.json from Phase 1 as input
- session-orchestrator: Use /session-end after completion for handoff
- TaskCreate/TaskUpdate/TaskList: Built-in progress tracking
