parallel-task-decomposition

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

1. A wave is a set of tasks that can run simultaneously without conflict.
2. Two tasks conflict if they touch the same file OR one logically depends on the other's output.
3. 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).