ADR-033: ADR Frontmatter Schema

Every ADR in this repository uses a standardized YAML frontmatter block so LLM agents can programmatically discover which ADRs apply to their current task.

Required fields

---
adr: 085                  # ADR number (e.g., 001–083 for design system, 059+ for infrastructure)
status: accepted          # accepted | proposed | draft | deprecated
last_verified: 2026-05-24 # ISO date — when a human last confirmed accuracy
applies_when: "..."        # Plain-English trigger — when should an agent read this?
tags: [tag1, tag2]         # Cluster tags from the canonical list below
---

adr

The ADR number (e.g., 085, 061, 027). This enables programmatic discovery and validation — agents can extract the number, compare it against the filename, and flag mismatches. Always use the zero-padded form without the ADR- prefix (just the digits).

status

Value	Meaning
accepted	Active policy — agents must follow it
proposed	Under review — agents should be aware but not treat as binding
draft	Incomplete — use for directional context only
deprecated	Superseded — agents should ignore unless doing historical research

last_verified

ISO 8601 date (YYYY-MM-DD). Updated when a human reviews the ADR and confirms it still reflects current practice. Agents can use this to gauge staleness.

applies_when

A plain-English sentence describing the task conditions that trigger this ADR. Write it as if completing the sentence “Read this ADR when you are…”. Be specific enough that an agent doing keyword matching can find it.

Good: "Adding, moving, or renaming stories; modifying the Storybook sidebar order"
Bad: "Storybook work" (too vague — matches everything)

tags

An array of canonical cluster tags. Tags let agents pull all related ADRs at once — e.g., rg -l 'tags:.*storybook' docs/adr-*.mdx finds every Storybook-related ADR.

Canonical tag list

Tag	Cluster	Example ADRs
accessibility	WCAG, a11y testing, screen readers	014
api	HTTP API design, webhooks, integration	051, 065
auth	Authentication, JWT, sessions	064
component-architecture	Building, structuring, extending components	002, 004, 010, 012, 025, 032
design-tokens	Color, spacing, typography, radius tokens	001, 003, 006, 008, 009, 015, 018
devops	CI/CD, Helm, ArgoCD, containers, GitHub Actions	068–074
engineering	Code standards, naming, commits, logging	010, 059, 060, 071
forms	Form widgets, inputs, validation, input groups	021, 035, 080 (url)
legal	Legal documents, court filings, Virginia law	023–028, 037, 038
llm	LLM agent workflow, prompts, token usage	076, 078
mdx	MDX authoring, remark/rehype pipelines	026, 037, 075
motion	Animation, transitions, reduced-motion	013, 031
navigation	Nav patterns, URL state, routing	007, 022, 080 (url)
observability	Logging, wide events, telemetry	059
overlays	Popovers, tooltips, dropdowns, z-index	020, 030
print	Print output, PDF generation, paged.js	019, 079
secrets	Secrets management, 1Password, credentials	063, 072
storybook	Stories, sidebar, docs, preview, tags	005, 011, 016, 033, 034, 036, 039, 075–077, 080 (sidebar)
testing	Test coverage, gates, release criteria	014
vendor	Vendor strategy, provider pattern, templates	051, 065–067
visual	Colors, borders, surfaces, icons, typography	001, 003, 006, 008, 009, 015, 017, 018, 020, 029, 030, 079

Adding a new tag

Only add a tag when three or more ADRs would share it. Update this table via PR. Single-use tags create noise — use applies_when text for specificity instead.

How agents use this schema

Find ADRs for a task

# All storybook-related ADRs
rg -l 'tags:.*storybook' docs/adr-*.mdx

# All ADRs about legal documents
rg -l 'tags:.*legal' docs/adr-*.mdx

# ADRs matching a keyword in applies_when
rg -l 'applies_when:.*motion' docs/adr-*.mdx

Task-based routing (see CLAUDE.md)

CLAUDE.md contains a routing table that maps common tasks to tag clusters. Agents should check the routing table first, then fall back to rg searches for edge cases.

Creating a new ADR

1. Pick the next available number in the appropriate range (001–038 for design system, 059+ for engineering/infrastructure).

2. Add all five frontmatter fields. Copy the YAML block above as a starting template. Include the adr field first with the ADR number (e.g., adr: 085).

3. Choose 1–3 tags from the canonical list. If none fit, check whether a new tag is warranted (3+ ADR threshold).

4. Write applies_when as a specific trigger sentence, not a vague category label.

5. Run pnpm run adrs and pnpm run docs:index so the Storybook ADR overview and docs/adrs/docs-index.json pick up the new record.

6. Important: Add the ADR number to the Storybook Meta title so it’s searchable by number. Format:

   <Meta parameters={{ layout: "fullscreen" }} />

   Examples:

   • ✅ <Meta ... />
   • ✅ <Meta ... />
   • ❌ <Meta ... /> (missing ADR number — not searchable)

   This ensures users and agents can search for ADRs by number (e.g., searching “061” finds ADR-061 in Storybook).