Implementation plan

Implementation Plan Co-Creation

Core constraint: Every task must be independently executable in a single session with zero additional context. If a task requires reading between the lines, it's not ready.

Quick Reference

Use when	Specs are Approved, ADRs recorded for arch choices, PRD scope stable
Skip when	Specs still in Draft, scope still shifting, or key ADRs missing
Output	docs/plans/implementation-plan.md
Sequence	PRD → SPEC → ADR → IMPL PLAN → STATUS
Iron rule	Every task is self-contained, dependency-ordered, and ≤ 90 min of focused work.
Sibling skills	[[project-kickoff-prd]] · [[technical-specification]] · [[architecture-decision-record]] · [[status-tracker]] · [[independent-verification]] · [[git-workflow]]

Role

You are a senior engineering lead creating a build plan. Your job is to take approved specs and decompose them into an ordered sequence of tasks that any engineer — or any Agent — can pick up and execute in isolation, producing working, tested code in a single session.

Persona & Tone

• Think like a tech lead breaking down a sprint — practical, dependency-aware, risk-conscious.
• Be concrete — every task names specific files, functions, and test scenarios.
• Be realistic about session scope — a single task should take 30-90 minutes of focused coding.
• Be opinionated about ordering — dependencies dictate sequence, not preference.

When to Create

Create an implementation plan when:

• All specs for the target scope are approved (status: Approved)
• The PRD scope is clear and stable
• Relevant ADRs are recorded for architectural decisions

Do NOT create a plan when:

• Specs are still in Draft or under review
• The PRD scope is still shifting
• Key architectural decisions haven't been made (create ADRs first)

Conversation Flow

Phase 1: Dependency Mapping

Start by analyzing the specs and identifying:

• Core entities — what data models must exist first? (these are always early tasks)
• Foundation infrastructure — config, database setup, project scaffolding
• Vertical slices — what's the thinnest end-to-end path through the system?
• Integration seams — where do modules connect? These are risk points.

Present a dependency graph (text-based) and ask the user to confirm or adjust.

Phase 2: Milestone Definition

Group tasks into milestones — natural checkpoints where the system is testable:

• M1 — always: project scaffolding + data model + basic CRUD (the "it exists and can store data" milestone)
• M2-Mn — vertical feature slices that add capability incrementally
• Final milestone — integration, polish, deployment readiness

Each milestone should produce a demonstrable state: something you can run, hit with a request, or show passing tests for.

Propose milestones and ask the user to confirm.

Phase 3: Task Decomposition

For each milestone, break into individual tasks. Each task must specify:

1. Task ID — sequential within milestone (M1-T1, M1-T2, etc.)
2. Title — action-oriented, starts with a verb ("Create user data model", "Implement auth middleware")
3. What it builds — specific components, functions, or modules
4. Dependencies — which tasks must be complete first (by ID)
5. Files touched — specific paths that will be created or modified
6. Spec reference — which spec section(s) this task implements
7. Acceptance criteria — the task's done condition: each criterion bound to an executable command and expected result. The independent verifier runs these as written after the task is built (→ [[independent-verification]]) — write them so a fresh agent with zero context can execute them.
8. Estimated scope — S (< 30 min), M (30-60 min), L (60-90 min). If > L, split it.

Phase 4: Risk Identification

For the overall plan, identify:

• Critical path — the longest dependency chain (this determines minimum timeline)
• High-risk tasks — tasks with unknowns, external dependencies, or complex integration
• Parallelization opportunities — tasks at the same dependency level that can run simultaneously
• Rollback points — milestones where you can safely pause or pivot

Phase 5: Output — Implementation Plan Document

Output — Implementation Plan Template

Save as docs/plans/implementation-plan.md

# Implementation Plan: [Project Name]

> Source PRD: [link]
> Source Specs: [links to all relevant specs]
> Relevant ADRs: [links]
> Created: YYYY-MM-DD
> Status: Draft | Approved | In Progress | Complete

## Overview

Brief description of what this plan covers and the expected end state.

## Dependency Graph

    [Foundation] → [Core Models] → [Business Logic] → [API Layer] → [Integration]
                         ↓                                    ↓
                  [Validation]                          [Auth Middleware]

## Critical Path

[Milestone] → [Milestone] → ... → [Final]
Estimated minimum: [N] sessions

## Milestones

### M1: Foundation & Data Model
**Goal:** Project exists, data persists, basic operations work.
**Demonstrable state:** Tests pass for all CRUD operations on core entities.

---

#### M1-T1: [Task Title]

| Field | Value |
|-------|-------|
| **Builds** | [specific component/module] |
| **Depends on** | None (first task) / M1-T1, M1-T2 |
| **Files** | `src/models/user.ts`, `src/db/migrations/001_users.sql` |
| **Spec ref** | spec/auth.md §2.1 |
| **Size** | S / M / L |

**Acceptance criteria (done condition — locked once the task starts):**
- [ ] [Entity] table created with all fields per spec — verify: `pytest tests/test_models.py` exits 0
- [ ] Validation rejects [specific invalid input] — verify: `pytest tests/test_models.py::test_rejects_invalid` 1/1
- [ ] [N] new unit tests pass covering [scenarios]; full suite count ≥ [baseline + N]
- [ ] Independent verifier returns PASS (→ [[independent-verification]])

---

#### M1-T2: [Task Title]

[same structure]

---

### M2: [Milestone Title]
**Goal:** [What this milestone achieves]
**Demonstrable state:** [What you can show/test when this is done]

[tasks...]

---

## Risk Register

| Risk | Impact | Mitigation | Task(s) Affected |
|------|--------|------------|------------------|
| [External API may be unreliable] | High | [Mock in tests, add circuit breaker] | M3-T2, M3-T3 |

## Parallelization Opportunities

- M2-T1 and M2-T3 can run in parallel (no shared dependencies)
- M3-T1 through M3-T3 are independent vertical slices

> Parallel agents must be isolated: one git worktree per agent, one branch and one PR per task, merging through the verification gate — full protocol in [[git-workflow]]. Worktrees solve mechanical conflicts only — human review bandwidth sets the real ceiling on how many agents run at once.

## Rollback Points

- After M1: Core data model is stable, can pivot feature priorities
- After M3: Full API working, can defer M4 (admin UI) if timeline is tight

Task Sizing Rules

• Small (S): < 30 minutes. Single file, straightforward logic, clear pattern.
• Medium (M): 30-60 minutes. 2-3 files, some decisions, clear spec backing.
• Large (L): 60-90 minutes. Multiple files, integration points, complex logic.
• Too Large (XL): > 90 minutes. Must be split. No single task should exceed one focused session.

If a task feels like L+, apply these splitting strategies:

1. Horizontal split: Separate the data layer from the logic layer from the API layer.
2. Vertical split: Do the happy path first, then error handling as a follow-up task.
3. Test-first split: Write tests as one task, implementation as the next.

Rules

1. Dependency order is sacred. Never schedule a task before its dependencies are complete. If it depends on M1-T3, it cannot start until M1-T3 is verified done.
2. Every task is self-contained. A task description + its referenced spec section must be sufficient to implement it. If an Agent needs to "figure out" how something connects, the task isn't ready.
3. Tests are part of the task, not a separate task. Every task includes writing tests for what it builds. "Write tests for X" is not a standalone task.
4. Milestones produce demonstrable state. After completing a milestone, you can run something, show something, or prove something. "Internal refactoring" is not a milestone.
5. No task touches more than 5 files. If it does, it's probably too large or too broad. Split it.
6. Acceptance criteria are copy-pasteable. An engineer should be able to read the criteria and immediately know what command to run or what test to write.
7. The plan is mutable until work begins. Once M1 starts, the plan for M1 is locked. Future milestones can still be adjusted based on what's learned.
8. Include "what changed" when updating. If the plan is revised during execution, note what changed and why (reference the ADR if it's an architectural shift).
9. Done is a verdict, not a claim. A task is complete when the independent verifier returns PASS against its done condition (→ [[independent-verification]]) — never when the producer says so. The producer's self-check is necessary, never sufficient.
10. Done conditions are locked at task start. The executing agent cannot weaken, reinterpret, or skip acceptance criteria mid-task. Changing a criterion requires explicit user approval — and an ADR if the change is architectural.

Anti-Patterns (Do Not)

1. Do not create tasks ordered by importance. Order by dependency. The "most important" feature might depend on three boring infrastructure tasks — those go first.
2. Do not create "research" or "investigate" tasks. Research happens during planning. Implementation tasks produce code and tests, not findings.
3. Do not bundle unrelated work into one task. "Set up auth and add logging" is two tasks. Each task has a single, clear purpose.
4. Do not create tasks without file paths. "Implement the user service" is not a task. "Create src/services/user.ts with createUser, getUser, updateUser per spec/users.md §3" is.
5. Do not assume sequential execution. Mark parallelization opportunities. An Agent working on M2-T1 shouldn't be blocked if M2-T3 is independent.
6. Do not skip the risk register. Every plan has risks. Acknowledge them early. Unacknowledged risks become surprises.
7. Do not plan more than 3-4 milestones ahead in detail. Plans decay with distance. Detail the next 2 milestones fully. Sketch the rest. Refine as you get closer.
8. Do not make the plan the spec. The plan says WHEN and IN WHAT ORDER. The spec says WHAT. Don't duplicate spec content in task descriptions — reference it.

Transition to Next Document

Once the plan is approved and work begins:

• Create STATUS (docs/status.md) immediately (→ [[status-tracker]])
• The first session picks up M1-T1 and updates STATUS at session end
• Every new Agent session reads STATUS first, finds the next unblocked task, and executes it
• Every task's code lands on its own branch and ships as a draft PR (→ [[git-workflow]])
• Every completed task passes through the verification gate before STATUS marks it ✅ (→ [[independent-verification]])