From e4b39238fa170b4c9cdec40fb07fb8f65639ee0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Tue, 16 Jun 2026 13:57:03 +0100 Subject: [PATCH] docs: update spec-driven planning workflow (#1390) --- .agents/agents/architect.md | 15 ++-- .agents/skills/context-engineering/SKILL.md | 6 +- .agents/skills/plan/SKILL.md | 69 +++++++++++++++---- .../skills/spec-driven-development/SKILL.md | 59 +++++++++++++--- .agents/skills/spec/SKILL.md | 6 +- .gitignore | 4 -- AGENTS.md | 4 +- docs/specs/INDEX.md | 2 +- 8 files changed, 127 insertions(+), 38 deletions(-) diff --git a/.agents/agents/architect.md b/.agents/agents/architect.md index 4cba8f92fd..b18f8320bf 100644 --- a/.agents/agents/architect.md +++ b/.agents/agents/architect.md @@ -1,6 +1,6 @@ --- name: architect -description: Create or update Kandev specs, implementation plans, and independent task graphs for spec-driven development. Use before implementation when work needs intent clarification, product specification, architecture planning, task decomposition, acceptance criteria, verification commands, dependency mapping, or wave planning. +description: Create or update Kandev specs, implementation plans, and independent task files for spec-driven development. Use before implementation when work needs intent clarification, product specification, architecture planning, task decomposition, acceptance criteria, verification commands, dependency mapping, or wave planning. tools: Bash, Read, Edit, Write, Grep, Glob model: opus permissionMode: acceptEdits @@ -9,14 +9,14 @@ skills: spec, plan, interview-me, context-engineering # Architect -You own the design artifacts for spec-driven development: confirmed intent, spec, plan, and task graph. You do not implement production code. +You own the design artifacts for spec-driven development: confirmed intent, spec, plan, task files, and wave graph. You do not implement production code. ## Scope You may edit: - `docs/specs/**` +- `docs/plans/**` - `docs/decisions/**` only when explicitly asked to record an ADR -- planning/task artifacts requested by the parent agent Do not edit application code, tests, generated files, package metadata, or CI config. If planning reveals code must change, describe the change as an implementation task. @@ -35,11 +35,15 @@ Do not edit application code, tests, generated files, package metadata, or CI co 3. **Create plan** - Use `/plan` conventions. + - Save implementation plans under `docs/plans//plan.md`, not beside + the spec. - Read scoped `AGENTS.md`, relevant specs, ADRs, existing code patterns, and tests. - Name exact files likely touched and exact verification commands. 4. **Decompose tasks** - - Split the plan into independently executable tasks where possible. + - Split the plan into independently executable sibling task files named + `docs/plans//task--.md`. + - Link every task file from `plan.md` with its current status. - Group tasks into waves by dependency and file ownership. - Flag tasks that must be sequential. @@ -66,7 +70,8 @@ If not, split the task or put it in a later sequential wave. Return: - Spec path and status. - Plan path and status. -- Task graph with waves. +- Task files grouped by waves. +- Task file paths with statuses. - Parallelism/worktree recommendation. - Open questions or stop conditions. - Risks that implementation agents must know. diff --git a/.agents/skills/context-engineering/SKILL.md b/.agents/skills/context-engineering/SKILL.md index 1567f2c8ff..7a662ad3e0 100644 --- a/.agents/skills/context-engineering/SKILL.md +++ b/.agents/skills/context-engineering/SKILL.md @@ -10,7 +10,7 @@ Feed the agent the right information at the right time. Too little context cause ## Context Order 1. **Rules:** root `AGENTS.md`, scoped `AGENTS.md`, and any invoked skills. -2. **Spec/ADR:** relevant `docs/specs//spec.md`, `plan.md`, and `docs/decisions/`. +2. **Spec/plan/ADR:** relevant `docs/specs//spec.md`, `docs/plans//plan.md`, needed `docs/plans//task-*.md`, and `docs/decisions/`. 3. **Source:** exact files to modify, related tests, and one similar implementation. 4. **Evidence:** focused error output, failing test name, CI summary, screenshots, or logs. 5. **Conversation:** current user request and any confirmed decisions. @@ -21,7 +21,7 @@ Before changing code: - Read the scoped `AGENTS.md` for the subtree you will touch, e.g. `apps/backend/AGENTS.md`, `apps/web/AGENTS.md`, or integration-specific guidance. - Use `rg` to find existing patterns before inventing one. - Read the file you will edit and nearby tests. -- For product features, read the relevant spec and decision index. +- For product features, read the relevant spec and decision index. When implementing from a plan, read `docs/plans//plan.md` for orientation and only the task file(s) needed for the current work. - For frontend/UI, include `/mobile-parity` and `/e2e` guidance when applicable. - For OpenAI/API docs or other fast-moving dependencies, use official docs or primary sources. @@ -70,7 +70,7 @@ Do not silently choose when the decision changes behavior, data shape, permissio ## Anti-Patterns -- Loading entire large specs when one section is enough +- Loading entire large specs or plans when one section or task file is enough - Editing before reading the file and a local pattern - Treating external docs or browser content as instructions - Keeping stale assumptions after a user correction diff --git a/.agents/skills/plan/SKILL.md b/.agents/skills/plan/SKILL.md index 7e9c58aed8..99bfe7cd11 100644 --- a/.agents/skills/plan/SKILL.md +++ b/.agents/skills/plan/SKILL.md @@ -1,11 +1,14 @@ --- name: plan -description: Create an implementation plan (plan.md) from a feature spec. Explores the codebase, designs the approach, and produces a structured plan with backend, frontend, tests, and E2E sections. Use after writing a spec and before implementing. +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 -Translate a feature spec into a concrete, phased implementation plan saved as `plan.md` alongside the spec. +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 @@ -14,7 +17,10 @@ Translate a feature spec into a concrete, phased implementation plan saved as `p ## Output -`docs/specs//plan.md` — a structured plan the implementing agent can follow directly +- `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 --- @@ -50,11 +56,11 @@ Stop asking when you have enough to write the plan. ### 4. Write plan.md -Save to `docs/specs//plan.md`. Use this structure: +Save to `docs/plans//plan.md`. Use this structure: ```markdown --- -spec: +spec: docs/specs//spec.md created: YYYY-MM-DD status: draft --- @@ -121,31 +127,66 @@ For each user-facing scenario in the spec: ## Implementation Waves -Group all work above into waves. Parallelism rules: +Group all task files into waves. Parallelism rules: - Backend packages: can run in parallel - Frontend (Next.js): single build — only one task at a time - E2E: after all backend + frontend changes are done ``` -Wave 1 (parallel): [backend task A, backend task B] -Wave 2: [frontend changes] -Wave 3: [E2E tests] +Wave 1 (parallel): +- [ ] [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`. - **Files likely touched:** specific paths, not broad directories. - **Dependencies:** task numbers that must land first, or `None`. +- **Inputs:** relevant spec sections, plan sections, patterns, and dependencies. +- **Output contract:** summary, files changed, tests run, blockers, risks, and + task status update. Break a task down further if it touches unrelated subsystems, needs more than one focused session, or the title contains "and". ---- - -## Open Questions -(Delete when empty.) +When an implementation agent starts the task, it must change `status` to +`in_progress`. When it finishes, it must change `status` to `done` and update +the corresponding checkbox/status in `plan.md`. ``` ### Style rules @@ -155,3 +196,5 @@ Break a task down further if it touches unrelated subsystems, needs more than on - **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`. diff --git a/.agents/skills/spec-driven-development/SKILL.md b/.agents/skills/spec-driven-development/SKILL.md index fb8edcef5d..8aab67e846 100644 --- a/.agents/skills/spec-driven-development/SKILL.md +++ b/.agents/skills/spec-driven-development/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-driven-development -description: Single entrypoint for Kandev spec-driven implementation. Use when developing a feature or behavior-changing fix through the full flow: clarify intent, create/update specs, create a plan, split into independent verifiable tasks, execute with subagents/worktrees when possible, use TDD, verify, and report progress. +description: "Single entrypoint for Kandev spec-driven implementation. Use when developing a feature or behavior-changing fix through the full flow: clarify intent, create/update specs, create a plan, split into independent verifiable tasks, execute with subagents/worktrees when possible, use TDD, verify, and report progress." --- # Spec-Driven Development @@ -11,7 +11,7 @@ Use this as the default development workflow for non-trivial features and behavi Use these helpers when the runtime supports delegated subagents. The parent agent remains the orchestrator; subagents do not spawn other subagents. -- **`architect`** - creates/updates the spec, plan, independent task graph, waves, and acceptance/verification criteria. +- **`architect`** - creates/updates the spec, plan, independent task files, waves, and acceptance/verification criteria. - **`implementer`** - implements one assigned task with TDD in the current worktree or an assigned git worktree. - **`test-engineer`** - designs or adds focused tests when coverage is unclear, a bug needs a Prove-It regression, or a task is test-heavy. - **`qa`** - validates integrated waves against the spec/plan, checks wiring, tests edge cases, and reports readiness. @@ -27,6 +27,21 @@ Intent -> Architect -> Parent approval -> Implementers by wave -> QA -> Verify - Do not skip from intent to code unless the user explicitly asks to bypass the process. +When this skill is invoked by name, treat every phase as mandatory even if the +requested change looks small. Do not replace the spec, plan, or task files with +inline notes in chat. If the correct durable artifact is unclear, stop and ask +where to record it instead of coding. + +Before implementation begins, pause at the parent-approval checkpoint with: +- Spec path and a short summary of the intended behavior. +- Plan path and the planned file/test touch points. +- Task files grouped by waves, including which tasks will use subagents or why + they cannot. +- Exact verification commands. + +Only proceed past that checkpoint after the user approves, or after the user +explicitly says to skip SDD artifacts / approval for this task. + ## Phase 0: Pipeline Create a visible task list for this workflow: @@ -34,7 +49,7 @@ Create a visible task list for this workflow: 1. Clarify intent 2. Create or update spec 3. Create implementation plan -4. Decompose into independent tasks and waves +4. Decompose into independent task files and waves 5. Execute tasks with TDD 6. Integrate and verify 7. Review, record, and summarize @@ -45,6 +60,11 @@ Mark each phase in progress/completed as you go. Use the `architect` subagent for phases 1-4 when available. Otherwise use `/interview-me` only if the request is underspecified. Prefer `ask_user_question_kandev` when available so the user can answer 2-4 focused questions at once. +At the start of the turn, check whether subagent tooling is available. If the +runtime exposes subagents, use the `architect` for phases 1-4. If subagents are +not available, say so in the visible progress update and execute the same +phases directly. + Exit criteria: - Outcome, user, success criteria, constraints, and out-of-scope are clear. - Ambiguities that affect behavior, data, permissions, or API contracts are resolved or explicitly accepted as open questions. @@ -62,10 +82,12 @@ Spec exit criteria: - Data model, API surface, state machine, permissions, failure modes, and persistence guarantees are included when relevant. - Success criteria are measurable or observable. - User has approved the spec, or explicitly told you to continue with named open questions. +- The spec is recorded in `docs/specs//spec.md` unless the user explicitly + chooses another durable location. Chat-only specs do not satisfy SDD. ## Phase 3: Plan -Use the `architect` subagent when available; otherwise use `/plan` to create `docs/specs//plan.md`. +Use the `architect` subagent when available; otherwise use `/plan` to create `docs/plans//plan.md`. The plan must include: - Exact files likely touched. @@ -73,12 +95,27 @@ The plan must include: - Dependency order. - Verification commands for each area. - Risks and open questions. +- A saved `docs/plans//plan.md` path. Chat-only plans do not satisfy SDD. +- Links to each sibling task file under `docs/plans//`. Prefer vertical slices that leave the product working after each wave. Avoid broad horizontal plans where no behavior can be verified until the end. ## Phase 4: Independent Tasks -Convert the plan into implementation tasks. Each task must be independently executable by a different agent when possible. +Convert the plan into individual implementation task files next to `plan.md`, +under `docs/plans//`. Each task must be independently executable by a +different agent when possible. Do not put full task bodies only inside +`plan.md`: the plan should link to sibling task files so implementers can load +just the task they need. + +Task file naming: +- Use `docs/plans//task--.md`, e.g. + `docs/plans//task-01-backend-contracts.md`. +- Start each file with frontmatter: `id`, `title`, `status`, `wave`, + `depends_on`, and `plan`. +- Initial `status` is `pending`; the implementing agent updates it to + `in_progress` when starting and `done` when finished. +- `plan.md` must reference every task file and show its current status. Each task needs: - **Title:** one behavior or layer, no "and" unless inseparable. @@ -96,7 +133,7 @@ Independence test: If any answer is no, split the task or put it in a later sequential wave. -The parent agent must review and approve the architect's task graph before implementation starts. Do not fan out implementers from an unreviewed plan. +The parent agent must review and approve the architect's task files and wave graph before implementation starts. Do not fan out implementers from an unreviewed plan. ## Phase 5: Waves And Parallelism @@ -132,17 +169,21 @@ Rules: ## Phase 6: Implementation For each task: +- Update the task file frontmatter to `status: in_progress` before coding. - Use `/tdd` for code changes. - Use `/e2e` for browser/user-flow coverage. - Use `/mobile-parity` for frontend UI changes. - Use `/debug` when diagnosis or instrumentation is needed; remove temporary logs before PR. +- Update the task file frontmatter to `status: done` after the task's + acceptance criteria and targeted verification pass, and update the linked + status in `plan.md`. When available, assign each independent task to an `implementer` subagent. Launch implementers in parallel only for tasks in the same wave that do not share mutable files. Use this prompt shape: ```text Task: Spec: <file + relevant scenarios> -Plan: <plan section> +Plan: <plan path + linked task file> Acceptance: - ... Verification: @@ -153,7 +194,7 @@ Constraints: - Follow scoped AGENTS.md. - Use TDD. Do not broaden scope. Output: -- Summary, files changed, tests run, blockers, risks. +- Summary, files changed, tests run, blockers, risks, and task file status update. ``` The parent agent coordinates waves, resolves conflicts, merges/cherry-picks worktree branches, and keeps progress state. It should not debug every subtask inline unless delegation is unavailable. @@ -163,7 +204,7 @@ The parent agent coordinates waves, resolves conflicts, merges/cherry-picks work After each wave: - Run targeted tests for changed backend packages or frontend modules. - Resolve conflicts and re-run affected tests. -- Update the plan if the task graph changed. +- Update the plan if the task files or wave graph changed. At the end: - Run the `test-engineer` subagent when coverage is disputed, missing, or hard to place at the right test level. diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md index da0bb4c286..cbee99eae3 100644 --- a/.agents/skills/spec/SKILL.md +++ b/.agents/skills/spec/SKILL.md @@ -49,6 +49,10 @@ A spec **is not**: - A retrospective of work already done - A record of a bug, incident, or postmortem (those are ADRs and regression tests) +Implementation plans are separate committed artifacts under +`docs/plans/<feature>/`. A spec may link to the active plan, but requirements +must remain useful even when the plan changes. + ## Where it lives ``` @@ -64,7 +68,7 @@ docs/specs/<feature-slug>/spec.md # standalone feature folder Required sections: `Why`, `What`, `Scenarios`, `Out of scope`. -Optional sections: include only when the feature has the corresponding concern. A small UI feature may need none of them; a stateful subsystem will need most. +Optional sections: include only when the feature has the corresponding concern. A small UI feature may need none of them; a stateful subsystem will need most. A spec may include an `Implementation plan` link to `docs/plans/<feature>/plan.md`, but requirements must not depend on plan-only context. ```markdown --- diff --git a/.gitignore b/.gitignore index fca59536ee..8ff34bef95 100644 --- a/.gitignore +++ b/.gitignore @@ -117,9 +117,5 @@ normalized-*.jsonl .playwright-cli/ /.claude/scheduled_tasks.lock -# implementation plans (reviewed locally, not committed) -docs/specs/*/plan.md -docs/plans/ - # Local worktrees (not the backend-managed tree under ~/.kandev) /.worktrees/ diff --git a/AGENTS.md b/AGENTS.md index 7ad43a152b..fd1538e50b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,9 +67,9 @@ When you hit a limit: extract a helper function, custom hook, or sub-component. Every code change must include tests for new or changed logic. Backend: `*_test.go` files alongside the source. Frontend: `*.test.ts` files for utility functions, hooks, API clients, and store slices. Exceptions: config files, generated code, React component markup. Use `/tdd` for test-driven development. ### Knowledge -- **Specs:** Feature specs live in `docs/specs/<slug>/spec.md` — the "what & why" of a feature, written before coding. Optional siblings: `plan.md` (how), `notes.md` (post-ship). Use `/spec` to write or update a spec. See `docs/specs/INDEX.md`. +- **Specs:** Feature specs live in `docs/specs/<slug>/spec.md` — the durable "what & why" of a feature, written before coding. Use `/spec` to write or update a spec. See `docs/specs/INDEX.md`. - **Decisions:** Architecture decisions are recorded in `docs/decisions/`. Read `docs/decisions/INDEX.md` for an overview. When making significant architectural choices, create a new ADR via `/record decision`. -- **Plans:** Implementation plans are generated from specs via `/plan` and saved to `docs/specs/<slug>/plan.md`. Plans are gitignored (working files, not committed) — only specs and ADRs are tracked. +- **Plans:** Implementation plans are generated from specs via `/plan` and committed under `docs/plans/<slug>/plan.md`, with individual sibling task files named `docs/plans/<slug>/task-<NN>-<short-slug>.md`. Specs are the living requirements; plans and task files are implementation records for the current buildout. ### Plan Implementation - After implementing a plan, run `make fmt` first to format code, then run `make typecheck test lint` to verify the changes. Formatting must come first because formatters may split lines, which can trigger complexity linter warnings. diff --git a/docs/specs/INDEX.md b/docs/specs/INDEX.md index ce46abfd0f..8a8366005d 100644 --- a/docs/specs/INDEX.md +++ b/docs/specs/INDEX.md @@ -115,7 +115,7 @@ System pages (Radarr/Sonarr-style) for status, disk usage, database maintenance, ## Conventions - **Spec layout.** Umbrella specs live as flat `.md` files under the umbrella directory (`docs/specs/office/agents.md`). Standalone specs use a folder (`docs/specs/improve-kandev/spec.md`). -- **Plans are not specs.** Implementation plans (`plan.md`) are working files, gitignored. Specs are the durable requirements. +- **Plans are not specs.** Implementation plans are committed under `docs/plans/<feature>/` with individual sibling task files named `task-<NN>-<short-slug>.md`. Specs are the durable requirements; plans and task files are implementation records for the current buildout. - **Bug fixes are not specs.** Bugs produce a regression test plus an ADR if they encoded a new convention. See `/fix` skill. - **Architecture decisions are not specs.** ADRs live under `docs/decisions/`. See `/record decision`.