| name | parallel-task-decomposition |
| description | Use when decomposing a feature into tasks that can be executed in parallel by independent sessions. Identifies file overlap, dependency chains, and assigns tasks to execution waves. Required for the planner agent. |
Parallel Task Decomposition
Your job: turn a feature spec into a set of tasks grouped into waves that can be safely executed in parallel within each wave.
Core Principles
- A wave is a set of tasks that can run simultaneously without conflict.
- Two tasks conflict if they touch the same file OR one logically depends on the other's output.
- The planner is the only intelligent component that resolves the parallelization tetris — the orchestrator just respects the wave assignments.
The Decomposition Process
Step 1: List atomic tasks
Break the feature into tasks of 5-20 minutes of focused work. Each task should:
- Have a single clear deliverable
- Touch a bounded set of files
- Have testable acceptance criteria
Step 2: Identify file ownership
For each task, list every file it will create or modify. Be exhaustive — missing files cause merge conflicts.
Step 3: Identify logical dependencies
Task B depends on task A if B imports from, calls, or references something A creates.
Step 4: Assign waves
Walk tasks in dependency order:
- A task with no incomplete dependencies and no file overlap with other wave-N candidates → goes in the next available wave
- A task that overlaps files with another wave-N candidate → must go in wave N+1 (sequential)
Cannot-parallelize examples:
- Two tasks both modifying
src/types/index.ts
- Two tasks both creating new endpoints in
src/routes/index.ts
- Two tasks both updating
package.json
Can-parallelize examples:
- Task A creates
src/models/user.ts, task B creates src/models/product.ts — different files
- Task A creates
src/services/auth.ts, task B creates src/services/billing.ts — even though both depend on shared types, if neither modifies the types file
- Task A and task B both depend on task C, but A and B don't depend on each other and touch different files → wave N+1, parallel
Step 5: Verify the slicing
Each wave should ideally have 2-5 parallel tasks. If you end up with 1 task per wave, you sliced wrong — try vertical slicing (one task = one feature top-to-bottom: model + service + route + test) instead of horizontal slicing (one task = all models, next task = all services).
The Wave Output Format
Tasks in PLAN.md must include:
- **wave**: 2
- **depends_on**: [task-01-user-model]
- **touches_files**:
- `src/services/auth.ts` (create)
- `src/types/tokens.ts` (create)
The orchestrator parses these to schedule execution. Be precise.
Anti-patterns to Avoid
- Hidden file dependencies: A task that says it touches
src/services/auth.ts but also adds an export to src/services/index.ts → mention BOTH files
- Logical dependencies hidden as "shared types": If task B imports a type from task A, that's a real dependency, not a parallel-safe assumption
- Wave 1 with one task and 5 tasks in wave 2: usually means wave 1 is doing too much — try slicing it further
- All tasks in one wave: if nothing depends on anything, double-check; usually some logical ordering exists (model before service before route)
Special Cases
Migration tasks
Database migrations must be sequential within a deploy. Even if two tasks add unrelated tables, give them sequential migration numbers and put them in different waves OR explicitly note they must be applied in a specific order.
Config files (package.json, tsconfig.json, etc.)
If multiple tasks need to modify config, collapse them into a single config-update task in wave 1 rather than letting parallel tasks fight over the file.
Cross-cutting refactors
If the feature requires renaming or refactoring across many files, that's its own task in its own wave (sequential, no parallel work on those files until the refactor is done).
