Docs are split by the question they answer (frostyard/core's four-category shape, core ADR-0025):
| Directory | Question | Contents |
|---|---|---|
| adr/ | Why did we choose this? | Repo-local Architecture Decision Records — immutable once accepted; superseded, never edited. Org-wide decisions live in frostyard/core — see org-adrs.md |
| 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 |
(none yet — org-wide decisions binding this repo are listed in org-adrs.md)
- Overview — purpose, architecture, key patterns, configuration, downstream consumers (the entry-point doc)
- Reporter package — the
Reporterinterface,ProgressEventJSON Lines format, and exact per-implementation output formatting
Shipped work; kept for the decision context they carry:
- clix design and clix implementation — the CLI convenience module built on this package, shipped as frostyard/clix
- Reporter extraction design
and implementation plan —
extracting
reporterfrom nbc into this module - Reporter examples design
and implementation plan — the
_examples/programs
- 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 NNNNrather than editing it. Decisions that bind more than this repo become ADRs in frostyard/core plus a line in org-adrs.md. - 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.
- Adding a doc means adding it to the index above.