speclisted

# Spec System Every project's design lives in `.spec/`. Single source of truth for what you're building, why, and how. Read specs before writing code. Update specs when decisions change. ## Why Specs Exist - **Persistent memory** — decisions survive across sessions - **Separation of concerns** — product thinking stays separate from implementation thinking - **Progressive disclosure** — load only what you need, when you need it - **Shared language** — consistent vocabulary between product and tech ## The Two-Layer Model Specs come in two layers. Use the right one for the job — mixing them is the most common mistake. ``` .spec/ │ │ ─── ROOT LAYER (high-level, persistent) ────────────── │ ├── product.md # mini PRD — story, requirements, principles ├── tech.md # architecture summary — stack, principles, basic implementation ├── design.md # cross-cutting product/UX design language ├── plan.md # implementation roadmap ├── lessons.md # accumulated mistakes, read at session start ├── product-{topic}.md # cross-cutting product branch (design system, conventions) ├── tech-{topic}.md # cross-cutting tech branch (infrastructure, observability) │ │ ─── FEATURE LAYER (detailed, ephemeral) ────────────── │ ├── features/<name>/ │ ├── product.md # what this feature does (requirements) │ ├── tech.md # how this feature is built (architecture) │ ├── design.md