--- name: implementation-task-plan description: Generate an implementation task plan from design documents. Breaks a low-level design into ordered, dependency-aware tasks with explicit parallelization analysis. Use when you have a completed low-level design and need to plan the implementation work. argument-hint: "[prefix] [output path, or leave blank for plan/{prefix}-plan.md]" --- Generate a task plan that breaks a low-level design into implementable units with precise dependency and parallelization analysis. This is not a simple list of things to build. The plan must answer: - **What depends on what?** (hard prerequisites) - **What can truly run in parallel?** (independent packages, no shared files) - **What has no ordering dependency but can't be done simultaneously?** (same package, shared tests, merge conflict risk) ## Input The user may provide: $ARGUMENTS (prefix, custom output path, or constraints on task granularity) ## Expected Folder Structure ``` project/ ├── design/ │ ├── {prefix}-requirements.md # Reference: for traceability │ ├── {prefix}-high-level-design.md # Reference: for component context │ └── {prefix}-low-level-design.md # Primary input: drives the task breakdown ├── plan/ │ └── {prefix}-plan.md # Output: task plan (includes task status tracking) ``` ## Process ### Phase 1: Locate and Read Documents 1. **Determine the design prefix:** - If $ARGUMENTS provides a prefix (first word that is not a file path), look for `design/{prefix}-low-level-design.md`, `design/{prefix}-requirements.md`, and `design/{prefix}-high-level-design.md` - If no prefix is provided, scan `design/` for files matching `*-low-level-design.md` (this is the primary input) - **One match:** Use it and infer the prefix from the filename (e.g., `foo-low-level-design.md` → prefix is `foo`) - **Multiple matches:** Use AskUserQuestion listing the discovered files and ask the user which design to plan - **No matches:** Also check for an unprefixed `low-level-design.md`. If found, use it with no prefix. Otherwise, use AskUserQuestion to ask the user where to find the low-level design - Once the prefix is established from the low-level design file, use the same prefix to locate the requirements and high-level design files - If no prefix can be determined, ask the user 2. **Look for low-level design** at `design/{prefix}-low-level-design.md` — this is the primary input 3. **Look for requirements** at `design/{prefix}-requirements.md` 4. **Look for high-level design** at `design/{prefix}-high-level-design.md` 5. **If any are missing:** Use AskUserQuestion to ask the user where to find them. The low-level design is required. Requirements and high-level design are strongly recommended. Read all documents thoroughly. The low-level design is the primary source for task breakdown. The requirements provide traceability targets. The high-level design provides component context. ### Phase 2: Identify the Parallelization Topology Before breaking tasks down, map the structural boundaries that determine what can run in parallel. Extract from the low-level design: 1. **Package/module boundaries** — Each distinct package is a potential parallelization unit. Tasks within the same package touch shared files (test files, module declarations, re-exports) and will conflict if done concurrently. 2. **Cross-package dependencies** — The package dependency graph from the low-level design tells you which packages must exist before others can be built. 3. **Shared infrastructure** — Some things are used by everything: error types, configuration, shared utilities, test helpers. These must come first. Build a mental model of the workspace: ``` workspace/ ├── pkg-a/ ← depends on: pkg-core ├── pkg-b/ ← depends on: pkg-core, pkg-a ├── pkg-c/ ← depends on: pkg-core ├── pkg-core/ ← depends on: nothing └── test-helpers/ ← depends on: pkg-core ``` In this example: - `pkg-a` and `pkg-c` can be built **truly in parallel** (different packages, no shared files) - Two tasks within `pkg-a` are **order-independent but not parallel** (they'll edit the same test files, same module declarations) - `pkg-b` must wait for both `pkg-a` and `pkg-core` (**sequential dependency**) ### Phase 3: Break Down Tasks Walk through each package/module from the low-level design and create tasks for: **Per package, typically in this order:** 1. **Package scaffolding** — Create the package, set up module structure, add to workspace 2. **Core types** — Structs, enums, traits/interfaces defined in the class diagrams 3. **Trait/interface implementations** — One task per significant implementation 4. **Internal logic** — Private helpers, algorithms, state machines 5. **Unit tests** — Tests for the classes in this package (reference the testing strategy from the low-level design and the requirement IDs they cover) **Cross-cutting tasks:** 6. **Integration points** — Where packages wire together (these depend on both packages being complete) 7. **Integration tests** — End-to-end tests from the testing strategy (reference requirement IDs) 8. **Configuration & wiring** — Startup sequence, dependency injection, main entry point **Task sizing rules — the context window test:** The goal is that each task can be completed by a coding agent in a single context window. That means the agent needs to read the relevant existing code, understand the task, write the implementation, and verify it — all without running out of context. Use these guidelines: - **One file is the ideal unit.** A task that creates or modifies a single file is almost always the right size. - **Tightly coupled files are okay** — e.g., a struct and its unit test file, or a trait definition and its one impl. But keep it to 2-3 files max, and only when they genuinely can't be split. - **Each file should not be individually complex.** If a single file involves a large state machine, complex algorithm, AND extensive error handling, that's probably two tasks even though it's one file. - **The agent must be able to hold the full picture.** If completing the task requires reading more than ~5-6 existing files for context, the task is scoped too broadly. - **A task must be verifiable on its own** — it should compile and its tests should pass with only prerequisite tasks complete. - **If a task touches more than one package, it's almost certainly too big** — split it. **Splitting heuristics — when in doubt, split:** - A struct with many methods → one task for the struct + core methods, another for secondary methods - A trait with multiple implementors → one task per implementor - A test file covering many behaviors → split by the requirement IDs being tested - An integration test that exercises a long workflow → split into setup/infrastructure task + test task ### Phase 4: Classify Dependencies For every task, classify its relationship to every other task using these three categories: #### Category 1: Sequential (Hard Dependency) Task B **requires** Task A's output to exist. Task B literally cannot be written or compiled without Task A being done. Examples: - Implementing a repository requires the domain types it operates on - Writing an API handler requires the service layer it calls - Integration tests require all the components they exercise Notation: `depends on: Task X.Y` #### Category 2: Order-Independent (Soft Conflict) Tasks have no logical dependency — either could be done first — but they touch shared files or shared state, so doing them concurrently would cause merge conflicts or require careful coordination. Examples: - Two struct implementations in the same package (both modify `mod.rs` / `lib.rs` / `__init__.py`) - Two sets of unit tests that share a test helper file - Two features that both add entries to a configuration struct - Tasks that both modify `Cargo.toml` / `package.json` / `go.mod` Notation: `conflicts with: Task X.Z` (with reason: "shared test file", "both modify mod.rs", etc.) #### Category 3: Truly Parallel (Independent) Tasks have no logical dependency AND no shared files. They can be assigned to different agents/developers and worked on simultaneously. The only coordination needed is at commit time — all tasks in a parallel batch must complete before committing. Examples: - Tasks in completely separate packages with no shared files - A documentation task and a code task - Two independent leaf packages that only depend on a shared core Notation: `parallel with: Task A.B, Task C.D` (explicitly named) ### Phase 5: Organize into Execution Batches Group tasks into **batches** — sets of tasks that can be executed together. A batch completes when ALL tasks in it are done, then the next batch can begin. **Batch rules:** - All tasks in a batch must have their sequential dependencies satisfied by previous batches - Within a batch, distinguish **parallel tracks** (truly independent) from **serialized tracks** (order-independent but conflicting) - A batch should be committable — when all tasks in a batch are done, the project should compile and all existing tests should pass **Batch structure:** ``` Batch 1: Foundation Track A (serial): Task 1.1 → Task 1.2 → Task 1.3 [pkg-core types] Track B (serial): Task 1.4 [test helpers] Tracks A and B are PARALLEL (different packages) Batch 2: Core Services Track A (serial): Task 2.1 → Task 2.2 [pkg-a] Track B (serial): Task 2.3 → Task 2.4 [pkg-c] Track C (serial): Task 2.5 [pkg-a unit tests] Tracks A and B are PARALLEL (different packages) Tracks A and C CONFLICT (same package — serialize within this track) Batch 3: Integration Layer Track A (serial): Task 3.1 → Task 3.2 [pkg-b, depends on pkg-a] (single track — no parallelization possible) ``` ### Phase 6: Generate the Plan Create `plan/{prefix}-plan.md` (or custom path from $ARGUMENTS if provided) using the template in [template.md](template.md). **Mermaid Diagram Rules** (required for renderer compatibility — GitLab, GitHub, VS Code use older Mermaid.js): - Always quote flowchart node labels: `A["Start here"]` not `A[Start here]` - Always quote decision nodes: `B{"Is it ready?"}` not `B{Is it ready?}` - Always quote subgraph titles: `subgraph sg["My Group"]` not `subgraph sg[My Group]` - Prefer `A -- "label" --> B` link syntax over `A -->|"label"| B` - Keep labels short — move detail into surrounding prose - NO `
` in any label or node text - NO `<-->` bidirectional arrows — use two separate directed arrows - NO special characters in state/flowchart labels: `()` `.` `/` `→` `__` — use plain words The plan must include: 1. **Overview** — Project summary, total task count, batch count, estimated parallel speedup 2. **Package Dependency Graph** — Mermaid diagram of package-level dependencies (from the low-level design) 3. **Execution Batches** — Each batch with: - Parallel tracks clearly labeled - Conflict annotations within tracks - Commit checkpoint description 4. **Task Details** — For each task: - Prerequisites (sequential dependencies) - Conflicts (order-independent but shared files — name the shared files) - Parallel group (what it can run alongside) - Objective - Instructions (specific file paths, type signatures, implementation details from the low-level design) - Verification (what to run to confirm it works) - Requirements covered (FR-x.x.x IDs from the testing strategy) 5. **Task Status Tracker** — A table at the end of the plan listing every task with its status (`[ ]` not started, `[~]` in progress, `[x]` completed), prerequisites, and conflicts. This is the single source of truth for task progress — no separate tracking file. 6. **Critical Path** — The longest sequential chain through the batch graph. This is the minimum time to complete all work even with unlimited parallelism. 7. **Parallelization Summary** — Table showing which batches have parallel tracks, what the theoretical speedup is, and what the commit coordination requirements are. 8. **Requirements Traceability** — Map from FR-x.x.x to the task(s) that implement and test each requirement. ### Phase 7: Validate the Plan Before finalizing, verify: - [ ] Every class/struct from the low-level design's class diagrams has a task that creates it - [ ] Every interaction from the low-level design's sequence diagrams is covered by tasks - [ ] Every unit test from the low-level design's testing strategy appears in a task - [ ] Every integration test from the low-level design's testing strategy appears in a task - [ ] Every FR-x.x.x from the requirements appears in the traceability table - [ ] No task has a circular dependency - [ ] Every batch is committable (project compiles, tests pass after batch completes) - [ ] Conflict annotations are specific (name the shared files, not just "same package") - [ ] Parallel tracks within a batch are truly independent (no shared files) - [ ] The critical path is realistic ## Output Create `plan/{prefix}-plan.md` (create `plan/` directory if needed). The plan should be: - **Dependency-precise:** Every sequential dependency, soft conflict, and parallel opportunity explicitly called out - **Batch-oriented:** Work organized into committable batches, not just a flat list - **Traceable:** Every task links back to the low-level design and every requirement has a task - **Honest about parallelism:** Distinguishes "can run simultaneously" from "order doesn't matter but will conflict"