architecture-awarenesslisted

# Architecture Awareness Architecture knowledge lives in two artifact types that complement specs: ``` SPEC (WHAT) / \ / \ ADR (HOW+WHY) -- C4 (CONTEXT MAP) ``` - **Specs** describe WHAT the system does (capabilities, acceptance criteria) - **ADRs** describe HOW the system is built and WHY those technical choices were made - **C4 Diagrams** provide the CONTEXT MAP — how everything relates structurally All three are persistent, first-class artifacts. Backlog items are transient; these are not. ## ADR Organization Architecture Decision Records capture significant technical decisions using the Michael Nygard pattern. ### Directory Structure ``` docs/decisions/ ADR-000-use-adrs-for-architecture-decisions.md # bootstrapping record ADR-001-{slug}.md ADR-002-{slug}.md ``` Flat directory. No subdirectories. The `domain` field in frontmatter provides domain association. ### Frontmatter Schema > Schema: `schemas/adr.schema.md` v1.0 Required: `adr_version`, `type: adr`, `id` (ADR-NNN), `title`, `status`, `created`, `deciders` Optional: `domain`, `spec_refs`, `backlog_ref`, `superseded_by`, `supersedes`, `tags` ### ADR Lifecycle ``` /define (proposed) → /design (accepted) → [lives indefinitely] → /design (superseded by new ADR) → /design (deprecated if no longer relevant) ``` - **proposed** — Created by `/define` when a behavioral delta involves an arch