Skip to content
Documentation

adr

FieldValue
TypeSkill
Source~/.copilot/skills/adr/SKILL.md
DescriptionThe architecture-decision-record system — the single source of truth for binding design, engineering, and platform decisions across projects. Use when writing a new ADR, changing or superseding an existing decision, deprecating one, citing a decision in code review or an agent, or answering “what is our rule for X”. Active records live in references/, tombstoned ones in references/ZZ-deprecated/, and the template in templates/adr-template.md. Storybook and the design-principles skill reference these records; they are not the source. Do NOT use for general prose (technical-writing), product specs (prd-generator), or enforcing visual rules at code time (design-principles cites these records).

Bundled Pages

GroupNameSource
ReferencesADR Index~/.copilot/skills/adr/references/index.md
ReferencesADR-001: Design Tokens~/.copilot/skills/adr/references/adr-001-design-tokens.md
ReferencesADR-002: Radius & Shape~/.copilot/skills/adr/references/adr-002-radius-and-shape.md
ReferencesADR-003: Typography & Density~/.copilot/skills/adr/references/adr-003-typography-and-density.md
ReferencesADR-004: Motion & Interaction~/.copilot/skills/adr/references/adr-004-motion-and-interaction.md
ReferencesADR-005: Accessibility & Release Gates~/.copilot/skills/adr/references/adr-005-accessibility-and-release-gates.md
ReferencesADR-006: Color & Theming~/.copilot/skills/adr/references/adr-006-color-and-theming.md
ReferencesADR-007: Print Discipline~/.copilot/skills/adr/references/adr-007-print-discipline.md
ReferencesADR-008: Border, Surface, and Overlay Discipline~/.copilot/skills/adr/references/adr-008-border-surface-and-overlay-discipline.md
ReferencesADR-009: Icon Role, Placement, and Layout~/.copilot/skills/adr/references/adr-009-icon-role-placement-and-layout.md
ReferencesADR-010: Component Architecture & Catalog~/.copilot/skills/adr/references/adr-010-component-architecture-and-catalog.md
ReferencesADR-011: Variants & Composition~/.copilot/skills/adr/references/adr-011-variants-and-composition.md
ReferencesADR-012: Input & Control Sizing~/.copilot/skills/adr/references/adr-012-input-control-sizing.md
ReferencesADR-013: Locale & Number Formatting~/.copilot/skills/adr/references/adr-013-locale-and-number-formatting.md
ReferencesADR-014: Build, Buy, or Wrap~/.copilot/skills/adr/references/adr-014-build-buy-or-wrap.md
ReferencesADR-015: Interaction Contracts~/.copilot/skills/adr/references/adr-015-interaction-contracts.md
ReferencesADR-016: Storybook IA & Navigation~/.copilot/skills/adr/references/adr-016-storybook-ia-and-navigation.md
ReferencesADR-017: Documentation Truthfulness~/.copilot/skills/adr/references/adr-017-documentation-truthfulness.md
ReferencesADR-018: Docs Authoring Format~/.copilot/skills/adr/references/adr-018-docs-authoring-format.md
ReferencesADR-019: Draft & Deprecation State~/.copilot/skills/adr/references/adr-019-draft-and-deprecation-state.md
ReferencesADR-020: Docs Folder Convention & IA~/.copilot/skills/adr/references/adr-020-docs-folder-convention-and-ia.md
ReferencesADR-021: Self-Documenting Code Examples~/.copilot/skills/adr/references/adr-021-code-examples-and-llm-prompts.md
ReferencesADR-022: Mermaid Diagram Selection~/.copilot/skills/adr/references/adr-022-mermaid-diagram-selection.md
ReferencesADR-023: Observability & Wide-Events Logging~/.copilot/skills/adr/references/adr-023-observability-and-wide-events-logging.md
ReferencesADR-024: Engineering Standards~/.copilot/skills/adr/references/adr-024-engineering-standards.md
ReferencesADR-025: Identity, Auth & Secrets~/.copilot/skills/adr/references/adr-025-identity-auth-and-secrets.md
ReferencesADR-026: LLM Agent Workflow & Token Discipline~/.copilot/skills/adr/references/adr-026-llm-agent-workflow-and-token-discipline.md
ReferencesADR-027: Default Tech Stack~/.copilot/skills/adr/references/adr-027-default-tech-stack.md
ReferencesADR-028: Platform Foundations~/.copilot/skills/adr/references/adr-028-platform-foundations.md
ReferencesADR-029: Multi-Tenancy by Default~/.copilot/skills/adr/references/adr-029-multi-tenancy-by-default.md
ReferencesADR-030: Legal Document Architecture~/.copilot/skills/adr/references/adr-030-legal-document-architecture.md
ReferencesADR-031: Legal Drafting & Court Conventions~/.copilot/skills/adr/references/adr-031-legal-drafting-and-court-conventions.md
ReferencesADR-032: Legal Output & PDF Workflow~/.copilot/skills/adr/references/adr-032-legal-output-and-pdf-workflow.md
ScriptsCheck_adr~/.copilot/skills/adr/scripts/check_adr.py
ScriptsCheck_index~/.copilot/skills/adr/scripts/check_index.py
TemplatesADR-NNN: {{Decision as a noun phrase}}~/.copilot/skills/adr/templates/adr-template.md

Source Content

ADR — Architecture Decision Records

DomainThe decision-record system: authoring, numbering, lifecycle, index
RoleKeeper of binding decisions
ScopeOne record per decision; consolidation; deprecation; the index
OutputAn ADR file under references/ in the house template, plus an updated index

Triggers: “write an ADR”, “record this decision”, “supersede ADR-NNN”, “deprecate an ADR”, “what’s our rule for”, “is there an ADR about”, “ADR index”.

An ADR captures one decision and the reasoning behind it, so the next person or agent inherits the why, not just the rule. This skill owns the system; the decisions live in references/.

Use me for

  • Writing a new decision record.
  • Consolidating overlapping records into one canonical record.
  • Superseding or deprecating a decision (move it to ZZ-deprecated/ with a tombstone).
  • Finding the record that governs a question.

Don’t use me for

  • General prose, guides, tutorials → technical-writing.
  • Product requirements → prd-generator.
  • Enforcing the visual rules at code time → design-principles (it cites these records).

What an ADR is

One decision per record. A record is immutable once accepted — a changed mind is a new record that supersedes the old one, never an edit that erases history. A number is assigned once and kept stable, so code and agents can cite ADR-008 forever.

Record shape

Copy templates/adr-template.md. The frontmatter carries id, status, collection, supersedes, sources, and tags; the title is the H1, not a duplicated frontmatter field. The body runs Decision → Key rules → (Code patterns) → Why → Applies when → Related.

Collections

Records are grouped, not renumbered, into five collections: Design Foundations, Component System, Storybook & Docs, Engineering & Platform, and Legal Domain. The index lists each.

Lifecycle

StageWhat happens
ProposedDrafted, status: proposed, open for discussion
Acceptedstatus: accepted — binding; agents may cite it
SupersededA newer record replaces it; the old one gets superseded_by: and moves to ZZ-deprecated/
DeprecatedNo longer applies; tombstoned in ZZ-deprecated/ with the reason

Consolidation keeps the most-cited number (usually the hard-rule one) as canonical and folds the others in via supersedes:; the folded numbers become tombstones.

How I work

  1. Check the index for an existing record before writing a new one.
  2. One decision. If the draft holds two decisions, it is two records.
  3. Copy the template. Fill the frontmatter and body; cite sources in Why.
  4. Number it. A new decision takes the next free number. A consolidation keeps the most-cited number and lists the rest in supersedes.
  5. Tombstone the old. Move superseded records to ZZ-deprecated/ with superseded_by.
  6. Update the index and run the technical-writing Markdown linter.

The short guide: read, use, author

  • Read: start at references/index.md; open only the record(s) for your task.
  • Use: the Decision and Key rules are binding; cite the record by number.
  • Author: copy the template, keep it to one decision, cite sources, update the index, lint to exit 0.

When I’m unsure, I ask

  • “Is this a new decision, or does it change an existing one — which means superseding it?”
  • “Which collection does this belong to?”
  • “What’s the source — a standard, a benchmark, or an internal convention?”

Elicitation tool order: see STANDARDS.md §6.

Self-rubric

  • One decision per record.
  • Frontmatter complete; sources cited where an external standard applies.
  • Number stable; superseded records tombstoned, not deleted.
  • Index updated; technical-writing Markdown linter exits 0.
  • scripts/check_adr.py <file> exits 0.
  • scripts/check_index.py exits 0 — no orphaned ADRs, no broken index links, supersedes/superseded_by reciprocal.

References

  • templates/adr-template.md — the canonical record shape.
  • references/index.md — the routing map of all active records.
  • references/ZZ-deprecated/ — superseded and deprecated records (tombstones).
  • scripts/check_adr.py <adr-file.md> — validates frontmatter status, the five required sections (Decision/Key rules/Why/Applies when/Related), no unfilled {{...}} placeholders, and that a superseded record actually lives under references/ZZ-deprecated/.
  • scripts/check_index.py [skill-dir] — diffs every ADR’s frontmatter id against references/index.md, failing on orphans (a record not indexed) or broken index links (an entry pointing at a file that doesn’t exist). Also checks supersedes/superseded_by frontmatter is reciprocal between the two records it names. Run after adding, superseding, or deprecating any record.