km-spec-driven-development 0.1.0

package/templates/SDD.md

@@ -0,0 +1,1873 @@
+# Spec Driven Development (SDD)
+### AI-Assisted Development Methodology
+
+> Based on the [TLC Spec-Driven Development](https://agent-skills.techleads.club/skills/tlc-spec-driven/) model.  
+> Version: 1.0.0 | Date: 2026-06-25
+
+---
+
+## Table of Contents
+
+1. [Methodology Overview](#1-methodology-overview)
+2. [`.specs/` Folder Structure](#2-specs-folder-structure)
+3. [File Descriptions](#3-file-descriptions)
+4. [Adaptive Workflow](#4-adaptive-workflow)
+5. [AI Development Harness](#5-ai-development-harness)
+6. [Context Loading Strategy](#6-context-loading-strategy)
+7. [Agent Execution Protocol](#7-agent-execution-protocol)
+8. [Sub-Agent Rules](#8-sub-agent-rules)
+9. [Traceability Model](#9-traceability-model)
+10. [Templates](#10-templates)
+11. [New Project Process](#11-new-project-process)
+12. [Existing Project Process](#12-existing-project-process)
+13. [Validation Gates](#13-validation-gates)
+14. [Commit Conventions](#14-commit-conventions)
+15. [Security and Quality Rules](#15-security-and-quality-rules)
+16. [Practical Feature Example](#16-practical-feature-example)
+17. [Tool-Specific Guidance](#17-tool-specific-guidance)
+
+---
+
+## 1. Methodology Overview
+
+### What is SDD?
+
+Spec Driven Development (SDD) is a methodology for AI-assisted software development that creates a structured, persistent, and tool-independent contract between the codebase and any AI agent operating on it.
+
+The core problem SDD solves: **AI agents lose context between sessions, invent details, duplicate work, and make undocumented decisions that are invisible to the next agent or human reviewing the code.**
+
+SDD solves this by establishing a single source of truth in `.specs/` — a living documentation layer that any agent can read to understand what was built, why, how it should behave, and what comes next.
+
+### Core Principles
+
+1. **Complexity determines ceremony.** A bug fix in one file does not need the same overhead as a new authentication module. The process scales proportionally.
+2. **Every agent starts cold.** Each session, each tool, each sub-agent must be able to orient itself from the spec files alone — without relying on chat history.
+3. **No fabrication.** An agent must never invent APIs, file paths, function signatures, or behaviors. It reads what exists before it writes what is new.
+4. **Traceability is not optional.** Every implemented line should trace back to a requirement. Every decision should trace to a document.
+5. **STATE.md is the memory.** It is updated at the end of every session or after any relevant change. It is always loaded first.
+6. **Validate before closing.** A task is not done until validation evidence exists.
+
+### The Pipeline
+
+```
+SPECIFY → DESIGN → TASKS → EXECUTE → VALIDATE → RECORD STATE
+```
+
+The required phases are **Specify** and **Execute**. Design, Tasks, and the depth of each phase scale with complexity. The Record State phase is always mandatory — it is the mechanism that prevents context loss.
+
+---
+
+## 2. `.specs/` Folder Structure
+
+The default structure keeps a clear separation between project context and codebase context, while avoiding excessive mandatory documentation.
+
+```
+.specs/
+├── project/
+│   ├── PROJECT.md              # Vision, goals, users, constraints
+│   ├── ROADMAP.md              # Milestones, feature priority, planning
+│   └── STATE.md                # Persistent memory across sessions
+│
+├── codebase/
+│   └── CONVENTIONS.md          # Technical context, architecture, structure, testing, integrations, concerns, and AI rules
+│
+├── features/
+│   └── [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
+│
+└── quick/
+    └── [quick-task-name]/
+        ├── TASK.md             # What to do and acceptance criteria
+        └── SUMMARY.md          # What was done, files changed, outcome
+```
+
+### Default vs Optional Codebase Documentation
+
+By default, the codebase has only one required technical document:
+
+```
+.specs/codebase/CONVENTIONS.md
+```
+
+This file consolidates what would otherwise be split into separate files such as `STACK.md`, `ARCHITECTURE.md`, `STRUCTURE.md`, `TESTING.md`, `INTEGRATIONS.md`, and `CONCERNS.md`.
+
+If one section becomes too large or complex, it may be extracted later into an optional dedicated file:
+
+```
+.specs/codebase/ARCHITECTURE.md
+.specs/codebase/TESTING.md
+.specs/codebase/INTEGRATIONS.md
+.specs/codebase/CONCERNS.md
+```
+
+These files are optional expansions. They are not generated by default and should only be created when they reduce complexity instead of adding ceremony.
+
+---
+
+## 3. File Descriptions
+
+### 3.1 `project/PROJECT.md`
+
+**Purpose:** The north star. Defines what the project is, who it is for, what success looks like, and what constraints must never be violated.
+
+**Created:** At project initialization (greenfield) or at first SDD adoption (brownfield).
+
+**Updated:** Only when the project's fundamental direction changes. Not for individual features.
+
+**Contains:**
+- Project name, one-sentence description
+- Problem being solved
+- Target users/stakeholders
+- Success criteria and KPIs
+- Non-negotiable constraints (performance, security, compliance)
+- Out-of-scope items
+- Key terminology/glossary
+
+---
+
+### 3.2 `project/ROADMAP.md`
+
+**Purpose:** Priority-ordered list of capabilities, milestones, and features. Gives agents a sense of what is planned and in what order.
+
+**Created:** During project initialization.
+
+**Updated:** When features are added, completed, reprioritized, or cancelled. Reflects current reality, not aspirational planning.
+
+**Contains:**
+- Milestones with target dates
+- Feature list per milestone (with status: planned / in-progress / done / cancelled)
+- Rationale for priority ordering
+- Dependencies between features
+
+---
+
+### 3.3 `project/STATE.md`
+
+**Purpose:** Persistent project memory. Bridges sessions so that the next agent or human picking up the work has full situational awareness without reading git history or chat logs.
+
+**Created:** After the first working session.
+
+**Updated:** At the end of every session and after any significant decision, blocker, or architectural choice.
+
+**Contains:**
+- Last task executed (with ID)
+- Current task in progress (with ID)
+- Suggested next steps
+- Decisions made (with DEC-XXX IDs)
+- Open blockers
+- Pending items
+- Deferred ideas
+- Project preferences and conventions discovered during work
+- Lessons learned
+- Session log (date, summary, what changed)
+
+> **Rule:** An AI must never end a session without updating STATE.md.
+
+---
+
+### 3.4 `codebase/CONVENTIONS.md`
+
+**Purpose:** The technical operating manual for the project. It is the single required codebase document and contains the information agents need to work safely without creating multiple mandatory technical files.
+
+**Created:** At project setup or during brownfield mapping.
+
+**Updated:** Whenever the stack, architecture, folder structure, testing strategy, integrations, risks, or coding conventions change.
+
+**Contains:**
+
+#### 1. Technical Context
+
+- Runtime and language versions
+- Core frameworks and libraries
+- Package manager and lockfile policy
+- Database and data stores
+- Build tools, bundlers, transpilers
+- Deployment platform and CI/CD tools
+
+#### 2. Architecture
+
+- High-level system design
+- Module/layer breakdown
+- Data flow narratives
+- Key architectural decisions
+- Scaling and deployment model
+- Monorepo vs. multi-repo structure if applicable
+
+#### 3. Project Structure
+
+- Annotated directory tree
+- Rules for where new files go
+- Co-location rules for tests, components, modules, and assets
+- Generated vs. handwritten file boundaries
+
+#### 4. Coding Standards
+
+- Naming conventions
+- Import ordering
+- Error handling patterns
+- Logging standards
+- Comment policy
+- Branch naming and PR conventions
+- Environment variable patterns
+- Feature flag conventions
+
+#### 5. Testing
+
+- Test types used: unit, integration, e2e, contract
+- Test file naming and organization
+- Mocking rules
+- Fixtures and factories
+- Commands to run validation gates
+- Coverage and CI expectations
+
+#### 6. Integrations
+
+- External APIs and services
+- SDKs in use and their configuration
+- Webhook endpoints and event contracts
+- Rate limits and retry policies
+- Credentials management pattern
+- Integration-specific risks
+
+#### 7. Concerns
+
+- Technical debt
+- Known performance bottlenecks
+- Security concerns
+- Deprecated patterns still in use
+- Areas with insufficient test coverage
+- Fragile modules or files agents should modify carefully
+
+#### 8. AI Rules
+
+- Do not invent files, APIs, functions, or behavior.
+- Read existing code before modifying it.
+- Follow existing project patterns.
+- Do not refactor unrelated code.
+- Keep changes small and reviewable.
+- Validate before marking work as done.
+- Update `.specs/project/STATE.md` at the end of the session.
+
+> **Expansion rule:** If one section becomes too large, extract it into a dedicated optional file. For example, move the Architecture section to `.specs/codebase/ARCHITECTURE.md` only when that makes the project easier to understand.
+
+---
+
+### 3.5 `features/[name]/spec.md`
+
+**Purpose:** Single source of truth for a feature's requirements, scope, and acceptance criteria. The primary document that drives all downstream work.
+
+**Created:** When a feature is approved for development.
+
+**Updated:** Only when requirements change (with change log).
+
+**Contains:**
+- Feature ID and title
+- Linked requirements (REQ-XXX)
+- User stories
+- Acceptance criteria (testable, specific)
+- Out-of-scope clarifications
+- Open questions
+- Change log
+
+---
+
+### 3.6 `features/[name]/context.md`
+
+**Purpose:** Provides agents with the "why" and the surrounding codebase context so they can make good decisions without reading every file.
+
+**Created:** When spec.md is created.
+
+**Updated:** When context evolves during implementation.
+
+**Contains:**
+- Background and motivation
+- Related existing features or modules
+- Prior decisions that constrain this feature
+- Files most likely to be impacted
+- Patterns to follow (with code references)
+- Anti-patterns to avoid
+
+---
+
+### 3.7 `features/[name]/design.md`
+
+**Purpose:** Technical design for the feature. Translates requirements into an implementable structure.
+
+**Created:** After spec.md, before tasks.md, for medium/large/complex features.
+
+**Skipped for:** Quick tasks and simple features where the implementation path is obvious.
+
+**Updated:** When design decisions change during implementation (with DEC-XXX entries).
+
+**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
+
+---
+
+### 3.8 `features/[name]/tasks.md`
+
+**Purpose:** The execution plan. Breaks design into atomic, verifiable, and potentially parallelizable tasks.
+
+**Created:** After design.md, for medium/large/complex features.
+
+**Skipped for:** Quick tasks. For medium features, tasks may be inlined in spec.md.
+
+**Updated:** As tasks are completed (status updated), or when new tasks are discovered during execution.
+
+**Contains:**
+- Full task list with TASK-XXX IDs
+- Dependencies between tasks
+- Parallelization markers (`[P]`)
+- Per-task: objective, files, steps, acceptance criteria, tests, validation gate, status
+
+---
+
+### 3.9 `quick/[name]/TASK.md`
+
+**Purpose:** Scoped description of a small task — a bug fix, small adjustment, or refactor that doesn't justify a full feature spec.
+
+**Created:** When a quick task is identified.
+
+**Contains:**
+- Task title and objective
+- Files affected (max 3 for quick mode)
+- Acceptance criteria
+- Validation steps
+
+---
+
+### 3.10 `quick/[name]/SUMMARY.md`
+
+**Purpose:** Post-execution record of what was done for the quick task.
+
+**Created:** After the task is complete.
+
+**Contains:**
+- Files changed
+- What was changed and why
+- Tests run and result
+- Deviations from the original task
+- Any follow-up actions
+
+---
+
+## 4. Adaptive Workflow
+
+### The Six Phases
+
+```
+1. SPECIFY     → Define scope, requirements, acceptance criteria
+2. DESIGN      → Translate requirements into technical structure
+3. TASKS       → Decompose into atomic, verifiable steps
+4. EXECUTE     → Implement, following the harness protocol
+5. VALIDATE    → Run all gates; verify acceptance criteria
+6. RECORD STATE → Update STATE.md with decisions, outcomes, next steps
+```
+
+**Always required:** SPECIFY (even if minimal), EXECUTE, VALIDATE, RECORD STATE.  
+**Conditional:** DESIGN and TASKS scale with complexity.
+
+---
+
+### Complexity Tiers
+
+#### Quick Task
+**Profile:** Bug fix, copy change, config tweak. Affects ≤3 files. No ambiguity.
+
+**Workflow:**
+1. Create `quick/[name]/TASK.md`
+2. Execute directly (no design doc needed)
+3. Run validation gates
+4. Create `quick/[name]/SUMMARY.md`
+5. Update `STATE.md`
+
+**Ceremony level:** Minimal. Total overhead: ~5 minutes.
+
+---
+
+#### Medium Feature
+**Profile:** Clear functionality with defined inputs/outputs. Low ambiguity. Fewer than 3 existing dependencies impacted.
+
+**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`
+
+**Ceremony level:** Low-to-medium. Skip `design.md` if implementation path is clear.
+
+---
+
+#### Large Feature
+**Profile:** Multiple components. Touches existing architecture. Clear requirements but broad scope.
+
+**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.
+
+---
+
+### Safety Valve Rule
+
+> **Even when Tasks is skipped, Execute ALWAYS starts by listing atomic steps inline before writing any code. If listing reveals more than 5 steps or complex dependencies, STOP and create `tasks.md` first.**
+
+---
+
+## 5. AI Development Harness
+
+The AI Development Harness is the operational contract between any AI agent and this repository. It defines exactly how an agent should orient, execute, validate, and hand off — regardless of which tool is being used.
+
+The harness has five components:
+
+1. Context Loading Strategy (what to read and when)
+2. Knowledge Verification Chain (how to verify before writing)
+3. Execution Protocol (how to implement a task)
+4. Validation Protocol (what done actually means)
+5. Session Closure Protocol (how to leave the project in a clean state)
+
+An agent that follows the harness never fabricates, never skips validation, and never leaves without updating STATE.md.
+
+---
+
+## 6. Context Loading Strategy
+
+### Always Load First (Base Context, ~15k tokens)
+
+| File | Reason |
+|------|--------|
+| `.specs/project/STATE.md` | Situational awareness, last task, blockers |
+| `.specs/project/PROJECT.md` | Goals, constraints, non-negotiables |
+| `.specs/codebase/CONVENTIONS.md` | Rules that apply to every line of code |
+
+Do not skip these. They are the minimum for any agent to operate safely.
+
+---
+
+### Load on Demand (Feature and Technical Context)
+
+Load only when working on the relevant feature or area:
+
+| File or Section | Load When |
+|------|-----------|
+| `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]/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 |
+| `codebase/CONVENTIONS.md` → Project Structure | Creating new files or directories |
+| `codebase/CONVENTIONS.md` → Testing | Writing or updating tests |
+| `codebase/CONVENTIONS.md` → Integrations | Working with external services |
+| `codebase/CONVENTIONS.md` → Concerns | Touching known risk areas |
+
+If an optional extracted file exists, such as `.specs/codebase/ARCHITECTURE.md`, load it only when the current task requires that specific context.
+
+---
+
+### Never Load Together
+
+Avoid loading all feature specs simultaneously. Load only the feature being worked on. Do not load `ROADMAP.md` unless doing project planning — it adds tokens without aiding implementation.
+
+---
+
+### Context Budget Rules
+
+| Budget | Action |
+|--------|--------|
+| Base load | ~15k tokens (always) |
+| On-demand additions | Load only what the current task requires |
+| Hard ceiling | Stay under 40k tokens for context |
+| Reservation | Keep 160k+ tokens free for reasoning and output |
+
+**Rule:** If context is approaching the ceiling, summarize completed work into STATE.md and start a fresh context window loading only base files plus the current task's files.
+
+---
+
+### Staleness Rule
+
+Before using any cached information about a file, re-read the file. Never operate on a mental model of what a file contains — read it. If a file does not exist where expected, stop and investigate rather than proceeding with assumptions.
+
+---
+
+## 7. Agent Execution Protocol
+
+### Step 1: Orient
+
+```
+1. Read STATE.md                         → understand current project state
+2. Read PROJECT.md                       → recall constraints
+3. Read CONVENTIONS.md                   → recall code rules
+4. Read the task file (spec.md / TASK.md / tasks.md entry)
+5. Confirm: Does this task have all required information?
+   - If missing info → ask before proceeding
+   - If blocked by dependency → record in STATE.md and stop
+```
+
+---
+
+### Step 2: Verify Dependencies
+
+```
+1. Identify files this task will touch
+2. Read each file — do not assume content
+3. Verify that assumed APIs, functions, and types actually exist
+4. Check CONVENTIONS.md → Technical Context before using language, framework, library, or package-manager assumptions
+5. Check CONVENTIONS.md → Project Structure before creating or moving files
+6. Check CONVENTIONS.md → Testing before writing or changing tests
+7. Check CONVENTIONS.md → Integrations before touching external service calls
+8. Check CONVENTIONS.md → Concerns before modifying risky or fragile areas
+```
+
+If optional extracted files exist, such as `.specs/codebase/TESTING.md` or `.specs/codebase/INTEGRATIONS.md`, read them only for tasks that require that specific context.
+
+**Knowledge Verification Chain (strict order):**
+1. Read the actual source files in the codebase
+2. Read the project's spec docs
+3. Read the relevant sections of `CONVENTIONS.md`
+4. Read optional extracted codebase docs if they exist and are relevant
+5. Read library documentation if needed
+6. Search the web if necessary
+7. Flag as uncertain if still unresolved — never fabricate
+
+---
+
+### Step 3: Plan Inline
+
+```
+Before writing code, list the atomic steps:
+  - Step 1: [file] [action]
+  - Step 2: [file] [action]
+  ...
+
+If > 5 steps or complex dependencies → create tasks.md and stop for review.
+If ≤ 5 steps → proceed.
+```
+
+---
+
+### Step 4: Implement
+
+```
+1. Implement only the scope of the current task — nothing more
+2. Follow CONVENTIONS.md for naming, structure, architecture, testing, integrations, and known concerns
+3. Use the Project Structure section in CONVENTIONS.md for file placement
+4. Use existing patterns — confirm them by reading code, not assuming
+5. Do not refactor unrelated code
+6. Do not introduce abstractions not required by this task
+7. Keep changes small and reviewable
+```
+
+---
+
+### Step 5: Validate
+
+```
+1. Run: build
+2. Run: lint
+3. Run: typecheck
+4. Run: tests (unit + integration relevant to changed code)
+5. Check: Do the changes satisfy the acceptance criteria in spec.md?
+6. Check: Are there regressions in adjacent features?
+7. If any gate fails → fix before marking task complete
+```
+
+**Rule:** An agent must never mark a task as complete without recorded validation evidence.
+
+---
+
+### Step 6: Record
+
+```
+1. Update tasks.md:
+   - Set task status to DONE
+   - Record files changed
+   - Record test results
+
+2. Update STATE.md:
+   - Log the session (date, task completed, outcome)
+   - Record any decisions made (with DEC-XXX IDs)
+   - Record any deviations from the spec
+   - Record blockers encountered
+   - Set suggested next steps
+
+3. Commit with atomic message following commit conventions
+```
+
+---
+
+### Deviation Protocol
+
+If implementation reveals that the spec is wrong, incomplete, or contradicts an existing constraint:
+
+1. **Stop.** Do not implement a workaround silently.
+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.
+
+---
+
+## 8. Sub-Agent Rules
+
+### When to Delegate to a Sub-Agent
+
+| Scenario | Use Sub-Agent |
+|----------|---------------|
+| Technical research or library evaluation | Yes |
+| Codebase mapping of an unfamiliar area | Yes |
+| Independent task execution (parallelizable) | Yes |
+| Security review | Yes |
+| Test suite creation for a module | Yes |
+| Architecture validation | Yes |
+| Drafting a feature spec | Optional |
+| Implementing the current focused task | No — keep in main agent |
+
+---
+
+### What to Pass to a Sub-Agent
+
+A sub-agent receives a self-contained briefing. It must never rely on chat history or accumulated conversation context.
+
+**Required input:**
+```
+1. Task description (exact scope, no ambiguity)
+2. Relevant spec files (spec.md, context.md, or design.md for the area)
+3. Relevant codebase docs (CONVENTIONS.md always; others on demand)
+4. Specific files to read or modify
+5. Acceptance criteria
+6. Test requirements
+7. What to return (see output format below)
+```
+
+**Never pass:**
+- Chat history
+- Full project context when only feature context is needed
+- Multiple unrelated tasks in one briefing
+
+---
+
+### Sub-Agent Output Format
+
+Every sub-agent response must be structured as follows:
+
+```markdown
+## Sub-Agent Report
+
+**Task ID:** TASK-XXX
+**Agent Role:** [Research | Implementation | Security | Testing | Mapping]
+**Status:** Complete | Partial | Blocked
+
+### Changed Files
+- `path/to/file.ts` — [description of change]
+- `path/to/test.spec.ts` — [description of change]
+
+### Tests Executed
+- TEST-001: [test name] → PASSED | FAILED
+- TEST-002: [test name] → PASSED | FAILED
+
+### Validation Result
+- Build: PASS | FAIL
+- Lint: PASS | FAIL
+- Typecheck: PASS | FAIL
+- Acceptance Criteria [REQ-XXX]: MET | NOT MET
+
+### Risks Found
+- RISK-XXX: [description of risk]
+
+### Deviations from Specification
+- [Description of deviation, if any]
+
+### Recommended Next Steps
+1. [Next action]
+2. [Next action]
+```
+
+The orchestrating agent reads this report and decides whether to proceed, escalate, or re-task.
+
+---
+
+### Sub-Agent Isolation Rule
+
+Sub-agents work on isolated scopes. Two sub-agents must never write to the same file simultaneously. The orchestrating agent is responsible for sequencing or merging conflicting changes.
+
+For parallelizable tasks (marked `[P]` in `tasks.md`), confirm they touch disjoint files before running in parallel.
+
+---
+
+## 9. Traceability Model
+
+### ID Scheme
+
+| ID Prefix | Entity | Example |
+|-----------|--------|---------|
+| `REQ-XXX` | Requirement | REQ-001 |
+| `DEC-XXX` | Decision | DEC-001 |
+| `TASK-XXX` | Task | TASK-001 |
+| `TEST-XXX` | Test | TEST-001 |
+| `RISK-XXX` | Risk | RISK-001 |
+
+IDs are sequential and unique per project. Never reuse an ID, even after deletion.
+
+---
+
+### Traceability Chain
+
+```
+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)
+                    └── Commit (references TASK-XXX in message)
+```
+
+Every task must reference the requirements it satisfies. Every test must reference the requirement or acceptance criterion it validates. Every decision must reference the context that prompted it.
+
+---
+
+### Traceability Rules
+
+1. No task is created without a parent requirement.
+2. No test is created without a parent task or requirement.
+3. No significant decision is made without a DEC-XXX entry.
+4. Commits reference TASK-XXX in the commit message.
+5. If a requirement changes, all dependent tasks, tests, and design notes must be reviewed and updated.
+
+---
+
+## 10. Templates
+
+### 10.1 `spec.md` Template
+
+```markdown
+# [Feature Name] — Specification
+
+**Feature ID:** FEAT-XXX
+**Created:** YYYY-MM-DD
+**Status:** Draft | Approved | In Progress | Complete
+**Owner:** [team or person]
+
+## Overview
+
+[1–3 sentence description of what this feature does and why it exists.]
+
+## Requirements
+
+| ID | Description | Priority |
+|----|-------------|----------|
+| REQ-001 | [Requirement statement] | Must Have |
+| REQ-002 | [Requirement statement] | Should Have |
+| REQ-003 | [Requirement statement] | Nice to Have |
+
+## User Stories
+
+- As a [user type], I want to [action] so that [benefit].
+- As a [user type], I want to [action] so that [benefit].
+
+## Acceptance Criteria
+
+- [ ] REQ-001: [Specific, testable criterion]
+- [ ] REQ-002: [Specific, testable criterion]
+- [ ] REQ-003: [Specific, testable criterion]
+
+## Out of Scope
+
+- [Explicit exclusion]
+- [Explicit exclusion]
+
+## Open Questions
+
+- [ ] [Question] — Owner: [name] — Due: [date]
+
+## Change Log
+
+| Date | Change | Author |
+|------|--------|--------|
+| YYYY-MM-DD | Initial draft | [name] |
+```
+
+---
+
+### 10.2 `design.md` Template
+
+```markdown
+# [Feature Name] — Technical Design
+
+**Feature ID:** FEAT-XXX
+**Linked Spec:** spec.md
+**Created:** YYYY-MM-DD
+**Status:** Draft | Approved | Superseded
+
+## Overview
+
+[Brief description of the technical approach.]
+
+## Components
+
+### [Component Name]
+
+**Responsibility:** [What this component does]
+**Location:** `src/path/to/component`
+**Interface:**
+```typescript
+// Describe the public interface
+```
+
+## Data Model
+
+### [Entity Name]
+
+```
+Field        | Type    | Constraints | Notes
+-------------|---------|-------------|------
+id           | uuid    | PK, required |
+name         | string  | max 255     |
+created_at   | datetime| required    |
+```
+
+## API Contracts
+
+### `POST /api/[resource]`
+
+**Request:**
+```json
+{
+  "field": "type"
+}
+```
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "field": "type"
+}
+```
+
+**Error states:**
+- 400: [condition]
+- 401: [condition]
+- 409: [condition]
+
+## State Management
+
+[Describe how state flows through the feature if applicable.]
+
+## Error Handling
+
+| Error Condition | Behavior | User Feedback |
+|----------------|----------|---------------|
+| [condition] | [action] | [message] |
+
+## Performance Considerations
+
+- [Note any N+1 risks, large queries, or caching needs]
+
+## Security Considerations
+
+- [Note authentication, authorization, input validation concerns]
+
+## Decisions
+
+| ID | Decision | Alternatives Considered | Rationale |
+|----|----------|------------------------|-----------|
+| DEC-001 | [Decision made] | [Alt A, Alt B] | [Why this choice] |
+
+## Change Log
+
+| Date | Change | Author |
+|------|--------|--------|
+| YYYY-MM-DD | Initial draft | [name] |
+```
+
+---
+
+### 10.3 `tasks.md` Template
+
+```markdown
+# [Feature Name] — Tasks
+
+**Feature ID:** FEAT-XXX
+**Linked Spec:** spec.md
+**Linked Design:** design.md
+**Created:** YYYY-MM-DD
+
+## Status Summary
+
+| Status | Count |
+|--------|-------|
+| TODO   | X     |
+| IN PROGRESS | X |
+| DONE   | X     |
+| BLOCKED | X   |
+
+---
+
+## TASK-001 — [Task Title] [P]
+
+> `[P]` marks a parallelizable task. Only valid when this task's files are disjoint from all currently running parallel tasks.
+
+**Objective:** [One sentence description of what this task achieves]
+
+**Satisfies:** REQ-001, REQ-002
+
+**Likely Files:**
+- `src/path/to/file.ts` — [reason]
+- `src/path/to/test.spec.ts` — [reason]
+
+**Dependencies:** None | TASK-XXX must complete first
+
+**Implementation Steps:**
+1. [Specific action]
+2. [Specific action]
+3. [Specific action]
+
+**Acceptance Criteria:**
+- [ ] [Testable criterion linked to spec]
+- [ ] [Testable criterion linked to spec]
+
+**Required Tests:**
+- TEST-001: [Test description] — unit | integration | e2e
+
+**Validation Gate:**
+- [ ] Build passes
+- [ ] Lint passes
+- [ ] Typecheck passes
+- [ ] TEST-001 passes
+- [ ] Acceptance criteria verified manually
+
+**Status:** TODO | IN PROGRESS | DONE | BLOCKED
+
+**Notes:** [Deviations, blockers, discoveries during implementation]
+
+---
+
+## TASK-002 — [Task Title]
+
+[Repeat structure above]
+```
+
+---
+
+### 10.4 `STATE.md` Template
+
+```markdown
+# Project State
+
+**Last Updated:** YYYY-MM-DD HH:MM
+**Last Task Completed:** TASK-XXX — [brief description]
+**Current Task:** TASK-XXX — [brief description]
+**Project Phase:** [Setup | Active Development | Stabilization | Maintenance]
+
+## Suggested Next Steps
+
+1. [TASK-XXX] [brief description]
+2. [TASK-XXX] [brief description]
+3. [Open question or decision needed]
+
+## Open Blockers
+
+| ID | Description | Owner | Since |
+|----|-------------|-------|-------|
+| BLK-001 | [Description] | [owner] | YYYY-MM-DD |
+
+## Decisions Log
+
+| ID | Date | Decision | Rationale | Impact |
+|----|------|----------|-----------|--------|
+| DEC-001 | YYYY-MM-DD | [Decision] | [Why] | [What it affects] |
+
+## Deviations from Specification
+
+| Date | Task | Deviation | Resolution |
+|------|------|-----------|------------|
+| YYYY-MM-DD | TASK-XXX | [What changed] | [How resolved or deferred] |
+
+## Pending Items
+
+- [ ] [Item] — [owner or context]
+- [ ] [Item] — [owner or context]
+
+## Deferred Ideas
+
+- [Idea] — [deferred reason] — [potential future ticket]
+
+## Project Preferences Discovered
+
+- [Convention or preference discovered during implementation]
+- [Tooling quirk or project-specific rule not in CONVENTIONS.md]
+
+## Lessons Learned
+
+- [Lesson] — discovered during [TASK-XXX or context]
+
+## Session Log
+
+| Date | Summary | Tasks Completed | Key Decisions |
+|------|---------|----------------|---------------|
+| YYYY-MM-DD | [What happened this session] | TASK-001, TASK-002 | DEC-001 |
+```
+
+---
+
+### 10.5 `CONVENTIONS.md` Template
+
+````markdown
+# Codebase Conventions
+
+## 1. Technical Context
+
+Describe the core technical context of the project.
+
+- Language:
+- Runtime:
+- Framework:
+- Package manager:
+- Database:
+- Main libraries:
+- Build tools:
+- Deployment:
+- CI/CD:
+
+## 2. Architecture
+
+Describe the general architecture, layers, modules, data flow, and important technical decisions.
+
+### Layers / Modules
+
+-
+
+### Data Flow
+
+-
+
+### Decisions
+
+| ID | Decision | Rationale | Impact |
+|----|----------|-----------|--------|
+| DEC-001 | | | |
+
+## 3. Project Structure
+
+Explain the project folder structure and where new files should be created.
+
+```txt
+src/
+├── ...
+```
+
+### File Placement Rules
+
+- New API routes:
+- New components:
+- New services:
+- New tests:
+- New assets:
+
+## 4. Coding Standards
+
+Define naming conventions, import organization, error handling, logging, environment variables, and coding style.
+
+### Naming
+
+-
+
+### Imports
+
+-
+
+### Error Handling
+
+-
+
+### Logging
+
+-
+
+### Environment Variables
+
+-
+
+## 5. Testing
+
+Describe how tests should be written, where they should live, which commands should be run, and which validation gates are required.
+
+### Test Types
+
+- Unit:
+- Integration:
+- E2E:
+
+### Commands
+
+```bash
+# build
+
+# lint
+
+# typecheck
+
+# test
+```
+
+### Required Gates
+
+- [ ] Build passes
+- [ ] Lint passes, if available
+- [ ] Typecheck passes, if available
+- [ ] Tests pass, if available
+- [ ] Acceptance criteria verified
+
+## 6. Integrations
+
+List external services, APIs, SDKs, webhooks, authentication methods, and integration concerns.
+
+| Service | Purpose | Auth | Notes |
+|---------|---------|------|-------|
+| | | | |
+
+## 7. Concerns
+
+List technical risks, tech debt, fragile areas, limitations, and parts of the codebase that agents should modify carefully.
+
+| ID | Area | Concern | Severity | Notes |
+|----|------|---------|----------|-------|
+| RISK-001 | | | | |
+
+## 8. AI Rules
+
+- Do not invent files, APIs, functions, or behavior.
+- Read existing code before modifying it.
+- Follow existing project patterns.
+- Do not refactor unrelated code.
+- Keep changes small and reviewable.
+- Validate before marking work as done.
+- Update `.specs/project/STATE.md` at the end of the session.
+
+## Optional Expansion
+
+If one section becomes too large, it may be extracted into a dedicated optional file, such as:
+
+- `.specs/codebase/ARCHITECTURE.md`
+- `.specs/codebase/TESTING.md`
+- `.specs/codebase/INTEGRATIONS.md`
+- `.specs/codebase/CONCERNS.md`
+
+These files are optional and should not be generated by default.
+````
+
+---
+
+## 11. New Project Process
+
+### Step 1: Initialize Project Spec
+
+Create the following files before writing any code:
+
+```
+.specs/project/PROJECT.md     → Fill in vision, goals, users, constraints
+.specs/project/ROADMAP.md     → List initial milestones and features
+.specs/project/STATE.md       → Initialize with project phase and first tasks
+.specs/codebase/CONVENTIONS.md → Fill in technical context and development rules
+```
+
+Key questions to answer in `PROJECT.md`:
+- What problem does this project solve?
+- Who are the users?
+- What are the non-negotiable constraints?
+- What is explicitly out of scope?
+- What does success look like in 3 months? 12 months?
+
+---
+
+### Step 2: Define Codebase Conventions
+
+Create `.specs/codebase/CONVENTIONS.md` before writing production code.
+
+Fill in these sections:
+
+1. **Technical Context** — language, framework, runtime, package manager, database, infrastructure, and main tools.
+2. **Architecture** — modules, layers, data flow, boundaries, and important technical decisions.
+3. **Project Structure** — folder layout and rules for where new files should go.
+4. **Coding Standards** — naming, imports, errors, logs, env vars, comments, and style.
+5. **Testing** — test strategy, file placement, commands, gates, mocks, and coverage expectations.
+6. **Integrations** — external services, APIs, SDKs, webhooks, auth, rate limits, and secrets pattern.
+7. **Concerns** — risks, fragile areas, technical debt, limitations, and known gaps.
+8. **AI Rules** — how agents must read, modify, validate, and record work.
+
+---
+
+### Step 3: Specify First Feature
+
+Create `features/[first-feature]/spec.md` with requirements, user stories, and acceptance criteria.
+
+Then follow the adaptive workflow based on the feature's complexity tier.
+
+---
+
+### Optional Expansion
+
+Do not create separate codebase files by default. If one section of `CONVENTIONS.md` becomes too large, extract it into an optional dedicated file:
+
+```
+.specs/codebase/ARCHITECTURE.md
+.specs/codebase/TESTING.md
+.specs/codebase/INTEGRATIONS.md
+.specs/codebase/CONCERNS.md
+```
+
+Create these only when they reduce complexity.
+
+---
+
+### Greenfield Checklist
+
+```
+[ ] .specs/project/PROJECT.md created
+[ ] .specs/project/ROADMAP.md created
+[ ] .specs/project/STATE.md initialized
+[ ] .specs/codebase/CONVENTIONS.md created
+[ ] CONVENTIONS.md → Technical Context filled
+[ ] CONVENTIONS.md → Architecture filled
+[ ] CONVENTIONS.md → Project Structure filled
+[ ] CONVENTIONS.md → Testing filled
+[ ] CONVENTIONS.md → Integrations filled, if applicable
+[ ] CONVENTIONS.md → Concerns filled, if applicable
+[ ] First feature spec created
+[ ] Initial commit includes .specs/ folder
+```
+
+---
+
+## 12. Existing Project Process
+
+### Step 1: Codebase Mapping
+
+Before modifying anything in a brownfield project, an agent must map what exists. This is a read-only discovery phase.
+
+The mapping should populate `.specs/codebase/CONVENTIONS.md` instead of creating several mandatory technical files.
+
+**Mapping deliverables inside `CONVENTIONS.md`:**
+
+| Section | Source of Truth |
+|------|----------------|
+| Technical Context | `package.json`, lockfiles, config files, runtime files |
+| Project Structure | Directory tree + file organization patterns |
+| Architecture | Entry points, routers, modules, services, data flow |
+| Coding Standards | Patterns found in existing code |
+| Testing | Test files, coverage config, CI config |
+| Integrations | External service calls, env vars, SDK usage |
+| Concerns | TODO comments, deprecated patterns, coverage gaps, fragile areas |
+
+**Mapping process:**
+1. Read package/config/lock files → populate Technical Context
+2. Run directory tree scan → populate Project Structure
+3. Read entry points, routers, main modules → populate Architecture
+4. Read 10–15 representative source files → extract Coding Standards
+5. Read test files and CI config → populate Testing
+6. Grep for external service calls and env var usage → populate Integrations
+7. Grep for TODO, FIXME, HACK, deprecated patterns, and dead code → populate Concerns
+
+Do not start writing features until the relevant sections of `CONVENTIONS.md` are mapped.
+
+---
+
+### Step 2: Validate Mapping
+
+After mapping, review `CONVENTIONS.md` for:
+- Contradictions: pattern A in one module, pattern B in another. Document both.
+- Gaps: areas with no clear convention. Add them to Concerns or Open Questions.
+- Risks: create RISK-XXX entries for anything that needs attention before new work.
+
+If one mapped section becomes too large, extract it into an optional dedicated file and link it from `CONVENTIONS.md`.
+
+---
+
+### Step 3: Align on State
+
+Create `.specs/project/STATE.md` with:
+- Current state of the project: what is working, what is broken
+- Known blockers
+- What the first feature/fix should be
+- Technical debt and risks summarized from `CONVENTIONS.md` → Concerns
+
+---
+
+### Step 4: Proceed with Feature Workflow
+
+With mapping complete, treat subsequent work the same as greenfield — follow the adaptive workflow for each feature.
+
+---
+
+### Brownfield Checklist
+
+```
+[ ] CONVENTIONS.md → Technical Context mapped from existing code
+[ ] CONVENTIONS.md → Project Structure mapped from directory tree
+[ ] CONVENTIONS.md → Architecture mapped from module analysis
+[ ] CONVENTIONS.md → Coding Standards extracted from existing code patterns
+[ ] CONVENTIONS.md → Testing mapped from test files and CI config
+[ ] CONVENTIONS.md → Integrations mapped from external service usage, if applicable
+[ ] CONVENTIONS.md → Concerns populated with debt, risks, and gaps
+[ ] STATE.md initialized with project current state
+[ ] First task identified and scoped
+```
+
+---
+
+## 13. Validation Gates
+
+### Gate Definitions
+
+Every task must pass all applicable gates before being marked DONE.
+
+| Gate | Description | Required |
+|------|-------------|----------|
+| **BUILD** | Project compiles without errors | Always |
+| **LINT** | Code passes all lint rules | Always |
+| **TYPECHECK** | Type errors: zero | Always (typed languages) |
+| **UNIT** | Unit tests for changed logic pass | Always |
+| **INTEGRATION** | Integration tests for affected paths pass | When paths are affected |
+| **E2E** | End-to-end scenarios pass | For user-facing features |
+| **ACCEPTANCE** | Acceptance criteria from spec.md verified | Always |
+| **MANUAL** | Manual test of the feature | For UI changes |
+| **SECURITY** | Security review passed | For auth, data, or external integration changes |
+| **REGRESSION** | Adjacent features unbroken | Always |
+| **COVERAGE** | Coverage thresholds maintained | Per `CONVENTIONS.md` → Testing rules |
+
+---
+
+### Gate Evidence Format
+
+When recording validation in `tasks.md` or `STATE.md`:
+
+```
+Validation Evidence — TASK-XXX
+- Build: PASS (npm run build — 0 errors)
+- Lint: PASS (eslint — 0 warnings, 0 errors)
+- Typecheck: PASS (tsc — 0 errors)
+- Unit tests: PASS (23/23 — 0 failures)
+- Integration tests: PASS (7/7)
+- Acceptance: PASS — REQ-001 verified, REQ-002 verified
+- Regression: PASS — unrelated test suites unchanged
+```
+
+---
+
+### Failure Protocol
+
+If a gate fails:
+1. Stop. Do not proceed to the next task.
+2. Record the failure in `STATE.md` under Open Blockers.
+3. Fix the root cause — do not suppress or work around it.
+4. Re-run the failed gate and all gates after it.
+5. Update task status and validation evidence.
+
+---
+
+## 14. Commit Conventions
+
+### Format
+
+```
+<type>(<scope>): <short description> [TASK-XXX]
+
+[Optional body — what changed and why, not how]
+
+[Optional footer — breaking changes, issue references]
+```
+
+### Types
+
+| Type | Use |
+|------|-----|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Restructure without behavior change |
+| `test` | Adding or fixing tests |
+| `docs` | Documentation only |
+| `chore` | Build, tooling, dependency updates |
+| `perf` | Performance improvement |
+| `security` | Security fix |
+| `spec` | Changes to `.specs/` files only |
+
+### Rules
+
+1. One logical change per commit. Never bundle unrelated changes.
+2. Every commit that implements a task must reference `TASK-XXX` in the message.
+3. Breaking changes must be flagged in the footer: `BREAKING CHANGE: [description]`.
+4. Commits to `.specs/` use type `spec`.
+5. Never squash commits that contain TASK-XXX references — they are the traceability chain.
+
+### Examples
+
+```
+feat(auth): add JWT refresh token endpoint [TASK-004]
+
+Implements the refresh token flow described in REQ-003.
+Tokens expire after 7 days and rotate on each use.
+```
+
+```
+spec(user-profile): add design.md with API contract [TASK-003]
+```
+
+```
+fix(orders): prevent duplicate submission on slow network [TASK-011]
+
+Race condition in submit handler caused double inserts.
+Added optimistic lock using idempotency key.
+```
+
+---
+
+## 15. Security and Quality Rules
+
+### Security Rules
+
+1. **No secrets in code.** All credentials use environment variables. Never hardcode tokens, passwords, or API keys.
+2. **Validate all inputs at the boundary.** Never trust data arriving from users, external APIs, or message queues without schema validation.
+3. **Sanitize before rendering.** Output encoding is required for any user-controlled data rendered in a UI.
+4. **Authentication before authorization.** Never implement authorization logic without confirming the authentication layer is correct.
+5. **Least privilege.** Database roles, IAM policies, and service accounts must request only the permissions they need.
+6. **Dependency audit.** Before adding a dependency, check for known CVEs. After adding an external service or SDK, document it in `CONVENTIONS.md` → Integrations.
+7. **Security gate on:** any change to authentication, session management, data access, payment flows, or external integrations.
+8. **Never log sensitive data.** Passwords, tokens, PII, and financial data must never appear in logs.
+
+---
+
+### Quality Rules
+
+1. **No dead code in production.** Remove commented-out code, unused imports, and orphaned functions before committing.
+2. **No magic values.** Constants must be named and defined centrally.
+3. **Error messages are observable.** Every error must include enough context for debugging without leaking internal structure to end users.
+4. **Tests are not optional.** No logic without a test. If it cannot be tested, document why in `CONVENTIONS.md` → Concerns.
+5. **Dependencies must be justified.** Adding a library requires updating `CONVENTIONS.md` → Technical Context with the reason.
+6. **Breaking changes are flagged.** Any change to a public API, data contract, or shared module must be flagged before implementation.
+7. **No overengineering.** Three similar lines is better than a premature abstraction. Optimize when the need is real, not hypothetical.
+8. **Documentation stays alive.** `.specs/` files must be updated when the code they describe changes. Stale specs are worse than no specs.
+
+---
+
+### AI-Specific Quality Rules
+
+1. **Never invent.** If an API, function, or file's existence is uncertain, read the source before assuming it exists.
+2. **No silent scope creep.** Implement exactly what the task specifies. Record anything discovered out-of-scope in STATE.md for a future task.
+3. **No silent decisions.** Every choice between two implementation approaches must be recorded as a DEC-XXX entry.
+4. **No fabricated validation.** Gate checks must actually be run. Do not write "tests pass" without running them.
+5. **Context revalidation.** When resuming after a session break, re-read STATE.md before taking any action.
+
+---
+
+## 16. Practical Feature Example
+
+### Feature: "User Email Notifications"
+
+This example demonstrates the full SDD workflow for a medium-complexity feature.
+
+---
+
+#### Step 1: Specify
+
+**File:** `.specs/features/email-notifications/spec.md`
+
+```markdown
+# Email Notifications — Specification
+
+**Feature ID:** FEAT-003
+**Created:** 2026-06-25
+**Status:** Approved
+
+## Overview
+Allow users to receive email notifications when their order status changes.
+
+## Requirements
+
+| ID | Description | Priority |
+|----|-------------|----------|
+| REQ-010 | System sends email when order moves to "shipped" status | Must Have |
+| REQ-011 | System sends email when order moves to "delivered" status | Must Have |
+| REQ-012 | User can opt out of email notifications per order | Should Have |
+| REQ-013 | Emails render correctly on mobile | Should Have |
+
+## Acceptance Criteria
+- [ ] REQ-010: Creating a shipment record triggers a "shipped" email to the order owner
+- [ ] REQ-011: Marking an order delivered triggers a "delivered" email
+- [ ] REQ-012: Users with notifications_enabled=false receive no emails
+- [ ] REQ-013: Email template passes mobile rendering check
+
+## Out of Scope
+- Push notifications
+- SMS notifications
+- Notification preferences beyond per-order opt-out
+```
+
+---
+
+#### Step 2: Add Context
+
+**File:** `.specs/features/email-notifications/context.md`
+
+```markdown
+# Email Notifications — Context
+
+## Background
+Orders currently update status with no user feedback. Users are complaining in
+support tickets. This feature closes the most common support request.
+
+## Related Code
+- `src/services/order.service.ts` — `updateStatus()` is where triggers belong
+- `src/models/order.model.ts` — Order schema, contains user_id and status
+- `src/services/user.service.ts` — `findById()` returns user email
+
+## Prior Decisions
+- DEC-005: We use SendGrid for transactional email (see `CONVENTIONS.md` → Integrations)
+- DEC-006: Email templates are stored in `src/templates/email/`
+
+## Patterns to Follow
+- See `src/services/payment.service.ts` for how async side effects are triggered
+- See `src/templates/email/receipt.html` for template structure
+
+## Known Risks
+- RISK-007: SendGrid rate limit is 100/min on free tier — may be hit under load
+```
+
+---
+
+#### Step 3: Design (brief, medium feature)
+
+**File:** `.specs/features/email-notifications/design.md`
+
+```markdown
+# Email Notifications — Design
+
+## Approach
+Add a notification trigger inside `order.service.ts` `updateStatus()`.
+Use the existing SendGrid integration documented in `CONVENTIONS.md` → Integrations.
+
+## Components
+
+### EmailNotificationService
+`src/services/email-notification.service.ts`
+- `sendShippedEmail(orderId: string): Promise<void>`
+- `sendDeliveredEmail(orderId: string): Promise<void>`
+- Reads order and user from DB, checks opt-out flag, sends via SendGrid
+
+### Email Templates
+- `src/templates/email/order-shipped.html`
+- `src/templates/email/order-delivered.html`
+
+## Decision
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| DEC-012 | Trigger synchronously in updateStatus() | Low volume; async queue not justified yet |
+| DEC-013 | Reuse existing SendGrid service class | Consistency; no new dependency |
+```
+
+---
+
+#### Step 4: Tasks
+
+**File:** `.specs/features/email-notifications/tasks.md`
+
+```markdown
+# Email Notifications — Tasks
+
+## TASK-020 — Create EmailNotificationService [P]
+
+**Satisfies:** REQ-010, REQ-011, REQ-012
+**Files:** `src/services/email-notification.service.ts`, `src/services/__tests__/email-notification.service.spec.ts`
+**Dependencies:** None
+
+**Steps:**
+1. Create service file at `src/services/email-notification.service.ts`
+2. Implement `sendShippedEmail` and `sendDeliveredEmail`
+3. Check `notifications_enabled` flag before sending
+4. Write unit tests with mocked SendGrid
+
+**Acceptance Criteria:**
+- [ ] sendShippedEmail calls SendGrid with correct template and recipient
+- [ ] sendDeliveredEmail calls SendGrid with correct template and recipient
+- [ ] No email sent when notifications_enabled is false
+
+**Status:** TODO
+
+---
+
+## TASK-021 — Create Email Templates [P]
+
+**Satisfies:** REQ-010, REQ-011, REQ-013
+**Files:** `src/templates/email/order-shipped.html`, `src/templates/email/order-delivered.html`
+**Dependencies:** None
+
+**Steps:**
+1. Copy structure from `src/templates/email/receipt.html`
+2. Create shipped template with order details
+3. Create delivered template with order details
+4. Use responsive table layout for mobile compatibility
+
+**Acceptance Criteria:**
+- [ ] Templates render with correct order data
+- [ ] Templates pass basic mobile breakpoint check
+
+**Status:** TODO
+
+---
+
+## TASK-022 — Wire Triggers in OrderService
+
+**Satisfies:** REQ-010, REQ-011
+**Files:** `src/services/order.service.ts`, `src/services/__tests__/order.service.spec.ts`
+**Dependencies:** TASK-020
+
+**Steps:**
+1. Import EmailNotificationService into order.service.ts
+2. Call sendShippedEmail when status changes to "shipped"
+3. Call sendDeliveredEmail when status changes to "delivered"
+4. Update order.service tests to verify trigger calls
+
+**Acceptance Criteria:**
+- [ ] Status change to "shipped" calls sendShippedEmail
+- [ ] Status change to "delivered" calls sendDeliveredEmail
+- [ ] No email triggered for other status changes
+
+**Status:** TODO
+```
+
+---
+
+#### Step 5: Execute
+
+Agent runs TASK-020 and TASK-021 in parallel (they are marked `[P]` and touch disjoint files), then TASK-022 sequentially.
+
+---
+
+#### Step 6: Validate
+
+```
+TASK-022 Validation Evidence:
+- Build: PASS
+- Lint: PASS
+- Typecheck: PASS
+- Unit tests: PASS (41/41)
+- Acceptance REQ-010: PASS — shipped trigger confirmed in test
+- Acceptance REQ-011: PASS — delivered trigger confirmed in test
+- Acceptance REQ-012: PASS — opt-out flag blocks send confirmed in test
+- Regression: PASS — order.service existing tests unchanged
+```
+
+---
+
+#### Step 7: Record State
+
+**Update to `STATE.md`:**
+
+```markdown
+## Session Log
+| 2026-06-25 | Implemented FEAT-003 email notifications | TASK-020, TASK-021, TASK-022 | DEC-012, DEC-013 |
+
+## Last Task Completed
+TASK-022 — Wire email notification triggers in OrderService
+
+## Suggested Next Steps
+1. TASK-023 (if created): Manual QA of email rendering on mobile
+2. Monitor RISK-007 (SendGrid rate limit) after deploy
+
+## Decisions Log
+| DEC-012 | 2026-06-25 | Trigger synchronously in updateStatus() | Low volume; queue not justified | order.service.ts |
+| DEC-013 | 2026-06-25 | Reuse existing SendGrid service | Consistency | email-notification.service.ts |
+```
+
+---
+
+## 17. Tool-Specific Guidance
+
+### General Principle
+
+The `.specs/` structure is tool-independent. It works as a plain text contract that any agent can read. The adaptations below are operational tips — not requirements.
+
+---
+
+### Claude Code
+
+**Strengths:** Long context window, multi-file edits, built-in tool use for running tests and reading files.
+
+**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`
+4. Use Claude Code's task system to track TASK-XXX progress
+5. Use `Bash` tool to run validation gates and capture evidence
+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.
+
+Always start a session by reading `.specs/project/STATE.md`.
+All work follows the AI Development Harness in `SDD.md` Section 7.
+```
+
+---
+
+### OpenAI Codex / ChatGPT with Code Interpreter
+
+**Strengths:** Strong reasoning, good at spec analysis and plan generation.
+
+**Usage pattern:**
+1. Paste the content of `STATE.md`, `spec.md`, and `context.md` at the start of the prompt
+2. Request one task at a time — Codex works best with focused, bounded scope
+3. Ask Codex to return output in the sub-agent report format (Section 8)
+4. Manually apply changes and run gates — Codex does not run tests natively in all modes
+
+**Limitation:** Cannot read files directly. Must paste context. Keep pasted context under 8k tokens.
+
+---
+
+### Cursor
+
+**Strengths:** IDE integration, inline suggestions, `@` file references, `.cursorrules` support.
+
+**Usage pattern:**
+1. Add `.cursorrules` pointing to key spec files:
+   ```
+   Always read .specs/project/STATE.md before suggesting changes.
+   Follow conventions in .specs/codebase/CONVENTIONS.md.
+   Reference the current feature spec before generating code.
+   ```
+2. Use `@file` references in prompts: `@.specs/features/email-notifications/spec.md`
+3. Use Cursor's Composer for multi-file tasks (TASK-XXX scope)
+4. After Composer runs, manually update `tasks.md` and `STATE.md`
+
+**Limitation:** Does not natively run tests. Use terminal to run validation gates.
+
+---
+
+### GitHub Copilot
+
+**Strengths:** Autocomplete, inline suggestions, Copilot Chat for bounded Q&A.
+
+**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`
+4. Manually validate and update `tasks.md` — Copilot does not maintain state
+
+**Limitation:** No persistent memory. Must re-establish context per chat session.
+
+---
+
+### CLI Agents (LangChain, AutoGPT, custom harnesses)
+
+**Strengths:** Automation, multi-step execution, tool use, scriptable.
+
+**Usage pattern:**
+1. At agent startup, inject: `STATE.md`, `PROJECT.md`, `CONVENTIONS.md`
+2. Pass the current `tasks.md` as the work queue
+3. Configure the agent to output sub-agent reports (Section 8 format)
+4. Use file write tools to update `tasks.md` status fields after each task
+5. Use file write tools to append to `STATE.md` session log at end of run
+
+**Key configuration:**
+```yaml
+context_files:
+  - .specs/project/STATE.md
+  - .specs/project/PROJECT.md
+  - .specs/codebase/CONVENTIONS.md
+
+task_source: .specs/features/[name]/tasks.md
+
+on_task_complete:
+  - update: tasks.md (set status=DONE, add evidence)
+  - append: STATE.md (session log entry)
+
+output_format: sub-agent-report
+```
+
+---
+
+### Specialized Sub-Agents
+
+When delegating to specialized sub-agents (security reviewer, test writer, architecture validator), provide:
+
+1. The sub-agent's specific spec section — not the whole project
+2. The sub-agent report format (Section 8) as the expected output
+3. Explicit scope boundaries: what files to read, what files to write, what not to touch
+
+The orchestrating agent is responsible for integrating the sub-agent's output back into `tasks.md` and `STATE.md`.
+
+---
+
+## Final Recommendations
+
+### 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.
+
+### STATE.md is the most important file
+
+Every agent must read it first and update it last. A well-maintained `STATE.md` means any agent — or any human — can pick up the project in under 5 minutes. A neglected `STATE.md` means the next session starts from zero.
+
+### 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.
+
+### Keep validation evidence
+
+The most common failure mode in AI-assisted development is a task marked DONE that was never actually validated. Recording gate evidence in `tasks.md` makes this impossible to fake and easy to audit.
+
+### Commit atomically
+
+One task, one commit. The commit message references the TASK-XXX. This creates a permanent audit trail between decisions, specs, and code that survives team changes, tool changes, and time.
+
+### Revisit CONVENTIONS.md → Concerns
+
+Technical debt and known risks accumulate silently. The Concerns section in `CONVENTIONS.md` is only useful if it is read before touching risky areas and updated when new concerns are found. Build the habit of reading it at the start of any session involving complex or legacy code.
+
+### This SDD is a living document
+
+Update `SDD.md` itself when the team finds patterns that work better, when tools change, or when new complexity tiers emerge. The methodology should evolve with the project — not constrain it.
+
+---
+
+*SDD v1.0.0 — Built on the TLC Spec Driven Development model.*  
+*Tool-independent. Complexity-adaptive. AI-native.*