Architecture decision records

An architecture decision record (ADR) is one short file about one decision. It says what the options were, what Cyclix chose, and what follows from the choice. Read one when you want to reopen a decision: it holds the reasons that were weighed.

Files are named NNNN-kebab-title.md, numbered from 0000. _template.md is the shape of a record. Its name starts with an underscore, so the site leaves it out. A decision gets a record when it chose between options that a contributor might reasonably reopen. A decision with nothing reasonable against it keeps its reason in the design text.

A record is not edited to change a decision. A new record replaces it, and the old one’s status becomes Superseded by ADR-NNNN.

ADR	Decision	Status
0000	Guiding principles	Accepted
0001	Cyclix merges a PR only after a person approves it or a written rule allows it	Accepted
0002	Each kind of data has one owner	Accepted
0003	Write one wide event per stage run, in OpenTelemetry shape, as local JSON lines	Accepted
0004	Use only the standard library unless a dependency has a written reason	Accepted
0005	Confine the agent and the gate	Accepted
0006	Build the docs site with Astro and Starlight	Accepted, deploy replaced by 0007
0007	Deploy the docs site through the host’s Git integration	Accepted
0008	Offer shell completion through an optional argcomplete extra	Accepted