Create Implementation Plan

This is a primary-session artifact skill. The user-started conversation creates the plan and task files, then returns control with a handoff. The user reviews the files, switches that same conversation to an implementation model if desired, and sends the explicit request to execute them.

Translate a feature spec into a concrete, phased implementation plan saved under docs/plans/<feature>/. Plans and task files are committed implementation records for the current buildout; specs remain the durable requirements under docs/specs/.

Input

• The feature spec (docs/specs/<slug>/spec.md) — read it first
• The codebase — explore relevant areas before designing

Output

• docs/plans/<slug>/plan.md — a structured plan that links back to the spec and references every task file
• docs/plans/<slug>/task-<NN>-<short-slug>.md — one independently executable implementation task per file

Steps

1. Read the spec

Read docs/specs/<slug>/spec.md in full. Identify:

• The observable behaviors (What section)
• The scenarios — each is a potential test case
• Any out-of-scope items (don't plan for these)

2. Explore the codebase

Search in parallel for all integration points the spec touches:

• Relevant models, repos, services, handlers
• Similar existing features to reuse as patterns
• Frontend state slices, hooks, and components in the area
• Existing tests in the area (to understand the testing patterns)

Use docs/decisions/INDEX.md to check for relevant architectural decisions.

Map dependencies before writing tasks. Implementation order follows the dependency chain: persistence/contracts first, service behavior next, API/client wiring after that, then UI and E2E. Prefer vertical slices that leave the product working over broad horizontal layers that cannot be verified until the end.

3. Ask before designing (if needed)

If the spec leaves implementation choices open, ask — one question at a time. Do not assume. Examples of things to ask:

• Which table/model owns new data?
• Is a new API endpoint needed or does an existing one extend?
• Should this be behind a feature flag?

Stop asking when you have enough to write the plan.

4. Write plan.md

Save to docs/plans/<slug>/plan.md. Use this structure:

---
spec: docs/specs/<slug>/spec.md
created: YYYY-MM-DD
status: draft
---

# Implementation Plan: <Feature Name>

## Overview
2-4 sentences. What changes, in what order, and why that order.

---

## Backend

### <Area 1 — e.g., Schema Changes>
For each change: file path, exact struct/function/SQL, reason.

### <Area 2 — e.g., Service Layer>
...

### <Area N>
...

---

## Frontend

> Skip this section if the spec has no user-facing changes.

### <Component / Page>
File path, what changes, why.

### API client
What new calls are needed and where they go.

### State
Store slice / hook changes.

---

## Tests

Every plan MUST include this section. For each testable behavior in the spec,
list the exact pre-PR validation:
- **What:** the behavior under test (maps to a spec scenario)
- **File:** where the test goes (`*_test.go` or `*.test.ts`)
- **How:** table-driven unit test / integration test with real DB / mock service

At minimum, include:
- One unit test per new function with non-trivial logic
- One integration test that exercises the full path (handler → service → repo)
- One test per edge case called out in the spec scenarios

Do not add a generic local QA, review, security, simplify, or full-verification
step to the plan. The listed task checks are the pre-PR evidence; the two PR AI
reviewers perform semantic review after the PR opens.

---

## E2E Tests

> Skip this section only if the spec has zero user-visible UI changes.

For each user-facing scenario in the spec:
- **Scenario:** restate the GIVEN/WHEN/THEN from the spec
- **File:** `apps/web/e2e/<area>/<name>.spec.ts`
- **What to verify:** the observable outcome (URL change, element visible, toast shown)

---

## Verification Results
Pending. On completion, synchronize this section with each task's `## Results`:
record exact commands and outcomes/counts, generated artifact paths, and
cleanup/teardown evidence.

---

## Implementation Waves And Parallel Candidates

Group task files by dependency order. Use waves to expose possible parallelism,
but label a task as parallel-safe only when its files are disjoint and it does
not touch shared schemas, migrations, generated contracts, lockfiles, or
package-wide configuration. E2E follows the backend and frontend changes it
covers.

The default is sequential execution in the primary conversation. Waves do not
authorize subagents: only the user may explicitly ask to use them after
selecting the implementation model.

Wave 1 (parallel candidates — user authorization required):

• task-01-backend-contracts
• task-02-backend-repository

Wave 2:

• task-03-frontend-ui

Wave 3:

• task-04-e2e

For small features (≤3 tasks total), waves are optional — list sequentially.

The plan links to task files; it does not contain full task bodies. Update the
checkbox/status link when a task is completed.

---

## Open Questions
(Delete when empty.)

5. Write task files

Create one task file beside plan.md per task, named docs/plans/<slug>/task-<NN>-<short-slug>.md. Use this structure:

---
id: "01-backend-contracts"
title: "Backend contracts"
status: pending
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/<slug>/spec.md"
---

# Task 01: Backend contracts

Each task should be small enough for one focused implementation pass:
- **Acceptance:** 1-3 concrete conditions.
- **Verification:** exact command(s), e.g. `cd apps/backend && go test -run TestName ./internal/path/...` or `cd apps && pnpm --filter @kandev/web test -- path/to/file.test.ts`. Frontend/E2E tasks must include the fresh-worktree bootstrap (`cd apps && pnpm install --frozen-lockfile`) when dependencies may be absent; direct web typechecking uses `cd apps/web && pnpm run typecheck`, while other workspace package commands use the documented `pnpm --filter` form. Backend commands should use the applicable repository `make` target when one exists. If several commands are required, write them as one sequentially runnable block rooted at a single directory (for example, `cd apps && ... && ...`) or make each `cd` explicit; do not rely on the caller's working directory surviving between commands.
- **Files likely touched:** specific paths, not broad directories.
- **Dependencies:** task numbers that must land first, or `None`.
- **Parallelism:** `sequential` by default; set `parallel-safe` only with named
  disjoint files and no shared-state blocker.
- **Inputs:** relevant spec sections, plan sections, patterns, and dependencies.
- **Output contract:** summary, files changed, tests run, blockers, risks, and
  task/plan status update in the same conversation.

## Results
Pending. Before marking the task done, replace this with every exact command
actually run and its outcome/count, generated artifact paths, and cleanup or
teardown evidence (including temporary capture-spec removal and
`git diff --check` when used). Record security/trust and external side-effect
boundaries when applicable, or explicitly state `None`.

Break a task down further if it touches unrelated subsystems, needs more than one focused session, or the title contains "and".

When an implementation agent starts the task, it must change `status` to
`in_progress`. Before it finishes, reconcile **Files likely touched** with the
actual diff, including modified existing tests used as E2E evidence. It may then
change `status` to `done`, update its `## Results`, and synchronize the
corresponding checkbox/status and `## Verification Results` in `plan.md`.

6. End the design turn

After plan.md and every task file are written and validated, report their paths, dependency order, exact checks, and open risks as a compact handoff, then end the turn. Do not call ask_user_question_kandev (or an equivalent approval prompt) to ask the user to approve the plan or switch models. The user reviews the artifacts and controls the next implementation request and model choice.

Style rules

• Be specific. Name exact file paths, function signatures, SQL column names. The implementing agent should not need to re-explore the codebase.
• No speculation. Only plan what the spec requires. Do not add "nice to have" items.
• Tests are not optional. Every plan must have a Tests section. E2E is required whenever there are UI changes.
• Frontend is not optional. If the spec has any user-visible behavior, the plan must have a Frontend section.
• Keep it proportional. A small spec gets a 1-page plan. A large spec may need 3-4 pages. Do not pad.
• Keep task bodies out of the plan. Put implementation details in individual task files and link to them from plan.md.