km-spec-driven-development 0.1.0 → 0.2.0

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "km-spec-driven-development",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A lightweight Spec Driven Development CLI for AI-assisted software projects",
   "bin": {
     "km-spec": "bin/km-spec"
   },
+  "scripts": {
+    "test": "bash tests/run.sh"
+  },
   "files": [
     "bin",
     "templates",

package/templates/AGENTS.md

@@ -1,42 +1,77 @@
 # Agent Instructions
 
-This project uses Spec Driven Development.
+This project uses Spec Driven Development (SDD).
 
-## Always Read First
+- Full methodology: `SDD.md`
+- Execution lifecycle: `HARNESS.md` (read every session)
 
-Before changing code, always read:
+## Mandatory Reading Order
+
+Before changing code, always read in this order:
 
 1. `.specs/project/STATE.md`
 2. `.specs/project/PROJECT.md`
 3. `.specs/codebase/CONVENTIONS.md`
+4. `HARNESS.md`
+5. Current feature or quick-task files (only the active work item)
+
+### Feature work
+
+Also read:
+
+- `.specs/features/<feature>/spec.md`
+- `.specs/features/<feature>/context.md`
+- `.specs/features/<feature>/plan.md`
+- `.specs/features/<feature>/tasks.md`
+- `.specs/features/<feature>/validation.md`
+
+Legacy features may lack `context.md` or `plan.md`. If missing, create them from current templates before large implementation work, or treat gaps as `[NEEDS CLARIFICATION]`.
+
+### Quick-task work
 
-For feature work, also read:
+Also read:
 
-- `.specs/features/[feature]/spec.md`
-- `.specs/features/[feature]/tasks.md`
-- `.specs/features/[feature]/validation.md`
+- `.specs/quick/<task>/TASK.md`
+- `.specs/quick/<task>/SUMMARY.md` (when closing out)
 
-## Rules
+Legacy single-file quick tasks may live at `.specs/quick/<task>.md`. Prefer the directory layout for new work.
 
-- Do not invent files, APIs, functions, or behavior.
-- Read existing code before modifying it.
-- Implement only the current task scope.
-- Keep changes small and reviewable.
-- Do not refactor unrelated code.
-- Follow `.specs/codebase/CONVENTIONS.md`.
-- Update task status after implementation.
-- Run validation before marking work as done.
-- Record validation evidence.
-- Update `.specs/project/STATE.md` at the end of the session.
+## Permanent Rules
+
+1. **Never invent** requirements, APIs, files, functions, or project conventions.
+2. **Never treat `[INFERRED]` as `[CONFIRMED]`** without evidence or explicit approval.
+3. **Read existing code** before modifying it. Prefer repository truth over chat memory.
+4. **One task at a time.** Prefer a single `IN PROGRESS` task per agent/session.
+5. **Implement only the current task scope.** No unrelated refactors or drive-by cleanups.
+6. **Follow** `.specs/codebase/CONVENTIONS.md` for structure, style, and validation commands.
+7. **Record evidence** in `validation.md` (features) or `SUMMARY.md` (quick tasks) before marking work complete.
+8. **Do not mark DONE** if required validation failed or was not executed.
+9. **Stop and record a blocker** in `STATE.md` when required information is missing.
+10. **If PROJECT.md or CONVENTIONS.md are still placeholders**, inspect the real repository (and ask the user) before assuming stack, commands, or layout.
+11. **Update** `.specs/project/STATE.md` at the end of every session where work occurred.
+12. **Update task status** as you go (`TODO` → `IN PROGRESS` → `DONE` | `BLOCKED`).
+
+## Confidence Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[CONFIRMED]` | Explicitly known; safe to implement against |
+| `[INFERRED]` | Suggestion only; not a requirement |
+| `[NEEDS CLARIFICATION]` | Unresolved; do not invent an answer silently |
+| `[DECISION REQUIRED]` | Needs an explicit decision (record DEC-XXX) |
 
 ## Done Means
 
-A task is only complete when:
+A task is complete only when:
+
+- Scope matches the task and linked requirements/acceptance criteria
+- Applicable build, lint, typecheck, and tests have been run (or honestly marked N/A with reason)
+- Acceptance criteria are verified
+- Validation evidence is recorded
+- Task status and `STATE.md` are updated
+
+## Out of Scope for Agents
 
-- Build passes.
-- Lint passes, if available.
-- Typecheck passes, if available.
-- Tests pass, if available.
-- Acceptance criteria are verified.
-- Validation result is recorded.
-- Project state is updated.
+- Do not expand ceremony beyond the work tier without cause
+- Do not load every feature spec at once
+- Do not skip `HARNESS.md` lifecycle steps for “small” code changes that still need validation

package/templates/HARNESS.md

@@ -0,0 +1,135 @@
+# AI Development Harness
+
+Operational lifecycle for agents working in this repository.
+Methodology detail lives in `SDD.md`. Permanent rules live in `AGENTS.md`.
+
+**Template:** harness@1.0
+
+---
+
+## Task States
+
+| State | Meaning |
+|-------|---------|
+| `TODO` | Not started |
+| `IN PROGRESS` | Active work (prefer one task per agent/session) |
+| `DONE` | Completion criteria met **and** required validation evidence recorded |
+| `BLOCKED` | Cannot proceed; reason recorded |
+
+A task must **not** be marked `DONE` if required validation failed or was not executed.
+
+---
+
+## Lifecycle
+
+```text
+Discover → Read → Plan → Implement → Validate → Review → Report
+```
+
+### 1. Discover
+
+| | |
+|--|--|
+| **Inputs** | User request; `.specs/project/STATE.md`; roadmap only if planning |
+| **Responsibilities** | Identify current feature or quick task and the next `TODO` / assigned task id |
+| **Outputs** | Target path (feature slug or quick slug) and task id |
+| **Stop** | No clear task → update STATE with question; do not invent scope |
+
+### 2. Read
+
+| | |
+|--|--|
+| **Inputs** | `STATE.md`, `PROJECT.md`, `CONVENTIONS.md`, this file, current work files |
+| **Feature files** | `spec.md`, `context.md`, `plan.md`, `tasks.md`, `validation.md` |
+| **Quick files** | `TASK.md` (and `SUMMARY.md` when closing) |
+| **Responsibilities** | Re-read real source files before changing them; treat `[INFERRED]` as non-binding |
+| **Outputs** | Verified understanding of scope and constraints |
+| **Stop** | Missing critical info → ask or set `BLOCKED`; do not invent REQs/APIs/paths |
+
+### 3. Plan
+
+| | |
+|--|--|
+| **Inputs** | Current task entry; linked REQs; plan/context |
+| **Responsibilities** | List atomic steps (file + action). If >5 steps or complex deps → add/update tasks first |
+| **Outputs** | Step list or updated `tasks.md` |
+| **Stop** | Spec/plan not ready for implementation work → finish planning tasks first |
+
+### 4. Implement
+
+| | |
+|--|--|
+| **Inputs** | Task scope; CONVENTIONS; existing code patterns |
+| **Responsibilities** | Change only task scope; no unrelated refactors; follow project structure rules |
+| **Outputs** | Code/docs diffs limited to expected files |
+| **Stop** | Reality contradicts plan/spec → record deviation; do not silent-workaround |
+
+### 5. Validate
+
+| | |
+|--|--|
+| **Inputs** | Commands from `CONVENTIONS.md` → Testing; task validation section |
+| **Responsibilities** | Run applicable gates; record real results |
+| **Outputs** | Evidence in task notes and feature `validation.md` or quick `SUMMARY.md` |
+| **Stop** | Gate failure → fix or `BLOCKED`; never mark DONE |
+
+### 6. Review
+
+| | |
+|--|--|
+| **Inputs** | Diff; acceptance criteria; confidence markers |
+| **Responsibilities** | Confirm AC met; no scope creep; markers still honest |
+| **Outputs** | Pass/fail judgment; deviation notes |
+| **Stop** | AC unmet → continue implement/validate loop |
+
+### 7. Report
+
+| | |
+|--|--|
+| **Inputs** | Outcomes of this session |
+| **Responsibilities** | Update task status, validation ledger, `STATE.md` |
+| **Outputs** | Handoff report (below); clear next task |
+| **Stop** | Never end a session without STATE update when work occurred |
+
+---
+
+## Handoff Report Format
+
+```markdown
+## Handoff Report
+
+**Task:** TASK-XXX | quick: <slug>
+**Status:** DONE | PARTIAL | BLOCKED
+
+### Files Changed
+- `path` — summary
+
+### Commands Executed
+- `command` → result
+
+### Results
+- Build/Lint/Typecheck/Tests/AC: PASS | FAIL | SKIPPED (reason)
+
+### Decisions
+- DEC-XXX: …
+
+### Deviations
+- …
+
+### Blockers
+- …
+
+### Next Recommended Task
+- TASK-XXX — …
+```
+
+---
+
+## Confidence Markers
+
+| Marker | Treat as |
+|--------|----------|
+| `[CONFIRMED]` | Safe to implement against |
+| `[INFERRED]` | Non-binding until promoted |
+| `[NEEDS CLARIFICATION]` | Resolve before relying on it |
+| `[DECISION REQUIRED]` | Needs explicit choice (DEC-XXX) |

package/templates/SDD.md

@@ -75,8 +75,9 @@ The default structure keeps a clear separation between project context and codeb
 │   └── [feature-name]/
 │       ├── spec.md             # Requirements, scope, acceptance criteria
 │       ├── context.md          # Background, prior decisions, related code
-│       ├── design.md           # Optional technical design for medium/large/complex features
-│       └── tasks.md            # Atomic tasks with traceability
+│       ├── plan.md             # Implementation plan (absorbs former design.md role)
+│       ├── tasks.md            # Atomic tasks with traceability
+│       └── validation.md       # Validation evidence ledger
 │
 └── quick/
     └── [quick-task-name]/
@@ -84,6 +85,17 @@ The default structure keeps a clear separation between project context and codeb
         └── SUMMARY.md          # What was done, files changed, outcome
 ```
 
+Root agent files (created by `km-spec init`):
+
+```
+AGENTS.md                       # Permanent agent rules and mandatory reading order
+HARNESS.md                      # Execution lifecycle for agents
+SDD.md                          # Full methodology reference
+```
+
+**CLI tiers (v0.2+):** `km-spec feature` supports `--tier standard` (default) and `--tier complex`. Complex features include additional planning sections in `plan.md`. Quick work uses `km-spec quick` (directory layout above).
+
+**Legacy (pre-0.2):** Features may only have `spec.md`, `tasks.md`, and `validation.md`. Quick tasks may be a single `.specs/quick/<name>.md` file. `km-spec doctor` warns on legacy layouts and does not fail solely for missing `context.md` / `plan.md`.
 ### Default vs Optional Codebase Documentation
 
 By default, the codebase has only one required technical document:
@@ -292,35 +304,34 @@ These files are optional expansions. They are not generated by default and shoul
 
 ---
 
-### 3.7 `features/[name]/design.md`
+### 3.7 `features/[name]/plan.md`
 
-**Purpose:** Technical design for the feature. Translates requirements into an implementable structure.
+**Purpose:** Implementation plan for the feature. Translates requirements into an implementable structure. **This is the canonical planning artifact** (it replaces / absorbs the former `design.md` responsibility).
 
-**Created:** After spec.md, before tasks.md, for medium/large/complex features.
+**Created:** When the feature is scaffolded (`km-spec feature`). Filled after `spec.md` and `context.md` are sufficiently clear.
 
-**Skipped for:** Quick tasks and simple features where the implementation path is obvious.
+**Depth:** Scales with tier — `standard` (default) vs `complex` (extra sections: component boundaries, data model, API contracts, security, performance, rollout, observability, rollback).
 
-**Updated:** When design decisions change during implementation (with DEC-XXX entries).
+**Skipped for:** Quick tasks.
 
-**Contains:**
-- Component and module breakdown
-- Data models and schema changes
-- API contracts (endpoints, request/response shapes)
-- State management design
-- Error states and edge case handling
-- Performance considerations
-- Security considerations
-- Diagrams as needed
+**Updated:** When plan decisions change during implementation (with DEC-XXX entries).
 
+**Contains:**
+- Technical approach
+- Affected components
+- Data and interface considerations
+- Error handling
+- Risks, decisions, alternatives, open design questions
+- For complex tier: component boundaries, data model, API/interface contracts, security, performance, migration/rollout, observability, rollback
 ---
 
 ### 3.8 `features/[name]/tasks.md`
 
-**Purpose:** The execution plan. Breaks design into atomic, verifiable, and potentially parallelizable tasks.
+**Purpose:** The execution plan. Breaks the implementation plan into atomic, verifiable, and potentially parallelizable tasks.
 
-**Created:** After design.md, for medium/large/complex features.
+**Created:** When the feature is scaffolded. Initial tasks are planning/decomposition tasks; implementation tasks are added after analysis (do not invent product implementation tasks before requirements and context are known).
 
-**Skipped for:** Quick tasks. For medium features, tasks may be inlined in spec.md.
+**Skipped for:** Quick tasks.
 
 **Updated:** As tasks are completed (status updated), or when new tasks are discovered during execution.
 
@@ -328,8 +339,17 @@ These files are optional expansions. They are not generated by default and shoul
 - Full task list with TASK-XXX IDs
 - Dependencies between tasks
 - Parallelization markers (`[P]`)
-- Per-task: objective, files, steps, acceptance criteria, tests, validation gate, status
+- Per-task: objective, required context, expected files, constraints, steps, completion criteria, validation, evidence, status
+
+### 3.8b `features/[name]/validation.md`
+
+**Purpose:** Evidence ledger for gates (build, lint, typecheck/static analysis, tests, acceptance criteria, review, security when applicable).
+
+**Created:** When the feature is scaffolded.
 
+**Updated:** When validation is run. Do not invent pass/fail results.
+
+**Note:** This file records evidence only. The CLI does not run project gates.
 ---
 
 ### 3.9 `quick/[name]/TASK.md`
@@ -395,54 +415,37 @@ These files are optional expansions. They are not generated by default and shoul
 
 ---
 
-#### Medium Feature
-**Profile:** Clear functionality with defined inputs/outputs. Low ambiguity. Fewer than 3 existing dependencies impacted.
+#### Medium / Standard Feature
+**Profile:** Clear functionality with defined inputs/outputs. Low ambiguity. CLI: `km-spec feature "Name"` (default `--tier standard`).
 
 **Workflow:**
-1. Create `features/[name]/spec.md` with requirements and acceptance criteria
-2. Create `features/[name]/context.md` with relevant background
-3. Design inline inside spec.md or in brief `design.md` if needed
-4. Tasks inline in spec.md or a short `tasks.md`
-5. Execute with harness protocol
-6. Run all validation gates
-7. Update `STATE.md`
+1. Scaffold with `km-spec feature "Name"` (creates `spec.md`, `context.md`, `plan.md`, `tasks.md`, `validation.md`)
+2. Fill `spec.md` with requirements and acceptance criteria (confidence markers)
+3. Fill `context.md` from real repository inspection
+4. Fill `plan.md` with technical approach (keep light if path is obvious)
+5. Decompose implementation tasks in `tasks.md`
+6. Execute with harness protocol (`HARNESS.md`)
+7. Record gates in `validation.md`
+8. Update `STATE.md`
 
-**Ceremony level:** Low-to-medium. Skip `design.md` if implementation path is clear.
+**Ceremony level:** Low-to-medium.
 
 ---
 
-#### Large Feature
-**Profile:** Multiple components. Touches existing architecture. Clear requirements but broad scope.
+#### Large / Complex Feature
+**Profile:** Multiple components, new domain, integrations, or high uncertainty. CLI: `km-spec feature "Name" --tier complex`.
 
 **Workflow:**
-1. Create `spec.md`, `context.md`
-2. Create `design.md` with full component breakdown, API contracts, data model
-3. Create `tasks.md` with TASK-XXX IDs, dependencies, parallelization markers
-4. Execute task by task, updating status in `tasks.md` as each completes
-5. Run validation gates per task and full suite at end
-6. Update `STATE.md`
-
-**Ceremony level:** Full. Do not skip `design.md` or `tasks.md`.
-
----
-
-#### Complex Feature
-**Profile:** New domain, high uncertainty, external integrations, technical risks, or research required.
-
-**Workflow:**
-1. **Exploration phase:** Research before specifying. Use sub-agents for spikes.
-2. Create `spec.md` after exploration — not before
-3. Create `context.md` with extensive background and risk notes
-4. Create `design.md` with alternatives considered and DEC-XXX decisions recorded
-5. Create `tasks.md` with RISK-XXX markers on high-uncertainty tasks
-6. Review design before execution (checkpoint)
-7. Execute in phases — stop and respec if reality diverges significantly
-8. Run validation gates including security review
-9. UAT if applicable
-10. Update `STATE.md` with all decisions, learnings, and deferred items
-
-**Ceremony level:** Maximum. Expect to iterate on `design.md` during implementation.
+1. Scaffold with `--tier complex` (adds expanded `plan.md` sections)
+2. Explore / spike before promoting requirements to `[CONFIRMED]`
+3. Fill `spec.md`, `context.md`, then complete complex `plan.md` sections
+4. Review plan before implementation tasks
+5. Decompose `tasks.md` with dependencies and RISK markers as needed
+6. Execute in phases — stop and replan if reality diverges
+7. Validate (including security when applicable); record evidence
+8. Update `STATE.md`
 
+**Ceremony level:** Full. Do not skip `plan.md` depth for complex tier.
 ---
 
 ### Safety Valve Rule
@@ -489,7 +492,8 @@ Load only when working on the relevant feature or area:
 |------|-----------|
 | `features/[name]/spec.md` | Working on this feature |
 | `features/[name]/context.md` | Need background on this feature |
-| `features/[name]/design.md` | Need architecture decisions for this feature |
+| `features/[name]/plan.md` | Need implementation plan / architecture decisions for this feature |
+| `features/[name]/validation.md` | Recording or reviewing gate evidence |
 | `features/[name]/tasks.md` | Checking task status or picking next task |
 | `codebase/CONVENTIONS.md` → Technical Context | Adding dependencies or checking compatibility |
 | `codebase/CONVENTIONS.md` → Architecture | Making structural or cross-module changes |
@@ -641,7 +645,7 @@ If implementation reveals that the spec is wrong, incomplete, or contradicts an
 2. Record the deviation in `STATE.md` under "Deviations".
 3. If the deviation is minor and resolution is obvious → resolve and document.
 4. If the deviation requires a decision → document the options and ask.
-5. Update `spec.md` or `design.md` to reflect any approved changes before continuing.
+5. Update `spec.md` or `plan.md` to reflect any approved changes before continuing.
 
 ---
 
@@ -669,7 +673,7 @@ A sub-agent receives a self-contained briefing. It must never rely on chat histo
 **Required input:**
 ```
 1. Task description (exact scope, no ambiguity)
-2. Relevant spec files (spec.md, context.md, or design.md for the area)
+2. Relevant spec files (spec.md, context.md, or plan.md for the area)
 3. Relevant codebase docs (CONVENTIONS.md always; others on demand)
 4. Specific files to read or modify
 5. Acceptance criteria
@@ -755,7 +759,7 @@ Project Goal
     └── REQ-XXX (requirement in spec.md)
             └── TASK-XXX (task in tasks.md)
                     ├── TEST-XXX (test file or validation evidence)
-                    ├── DEC-XXX (decision in design.md or STATE.md)
+                    ├── DEC-XXX (decision in plan.md or STATE.md)
                     └── Commit (references TASK-XXX in message)
 ```
 
@@ -826,15 +830,19 @@ Every task must reference the requirements it satisfies. Every test must referen
 
 ---
 
-### 10.2 `design.md` Template
+### 10.2 `plan.md` Template
+
+> Canonical name is **`plan.md`** (formerly referred to as `design.md` in earlier SDD drafts).
+> The CLI scaffolds a guided `plan.md` via templates; the outline below is the conceptual structure.
 
 ```markdown
-# [Feature Name] — Technical Design
+# [Feature Name] — Implementation Plan
 
 **Feature ID:** FEAT-XXX
 **Linked Spec:** spec.md
+**Linked Context:** context.md
 **Created:** YYYY-MM-DD
-**Status:** Draft | Approved | Superseded
+**Status:** Draft | Ready for implementation | Superseded
 
 ## Overview
 
@@ -927,7 +935,7 @@ created_at   | datetime| required    |
 
 **Feature ID:** FEAT-XXX
 **Linked Spec:** spec.md
-**Linked Design:** design.md
+**Linked Plan:** plan.md
 **Created:** YYYY-MM-DD
 
 ## Status Summary
@@ -1447,7 +1455,7 @@ Tokens expire after 7 days and rotate on each use.
 ```
 
 ```
-spec(user-profile): add design.md with API contract [TASK-003]
+spec(user-profile): add plan.md with API contract [TASK-003]
 ```
 
 ```
@@ -1574,7 +1582,7 @@ support tickets. This feature closes the most common support request.
 
 #### Step 3: Design (brief, medium feature)
 
-**File:** `.specs/features/email-notifications/design.md`
+**File:** `.specs/features/email-notifications/plan.md`
 
 ```markdown
 # Email Notifications — Design
@@ -1732,19 +1740,19 @@ The `.specs/` structure is tool-independent. It works as a plain text contract t
 
 **Usage pattern:**
 1. Start each session: `Read .specs/project/STATE.md`
-2. Load feature context: `Read .specs/features/[name]/spec.md` and `context.md`
-3. Use `CLAUDE.md` to point to the harness: add a line pointing to this `SDD.md`
+2. Load feature context: `Read` feature `spec.md`, `context.md`, `plan.md`, `tasks.md`
+3. Use `CLAUDE.md` / project `AGENTS.md` to point at `HARNESS.md`
 4. Use Claude Code's task system to track TASK-XXX progress
-5. Use `Bash` tool to run validation gates and capture evidence
+5. Use `Bash` tool to run validation gates and capture evidence in `validation.md`
 6. End each session: update `STATE.md` before closing
 
 **CLAUDE.md suggestion:**
 ```markdown
 # Development Guide
-This project uses Spec Driven Development. See `SDD.md` for the full methodology.
+This project uses Spec Driven Development. See `AGENTS.md` and `HARNESS.md`.
+Full methodology: `SDD.md`.
 
 Always start a session by reading `.specs/project/STATE.md`.
-All work follows the AI Development Harness in `SDD.md` Section 7.
 ```
 
 ---
@@ -1789,7 +1797,7 @@ All work follows the AI Development Harness in `SDD.md` Section 7.
 **Usage pattern:**
 1. Use Copilot Chat with explicit file context: "Given `spec.md` [paste], implement `sendShippedEmail`"
 2. Use `@workspace` in Copilot Chat to reference the full codebase (when available)
-3. Copilot is best for filling in implementation detail after design is done in `design.md`
+3. Copilot is best for filling in implementation detail after the plan is done in `plan.md`
 4. Manually validate and update `tasks.md` — Copilot does not maintain state
 
 **Limitation:** No persistent memory. Must re-establish context per chat session.
@@ -1841,7 +1849,7 @@ The orchestrating agent is responsible for integrating the sub-agent's output ba
 
 ### Start lean, grow as needed
 
-Do not create every `.specs/` file before writing any code. For a quick task, `quick/[name]/TASK.md` is sufficient. For a new medium feature, start with `spec.md` and `context.md`. Add `design.md` and `tasks.md` when the complexity warrants it.
+Do not create every `.specs/` file by hand before writing any code. Prefer `km-spec quick` or `km-spec feature` scaffolds. For a quick task, `quick/[name]/TASK.md` is sufficient. For a standard feature, fill `spec.md` and `context.md` before deep implementation; complete `plan.md` depth based on tier.
 
 ### STATE.md is the most important file
 
@@ -1849,7 +1857,7 @@ Every agent must read it first and update it last. A well-maintained `STATE.md`
 
 ### Trust the traceability chain
 
-When requirements change, follow the chain: update `spec.md`, then `design.md`, then `tasks.md`, then the code. Never update code and forget to update the spec. The spec is the contract — the code is the execution.
+When requirements change, follow the chain: update `spec.md`, then `plan.md`, then `tasks.md`, then the code. Never update code and forget to update the spec. The spec is the contract — the code is the execution.
 
 ### Keep validation evidence
 
@@ -1869,5 +1877,6 @@ Update `SDD.md` itself when the team finds patterns that work better, when tools
 
 ---
 
-*SDD v1.0.0 — Built on the TLC Spec Driven Development model.*  
+*SDD v1.1.0 (aligned with km-spec 0.2.0) — Built on the TLC Spec Driven Development model.*  
 *Tool-independent. Complexity-adaptive. AI-native.*
+*CLI scaffolds use `plan.md` + `validation.md`; see `HARNESS.md` for the agent lifecycle.*

package/templates/features/context.md

@@ -0,0 +1,69 @@
+<!-- km-spec-template: feature/context@1.0 -->
+# Context: {{FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_ID}} |
+| **Linked Spec** | `spec.md` |
+| **Created** | {{CREATED_DATE}} |
+| **Template** | feature/context@{{TEMPLATE_VERSION}} |
+
+<!--
+AGENT INSTRUCTIONS
+- Populate this file by reading the real repository. Do not invent paths.
+- Mark unknown items [NEEDS CLARIFICATION] until verified in source.
+- Prefer concrete file paths and symbols over vague module names.
+-->
+
+## Background and Motivation
+
+[NEEDS CLARIFICATION]: Why does this feature exist now? What problem does it solve for users or the system?
+
+{{DESCRIPTION_CONTEXT}}
+
+## Related Code Paths
+
+List real paths after inspection. Do not invent files.
+
+| Area | Path / Symbol | Notes | Confidence |
+|------|---------------|-------|------------|
+| Entry / API | [NEEDS CLARIFICATION] | | [NEEDS CLARIFICATION] |
+| Domain / service | [NEEDS CLARIFICATION] | | [NEEDS CLARIFICATION] |
+| Data / persistence | [NEEDS CLARIFICATION] | | [NEEDS CLARIFICATION] |
+| Tests | [NEEDS CLARIFICATION] | | [NEEDS CLARIFICATION] |
+
+## Existing Patterns to Follow
+
+- [NEEDS CLARIFICATION]: Reference an existing similar feature or module and the pattern to copy.
+- Check `.specs/codebase/CONVENTIONS.md` for project-wide patterns.
+
+## Prior Decisions
+
+| ID | Decision | Source | Confidence |
+|----|----------|--------|------------|
+| — | [NEEDS CLARIFICATION]: Link DEC-XXX from STATE.md or CONVENTIONS if any apply. | | [NEEDS CLARIFICATION] |
+
+## Likely Impacted Files
+
+Fill only after inspecting the codebase (target ≤ a reviewable set for the first slice).
+
+- [NEEDS CLARIFICATION]: `path/to/file` — reason
+
+## Risks
+
+| ID | Risk | Severity | Notes |
+|----|------|----------|-------|
+| RISK-001 | [NEEDS CLARIFICATION]: Unknown risk until code is inspected. | TBD | |
+
+## Anti-Patterns to Avoid
+
+- [NEEDS CLARIFICATION]: Patterns in this codebase that should not be copied for this feature.
+- Do not introduce unrelated refactors while implementing this feature.
+
+## Document Completion Criteria
+
+This `context.md` is **Ready for plan** when:
+
+- [ ] Related code paths point to files that exist in the repository.
+- [ ] Likely impacted files are based on inspection, not guesswork.
+- [ ] Relevant patterns and risks are noted or explicitly marked N/A with rationale.