README.md

Documentation

Docs are split by the question they answer:

Directory	Question	Contents
adr/	Why did we choose this?	Architecture Decision Records — immutable once accepted; superseded, never edited
design/	How does it fit together?	Living documents describing the current architecture
specs/	What exactly is the contract?	Precise, testable interface definitions
plans/	When/in what order do we build?	Roadmaps and phase plans; updated as work lands

Index

Decisions (ADRs)

• 0001 — Record architecture decisions
• 0002 — Agent-portable instruction surface
• 0003 — Digest-based conditional rebuild scheduling
• 0004 — Gate PR builds on lint and changed paths

Design

• Build scheduling

Specs

(none yet)

Plans

(none yet)

Conventions

• New docs start from their category's TEMPLATE.md (in each directory).
• New decision → new ADR with the next number; if it reverses an old one, mark the old one Superseded by NNNN rather than editing it.
• Design docs are updated in place to always reflect reality.
• Specs change only alongside the code that implements them.
• Cross-links between categories are mandatory in both directions — see the documentation rules in AGENTS.md (CLAUDE.md/GEMINI.md are symlinks to it, ADR-0002).
• Adding a doc means adding it to the index above.