ADR-000 — ADR Conventions

Status

Accepted

Context

This repository captures design decisions as Architecture Decision Records. ADR-000 is the meta-ADR: it fixes the format, status lifecycle, file naming, and index rules every other ADR follows. Copy block: [[template]].

Decision

Format — pure Nygard. Four mandatory sections, in order: Status, Context, Decision, Consequences. No other top-level section, except ## Sub-decisions when the ADR has sub-letters. Frontmatter is metadata, not a section. Each decision is a bold-header paragraph; tables, code, and lists are supporting detail under one.

Status lifecycle.

Value	Meaning
`Draft`	Under discussion — editable
`Accepted`	Decided — substance is immutable
`Deprecated`	No longer applies, no replacement
`Superseded by ADR-NNN`	Replaced — names the successor

Immutability protects the decision, not the wording. Once Accepted, the decision is frozen: to change what was decided, write a new ADR and mark this one Superseded by ADR-NNN. Editorial maintenance that does not alter the decision — tightening prose, fixing links, adding frontmatter, adapting to Obsidian — is always permitted.

[!warning] To change an Accepted decision, write a new ADR Never rewrite a decision in place. Supersede it.

File naming. adr-NNN[-subletter]-slug-in-kebab-case.md. NNN is a stable three-digit topic id (not a priority ranking). Sub-letters a, b, c… group sub-decisions within one topic. The slug is the English title in kebab-case.

Index. Every ADR is registered in the [[adr/README|ADR index]] at creation, even while Draft.

Sub-decisions hub. An ADR that heads a sub-lettered series adds a ## Sub-decisions section listing each child with a one-line summary, so a reader of the parent knows what the children cover without opening them. The child sets parent to the hub.

Sub-decisions

ADR-000 also heads the project-conventions series (the children carry parent: "[[adr-000]]"):

[[adr-001-a-naming-glossary|ADR-001-a]] — Naming Conventions and Domain Glossary: the single canonical English name for every domain concept.
[[adr-001-b-language-conventions|ADR-001-b]] — Language Conventions: English for code, Spanish only in display strings.
[[adr-001-c-hour-color-vocabulary|ADR-001-c]] — Hour Color Vocabulary: the five color terms and their coexistence rules.

Consequences

The [[adr/README|ADR index]] is the complete, status-annotated map of decisions for any reader, human or AI.
Draft ADRs are editable in substance; Accepted ones change only by supersession (the decision) or non-substantive editorial passes (clarity, links, frontmatter).
Parent ADRs with sub-letters act as navigation hubs; their ## Sub-decisions section keeps children discoverable.