implementation-task-plan

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.

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 <br/> 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"