About
About the library
What a specification is here, how the library is organised, and how to read a specification page.
Every repository in the organisation shares a shape: the same areas, the same
command surface, the same lifecycle hooks, the same way of delivering what it
builds. Most of that shape is written down in standard files copied into every
repository — owner README.md files, make modules, and runner scripts.
This library gives each of those recurring ideas a page of its own. A specification describes how something behaves and how it relates to everything around it. It is a reference to understand and build on, not a checklist to pass.
What counts as a specification#
A specification is any concept that recurs: an area of a repository, a way of sequencing work, a promise a component makes to its callers, a set of lifecycle phases, or a convention for writing something down. Each one has exactly one kind, which says which question it answers.
- 01 Architecture Where does it live, and how do the parts fit?
- 02 Orchestration How is the work sequenced and composed?
- 03 Contract What does it promise?
- 04 Lifecycle What happens, and when?
- 05 Convention How is it written down?
Each specification also belongs to one domain — the area of the repository it concerns, following the groupings of the repository code map — and carries any number of traits, the behavioural qualities it shares with other specifications, such as idempotent, offline-safe, or composable.
Reading a specification page#
- Plate and title The specification's glyph, kind, and one-sentence summary
- Facts strip Kind, domain, where it applies, status, and its source file
- Anatomy What it defines, when it applies, and where it stops
- Expected behaviour The behaviour it describes, as numbered statements
- Body How it behaves: flows, lifecycles, layouts, and examples
- Connections A neighbourhood diagram and every related specification
The source of a specification is the file in the repository that the specification describes. When that file is a managed standard, the page says so: change it where it is managed, and the library follows.
Relationships#
Specifications link to each other with five typed relationships. Authors write one direction; the library derives the other, so every link appears on both pages.
| Relationship | Read as | Inverse |
|---|---|---|
| Refines | A narrower specification of a broader one | Refined by |
| Composes | Built out of the other specification | Composed into |
| Relies on | Depends on the other’s behaviour | Relied on by |
| Followed by | Comes earlier in a sequence or lifecycle | Preceded by |
| Contrasts with | A neighbour with a deliberately different boundary | Contrasts with |
The atlas draws all of them at once.