--- name: plan description: Create a committed implementation plan from a feature spec. Explores the codebase, designs the approach, and produces docs/plans//plan.md plus individual task files. Use after writing a spec and before implementing. --- # 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//`. 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//spec.md`) — read it first - The codebase — explore relevant areas before designing ## Output - `docs/plans//plan.md` — a structured plan that links back to the spec and references every task file - `docs/plans//task--.md` — one independently executable implementation task per file --- ## Steps ### 1. Read the spec Read `docs/specs//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//plan.md`. Use this structure: ```markdown --- spec: docs/specs//spec.md created: YYYY-MM-DD status: draft --- # Implementation Plan: ## Overview 2-4 sentences. What changes, in what order, and why that order. --- ## Backend ### For each change: file path, exact struct/function/SQL, reason. ### ... ### ... --- ## Frontend > Skip this section if the spec has no user-facing changes. ### 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//.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-01-backend-contracts.md) - [ ] [task-02-backend-repository](task-02-backend-repository.md) Wave 2: - [ ] [task-03-frontend-ui](task-03-frontend-ui.md) Wave 3: - [ ] [task-04-e2e](task-04-e2e.md) ``` 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//task--.md`. Use this structure: ```markdown --- id: "01-backend-contracts" title: "Backend contracts" status: pending wave: 1 depends_on: [] plan: "plan.md" spec: "../../specs//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. - **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`.