km-spec-driven-development 0.1.0 → 0.2.0

package/templates/features/plan.md

@@ -0,0 +1,71 @@
+<!-- km-spec-template: feature/plan@1.0 -->
+# Plan: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_ID}} |
+| **Linked Spec** | `spec.md` |
+| **Linked Context** | `context.md` |
+| **Status** | Draft |
+| **Tier** | {{TIER}} |
+| **Created** | {{CREATED_DATE}} |
+| **Template** | feature/plan@{{TEMPLATE_VERSION}} |
+
+<!--
+AGENT INSTRUCTIONS
+- plan.md is the implementation-planning artifact (absorbs former design.md duties).
+- Do not mark Status Ready for implementation until approach is grounded in context.md
+  and confirmed requirements in spec.md.
+- Record DEC-XXX for meaningful choices. Prefer [DECISION REQUIRED] over silent picks.
+-->
+
+## Technical Approach
+
+[NEEDS CLARIFICATION]: Describe the intended approach in 2–5 sentences after reading `spec.md` and `context.md`.
+
+## Affected Components
+
+| Component | Responsibility | Location (expected) | Confidence |
+|-----------|----------------|---------------------|------------|
+| [NEEDS CLARIFICATION] | | | [NEEDS CLARIFICATION] |
+
+## Data and Interface Considerations
+
+- **Data:** [NEEDS CLARIFICATION]: Schema, entities, or state changes (or N/A).
+- **Interfaces:** [NEEDS CLARIFICATION]: Public APIs, events, CLI, or UI contracts (or N/A).
+
+## Error Handling
+
+| Condition | Behavior | User / caller feedback |
+|-----------|----------|------------------------|
+| [NEEDS CLARIFICATION] | | |
+
+## Risks
+
+- [NEEDS CLARIFICATION]: Implementation risks not already captured in `context.md`.
+
+## Decisions
+
+| ID | Decision | Alternatives | Rationale | Confidence |
+|----|----------|--------------|-----------|------------|
+| — | [DECISION REQUIRED]: None yet. | | | |
+
+## Alternatives Considered
+
+- [NEEDS CLARIFICATION]: List alternatives only after real evaluation; leave empty with marker until then.
+
+## Open Design Questions
+
+- [ ] [NEEDS CLARIFICATION]: What is the smallest shippable technical slice?
+- [ ] [DECISION REQUIRED]: Where should new code live per CONVENTIONS project structure?
+
+{{COMPLEX_SECTIONS}}
+
+## Readiness Criteria
+
+This `plan.md` is **Ready for implementation tasks** when:
+
+- [ ] Technical approach is written and consistent with confirmed requirements.
+- [ ] Affected components map to real or intentionally new paths justified by CONVENTIONS.
+- [ ] Open design questions that block coding are resolved or tracked as blockers.
+- [ ] For **complex** tier: component boundaries, data model, contracts, security, performance, rollout, observability, and rollback sections are filled or explicitly N/A with rationale.

package/templates/features/spec.md

@@ -0,0 +1,88 @@
+<!-- km-spec-template: feature/spec@1.0 -->
+# Feature: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_ID}} |
+| **Status** | Draft |
+| **Tier** | {{TIER}} |
+| **Created** | {{CREATED_DATE}} |
+| **Template** | feature/spec@{{TEMPLATE_VERSION}} |
+
+<!--
+AGENT INSTRUCTIONS
+- Do not invent product requirements, APIs, files, or behaviors.
+- Values marked [INFERRED] are NOT requirements. Do not promote them to
+  [CONFIRMED] without evidence from the user, an approved brief, or code.
+- Fill [NEEDS CLARIFICATION] before treating an item as implementable truth.
+- Prefer fewer confirmed requirements over fabricated completeness.
+-->
+
+## Overview
+
+{{OVERVIEW_BLOCK}}
+
+## Confirmed Information
+
+Only facts that are explicitly known. Do not invent product claims here.
+
+{{CONFIRMED_BLOCK}}
+
+## Inferred Suggestions
+
+**Not requirements.** Do not implement against this section until items are
+promoted to Confirmed Information or Requirements with evidence or approval.
+
+{{INFERRED_BLOCK}}
+
+## Requirements
+
+| ID | Description | Priority | Confidence |
+|----|-------------|----------|------------|
+| REQ-001 | [NEEDS CLARIFICATION]: Write a specific, testable requirement. | Must Have | [NEEDS CLARIFICATION] |
+| REQ-002 | [NEEDS CLARIFICATION]: Optional second requirement. Remove if unused. | Should Have | [NEEDS CLARIFICATION] |
+
+<!-- Example format (delete when writing real REQs):
+| REQ-001 | User can reset password via email link within 15 minutes | Must Have | [CONFIRMED] |
+-->
+
+## Acceptance Criteria
+
+Link each criterion to a requirement ID. Criteria must be observable and falsifiable.
+
+- [ ] AC-001 (REQ-001): [NEEDS CLARIFICATION]: Specific check that proves REQ-001.
+- [ ] AC-002 (REQ-002): [NEEDS CLARIFICATION]: Specific check that proves REQ-002.
+
+## Constraints
+
+- [NEEDS CLARIFICATION]: Project non-negotiables that apply (see `.specs/project/PROJECT.md`).
+- [NEEDS CLARIFICATION]: Feature-specific technical, security, or UX constraints.
+
+## Out of Scope
+
+Explicit exclusions prevent scope creep.
+
+- [NEEDS CLARIFICATION]: List what this feature will **not** do.
+- <!-- Example: Push notifications, mobile apps, admin SSO -->
+
+## Open Questions
+
+- [ ] [NEEDS CLARIFICATION]: What is the primary user journey for this feature?
+- [ ] [DECISION REQUIRED]: Which existing modules or services own this behavior?
+- [ ] [NEEDS CLARIFICATION]: What is the definition of done for the first shippable slice?
+
+## Change Log
+
+| Date | Change | Author |
+|------|--------|--------|
+| {{CREATED_DATE}} | Initial scaffold (km-spec {{TEMPLATE_VERSION}}) | km-spec |
+
+## Document Completion Criteria
+
+This `spec.md` is **Ready for plan** when:
+
+- [ ] Overview is filled and marked with an appropriate confidence marker.
+- [ ] Every Must Have requirement is specific and marked `[CONFIRMED]` (or explicitly accepted as a working assumption with owner note).
+- [ ] Every Must Have requirement has at least one acceptance criterion.
+- [ ] Out of scope lists concrete exclusions.
+- [ ] Open questions that block implementation are resolved or tracked as blockers in `STATE.md`.

package/templates/features/tasks.md

@@ -0,0 +1,290 @@
+<!-- km-spec-template: feature/tasks@1.0 -->
+# Tasks: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_ID}} |
+| **Linked Spec** | `spec.md` |
+| **Linked Context** | `context.md` |
+| **Linked Plan** | `plan.md` |
+| **Linked Validation** | `validation.md` |
+| **Tier** | {{TIER}} |
+| **Created** | {{CREATED_DATE}} |
+| **Template** | feature/tasks@{{TEMPLATE_VERSION}} |
+
+## Status Summary
+
+| Status | Count |
+|--------|-------|
+| TODO | 4 |
+| IN PROGRESS | 0 |
+| DONE | 0 |
+| BLOCKED | 0 |
+
+## Task States
+
+| State | Meaning |
+|-------|---------|
+| `TODO` | Not started |
+| `IN PROGRESS` | Actively being worked (prefer one per agent/session) |
+| `DONE` | Completion criteria met **and** required validation evidence recorded |
+| `BLOCKED` | Cannot proceed; reason recorded in Notes and `STATE.md` |
+
+Rules:
+
+- Do **not** mark `DONE` if required validation failed or was not run.
+- Do **not** invent implementation tasks before requirements and codebase context are analyzed.
+- Mark parallelizable tasks with `[P]` only when file sets are disjoint.
+
+---
+
+## TASK-001 — Confirm requirements in spec.md
+
+**Objective:** Fill `spec.md` so Must Have requirements and acceptance criteria are explicit and confidence-marked.
+
+**Status:** TODO
+
+**Satisfies:** N/A (enables all REQs)
+
+**Required context:**
+
+- `.specs/project/STATE.md`
+- `.specs/project/PROJECT.md`
+- `spec.md`
+- Product brief or user description if available
+
+**Expected files:**
+
+- `.specs/features/{{FEATURE_SLUG}}/spec.md`
+
+**Constraints:**
+
+- Do not invent product requirements.
+- Do not promote `[INFERRED]` to `[CONFIRMED]` without evidence or explicit approval.
+
+**Dependencies:** None
+
+**Steps:**
+
+1. Read project goals and constraints.
+2. Write Overview with an appropriate confidence marker.
+3. Add only requirements that are confirmed or explicitly accepted working assumptions.
+4. Link acceptance criteria to each Must Have requirement.
+5. Record open questions and out-of-scope items.
+
+**Completion criteria:**
+
+- [ ] `spec.md` document completion criteria are satisfied or remaining gaps are listed as blockers.
+
+**Validation commands:**
+
+- N/A (documentation task). Review `spec.md` against the completion checklist.
+
+**Required evidence:**
+
+- Spec status moved toward Ready for plan; open blockers in `STATE.md` if any.
+
+**Deviations:**
+
+-
+
+---
+
+## TASK-002 — Build context from the codebase
+
+**Objective:** Populate `context.md` from real repository inspection.
+
+**Status:** TODO
+
+**Satisfies:** N/A (enables safe implementation)
+
+**Required context:**
+
+- `spec.md`
+- `.specs/codebase/CONVENTIONS.md`
+- Repository source tree and relevant modules
+
+**Expected files:**
+
+- `.specs/features/{{FEATURE_SLUG}}/context.md`
+
+**Constraints:**
+
+- Do not invent file paths or APIs.
+- Mark unknowns `[NEEDS CLARIFICATION]`.
+
+**Dependencies:** TASK-001 recommended first (or proceed if requirements are already confirmed).
+
+**Steps:**
+
+1. Inspect entry points and modules related to the feature domain.
+2. Record real related paths, patterns, and risks.
+3. List likely impacted files with reasons.
+
+**Completion criteria:**
+
+- [ ] `context.md` completion criteria are met.
+
+**Validation commands:**
+
+- N/A (documentation). Spot-check that listed paths exist.
+
+**Required evidence:**
+
+- Paths in `context.md` verified present (or explicitly planned as new files).
+
+**Deviations:**
+
+-
+
+---
+
+## TASK-003 — Draft implementation plan
+
+**Objective:** Fill `plan.md` with a grounded technical approach (depth matches tier **{{TIER}}**).
+
+**Status:** TODO
+
+**Satisfies:** N/A (shapes implementation tasks)
+
+**Required context:**
+
+- `spec.md`, `context.md`, `CONVENTIONS.md`
+
+**Expected files:**
+
+- `.specs/features/{{FEATURE_SLUG}}/plan.md`
+
+**Constraints:**
+
+- Align with confirmed requirements only.
+- For **complex** tier, complete the complex planning sections or mark N/A with rationale.
+
+**Dependencies:** TASK-001, TASK-002
+
+**Steps:**
+
+1. Write technical approach and affected components.
+2. Capture decisions as DEC-XXX when choosing among options.
+3. Resolve or track open design questions.
+
+**Completion criteria:**
+
+- [ ] `plan.md` readiness criteria are met for tier **{{TIER}}**.
+
+**Validation commands:**
+
+- N/A (documentation / design review).
+
+**Required evidence:**
+
+- Plan status Ready for implementation tasks (or blocker recorded).
+
+**Deviations:**
+
+-
+
+---
+
+## TASK-004 — Decompose implementation tasks
+
+**Objective:** Append atomic implementation tasks (TASK-010+) after analysis. Do not invent them before TASK-001–003 are adequately done.
+
+**Status:** TODO
+
+**Satisfies:** All confirmed REQs via future tasks
+
+**Required context:**
+
+- `spec.md`, `context.md`, `plan.md`
+
+**Expected files:**
+
+- `.specs/features/{{FEATURE_SLUG}}/tasks.md` (this file)
+
+**Constraints:**
+
+- Each implementation task must reference REQ-IDs, expected files, completion criteria, and validation.
+- Prefer small, reviewable tasks.
+- Use `[P]` only for disjoint file sets.
+
+**Dependencies:** TASK-003
+
+**Steps:**
+
+1. Break the plan into atomic tasks using the template below.
+2. Set dependencies and parallelization markers.
+3. Update the status summary counts.
+
+**Completion criteria:**
+
+- [ ] Implementation tasks cover all Must Have requirements.
+- [ ] No task lacks linked REQs, expected files, or validation expectations.
+
+**Validation commands:**
+
+- N/A (planning). Review traceability REQ → TASK.
+
+**Required evidence:**
+
+- Task graph ready for execution; first implementation task identified in `STATE.md`.
+
+**Deviations:**
+
+-
+
+---
+
+## Implementation Task Template
+
+Copy and renumber starting at **TASK-010** (or next free id). Delete this section’s placeholder row only when real tasks exist—or leave the template for future tasks.
+
+### TASK-XXX — [Title] [P?]
+
+**Objective:** [One sentence]
+
+**Status:** TODO
+
+**Satisfies:** REQ-XXX
+
+**Required context:**
+
+- `spec.md` (relevant REQs/ACs)
+- `context.md` / `plan.md` sections
+- Concrete source files to read
+
+**Expected files:**
+
+- `path/to/file` — create | modify
+
+**Constraints:**
+
+- [Project or task-specific constraints]
+
+**Dependencies:** None | TASK-XXX
+
+**Steps:**
+
+1. …
+2. …
+
+**Completion criteria:**
+
+- [ ] …
+
+**Validation commands:**
+
+- Use commands from `.specs/codebase/CONVENTIONS.md` → Testing (build, lint, typecheck, tests as applicable).
+- [ ] Build
+- [ ] Lint
+- [ ] Typecheck
+- [ ] Tests
+- [ ] Acceptance criteria for linked REQs
+
+**Required evidence:**
+
+- Results recorded in this task’s notes and/or `validation.md`.
+
+**Deviations:**
+
+-

package/templates/features/validation.md

@@ -0,0 +1,52 @@
+<!-- km-spec-template: feature/validation@1.0 -->
+# Validation: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_ID}} |
+| **Status** | Pending |
+| **Created** | {{CREATED_DATE}} |
+| **Template** | feature/validation@{{TEMPLATE_VERSION}} |
+
+This file is an **evidence ledger** only. Record what was run and the outcome.
+Do not treat unchecked boxes as passed. Do not invent gate results.
+
+## Validation Summary
+
+| Field | Value |
+|-------|-------|
+| Overall status | Pending |
+| Last updated | |
+| Related tasks | |
+
+## Evidence Ledger
+
+| Gate | Result | Command / notes | Task | Date |
+|------|--------|-----------------|------|------|
+| Build | Pending | | | |
+| Lint | Pending | | | |
+| Static analysis / typecheck | Pending | | | |
+| Tests | Pending | | | |
+| Acceptance criteria | Pending | Map to AC-XXX / REQ-XXX | | |
+| Review | Pending | Human or peer review | | |
+| Security | Pending / N/A | Required for auth, data access, or external integrations | | |
+
+## Acceptance Criteria Trace
+
+| Criterion | Result | Evidence |
+|-----------|--------|----------|
+| AC-001 | Pending | |
+| AC-002 | Pending | |
+
+## Issues Found
+
+None yet.
+
+## Final Result
+
+Pending.
+
+## Notes
+
+- Prefer commands documented in `.specs/codebase/CONVENTIONS.md` → Testing.
+- A task is not `DONE` until applicable gates above have real evidence.

package/templates/quick/SUMMARY.md

@@ -0,0 +1,53 @@
+<!-- km-spec-template: quick/SUMMARY@1.0 -->
+# Summary: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Linked Task** | `TASK.md` |
+| **Final status** | Pending |
+| **Completed** | |
+| **Template** | quick/SUMMARY@{{TEMPLATE_VERSION}} |
+
+Fill this file **after** implementation. Do not invent results.
+
+## Final Status
+
+Pending | DONE | BLOCKED | Cancelled (promoted to feature)
+
+## Files Changed
+
+- `path/to/file` — [what changed]
+
+## Implementation Summary
+
+[NEEDS CLARIFICATION until done]: What changed and why (2–5 sentences).
+
+## Commands Executed
+
+```text
+# example
+# npm test
+```
+
+## Validation Evidence
+
+| Gate | Result | Notes |
+|------|--------|-------|
+| Build | Pending | |
+| Lint | Pending | |
+| Typecheck | Pending | |
+| Tests | Pending | |
+| Manual | Pending | |
+| Acceptance criteria | Pending | |
+
+## Deviations
+
+- None yet.
+
+## Remaining Risks
+
+- None yet. / [describe]
+
+## Follow-up Work
+
+- [ ] None / [ ] Create feature or follow-up quick task: …

package/templates/quick/TASK.md

@@ -0,0 +1,71 @@
+<!-- km-spec-template: quick/TASK@1.0 -->
+# Quick Task: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Status** | TODO |
+| **Created** | {{CREATED_DATE}} |
+| **Template** | quick/TASK@{{TEMPLATE_VERSION}} |
+| **Slug** | {{FEATURE_SLUG}} |
+
+<!--
+AGENT INSTRUCTIONS
+- Quick tasks are for low-ambiguity work (typically ≤3 files).
+- Do not invent file paths. Inspect the repository first.
+- If scope grows beyond the promotion criteria, stop and create a feature instead.
+-->
+
+## Objective
+
+{{QUICK_OBJECTIVE}}
+
+## Description
+
+{{QUICK_DESCRIPTION}}
+
+## Scope
+
+Keep the change set small and reviewable.
+
+### Expected files
+
+- [NEEDS CLARIFICATION]: `path/to/file` — create | modify
+
+List files only after inspection. Prefer ≤3 files for quick mode.
+
+### Constraints
+
+- Follow `.specs/codebase/CONVENTIONS.md`.
+- Do not refactor unrelated code.
+- Do not invent APIs or files.
+
+## Acceptance Criteria
+
+- [ ] [NEEDS CLARIFICATION]: Observable outcome that proves the fix or change works.
+- [ ] No unrelated behavior change.
+
+## Validation
+
+Use project commands from `.specs/codebase/CONVENTIONS.md` → Testing when available.
+
+- [ ] Build passes (if applicable)
+- [ ] Lint passes (if available)
+- [ ] Typecheck passes (if available)
+- [ ] Relevant tests pass (if available)
+- [ ] Manual check completed (if needed)
+
+## Out of Scope
+
+- [NEEDS CLARIFICATION]: Explicit exclusions for this quick change.
+- New product features that need REQs, plan, or multi-module design.
+
+## Promotion Criteria
+
+**Promote to a feature** (`km-spec feature "..."`) when any of the following is true:
+
+- More than 3 files are likely affected.
+- Requirements are ambiguous or need stakeholder decisions.
+- New public APIs, data models, or security-sensitive flows are introduced.
+- Implementation planning needs more than a short inline step list (>5 steps or complex dependencies).
+
+If promoting, leave this TASK with status BLOCKED or cancelled note and link the new feature path in `SUMMARY.md` / `STATE.md`.