adr-ops

ADR Ops

An Architecture Decision Record (ADR) captures one architectural decision: what was decided, why, what was rejected, and what it costs. ADRs are append-only project memory — they exist so a future maintainer touching a subsystem can recover the reasoning behind its shape without archaeology through git history or chat logs.

This skill encapsulates a battle-tested ADR protocol and generalizes it to any repo. The default location is docs/adr/, but every script takes --dir so a repo can keep records anywhere (docs/decisions/, architecture/adr/, …).

---

When to write an ADR

Write one when a change has any of these properties:

• It constrains future options — a boundary, an invariant, a "we will always / never do X" rule that later work must respect.
• Multiple alternatives were seriously evaluated and the choice is not obvious in hindsight.
• The rationale is non-obvious from the code — the code shows what, the ADR preserves why.

Write one decision per ADR. If a change bundles two separable decisions, write two.

When NOT to write one

• A bug fix, refactor, or feature that follows existing architecture without changing it — that is a commit message.
• A reversible, low-stakes choice — that is a code comment.
• A point-in-time event with no forward constraint (a benchmark run, an incident write-up) — that is an audit/log entry, not an ADR.

Rule of thumb: if someone could plausibly undo this next month without re-litigating a trade-off, it is not an ADR.

---

Naming, location, numbering

• Path: <adr-dir>/ADR-NNN-slug.md (default <adr-dir> = docs/adr).
• NNN is zero-padded three digits, assigned sequentially: the next number is highest existing + 1. Numbers are never reused, never reordered — a superseded ADR keeps its number forever.
• slug is short kebab-case naming the subject (oauth-only-auth, per-trial-container).
• A protocol/how-to file (e.g. 00_*) sorts above the numbered records and is not part of the sequence.

The directory IS the index

Do not maintain a hand-curated numbered list as the source of truth — it drifts from the filesystem. The authoritative list is the directory itself; adr-index.sh is just a clean parse of it. Any prose list elsewhere (README, AGENTS.md) is a convenience pointer that may lag and must say so.

---

Canonical format (compact view)

Full template in assets/ADR-template.md; full rules in references/canonical-format.md. The shape:

---
status: accepted
date: YYYY-MM-DD
supersedes: []
superseded-by: []
touches:
  - "path/one.py"
---

# ADR-NNN: Title in Title Case

## Decision (one sentence)
<BLUF — one present-tense sentence stating the standing rule; greppable, stands alone.>

## Context
## Alternatives considered
## Consequences
### Positive / ### Negative / ### Non-goals
## See also

Fixed section order: Decision → Context → Alternatives considered → Consequences → See also. Extra sections (Migration path, Enforcement, Implementation summary) go after Consequences. For a multi-part decision, keep the one-sentence BLUF and add a ## Decision (detail) section lower down.

Frontmatter fields

Field	Required	Rule
status	yes	proposed / accepted / superseded / deprecated (lowercase).
date	yes	Decision date, YYYY-MM-DD.
supersedes	yes	YAML list of ADR ids this replaces ([] if none).
superseded-by	yes	YAML list of ADR ids that replace this ([] until superseded).
touches	yes	YAML list of paths / globs / config keys this governs. Quote each. The grep discovery surface — grep touches: answers "is there an ADR about the thing I'm changing?"
extends	optional	ADR ids this builds on without replacing.
related	optional	Companion ADR ids (not parents).
deciders	optional	Who made the call.

A new field is a protocol change — record it in a new ADR, don't invent per-record keys.

---

Status lifecycle & immutability

proposed ──► accepted ──► superseded   (superseded-by: [ADR-NNN])
                │
                └────────► deprecated  (withdrawn; nothing replaces it)

ADRs are append-only. Once accepted, you do not rewrite the Decision or Context. Three change modes (full detail in references/lifecycle-and-supersession.md):

1. Supersede — the rule itself changes. Write a new ADR with supersedes: [ADR-OLD]; flip the old record's frontmatter to status: superseded + superseded-by: [ADR-NEW] in the same commit. Body stays intact (obsolete reasoning is itself a record). Supersession is bidirectional — a one-sided link is a lint error.
2. Addendum — new facts that refine an in-force decision. A dated ## Addendum — YYYY-MM-DD: <topic> at the end of the body. Never use it to quietly reverse the decision.
3. In-place edit — typos, dead links, a renamed path in touches:. Preserves meaning; never rewrites rationale.

---

End-to-end workflow

1. Scaffold the next record: bash scripts/adr-new.sh --dir docs/adr --title "Your decision title" (computes NNN = highest+1, derives the slug, fills frontmatter).
2. Fill it in — BLUF first, then Context, Alternatives, Consequences, See also. Keep touches: accurate; it is the discovery surface.
3. Cross-check the number against the directory to avoid a collision with a parallel session: ls docs/adr/ADR-*.md (or bash scripts/adr-index.sh).
4. If superseding, flip the old record's frontmatter in the same commit — either by hand or with adr-new.sh --supersedes ADR-OLD --apply-supersede.
5. Lint before committing: python scripts/adr-lint.py --dir docs/adr.
6. Commit with a docs(adr): conventional-commit subject, e.g. docs(adr): ADR-020 — <subject>.

Adopting ADRs in a fresh repo? Run bash scripts/adr-init.sh --first-title "…" once to bootstrap the directory + a lint-clean ADR-001. Before changing an existing subsystem, run python scripts/adr-touching.py <path> to surface any decision already governing it.

---

Tools

All scripts take --dir (default docs/adr), --help, and follow semantic exit codes (0 ok, 2 usage, 3 not-found, 5 precondition, 10 findings/domain-signal). Pair with the git-ops skill for the commit/PR step. The three read tools form the legs of a stool: lint = integrity, index = overview, touching = "what governs this file before I change it".

scripts/adr-init.sh — bootstrap a repo adopting ADRs cold

# Create docs/adr/, scaffold a lint-clean ADR-001, write a generated README:
bash scripts/adr-init.sh --first-title "Adopt ADRs"

# Custom dir + preview without writing:
bash scripts/adr-init.sh --dir docs/decisions --first-title "OAuth-only auth" --dry-run

Refuses to run in a directory that already holds ADR-*.md (exit 5) unless --force. The ADR-001 it scaffolds is rendered by adr-new.sh, so it lints clean immediately. The generated <dir>/README.md is self-labeled "generated — do not hand-edit; the directory is the index" and says to run adr-index to regenerate. --dry-run writes nothing.

scripts/adr-new.sh — scaffold the next ADR

# Next number, slug derived from the title, frontmatter pre-filled:
bash scripts/adr-new.sh --title "OAuth-only auth"

# Custom dir + explicit slug + proposed status, preview without writing:
bash scripts/adr-new.sh --dir docs/decisions --title "Per-trial container" \
  --slug per-trial-container --status proposed --dry-run

# Supersede an old record and flip its frontmatter automatically:
bash scripts/adr-new.sh --title "Replace router" --supersedes ADR-002 --apply-supersede

Refuses to overwrite an existing file (exit 5). Atomic write. --dry-run prints the path

• rendered content and writes nothing. --number N forces a specific number (backfilling or coordination) — use sparingly; sequential highest+1 is the discipline.

scripts/adr-index.sh — the directory as a table (read-only)

bash scripts/adr-index.sh                       # number | status | date | title
bash scripts/adr-index.sh --json | jq '.data[] | select(.status=="accepted")'

Prefers yq; degrades to a built-in parser when yq is absent (announced on stderr). Pass --output FILE to write a generated Markdown index (heading + a do not hand-edit marker + the | # | Status | Date | Title | table) atomically to a file instead of stdout — for a README pointer that you regenerate rather than hand-curate.

scripts/adr-touching.py — what governs this file? (the discovery surface)

The touches: frontmatter is the grep target answering "is there an ADR about the thing I'm changing?". This tool is that grep, done properly — match a path, glob, or config key against every ADR's touches: list.

# Before editing src/auth.py, ask what decisions constrain it:
python scripts/adr-touching.py src/auth.py        # exit 10 if an ADR governs it
python scripts/adr-touching.py 'src/**'           # glob query
python scripts/adr-touching.py --json src/ | jq '.data[].number'

Matching is bidirectional and pragmatic: exact equality; fnmatch glob either direction (touches src/** matches query src/auth.py; query src/* matches touches src/auth.py); path-prefix containment (query src/ governs touches src/auth.py, and vice-versa); config keys (file.yaml:key) by exact-or-prefix.

Guard contract (the load-bearing bit): exit 0 = no governing ADR found, exit 10 = at least one ADR governs the query. A pre-edit hook or CI step branches on it — "heads up, ADR-010 governs this path; read it before changing." Exit 3 dir not found, 2 usage.

scripts/adr-lint.py — conformance validator

python scripts/adr-lint.py --dir docs/adr        # exit 0 clean, 10 if findings
python scripts/adr-lint.py --strict --json | jq '.data[] | select(.severity=="error")'

Checks required + well-typed frontmatter, the # ADR-NNN: title matching the filename, the BLUF placement, core section order, no duplicate numbers (gaps are a warning), and supersession bidirectionality (the high-value cross-file check). Plus:

• Lifecycle consistency (errors): superseded with an empty superseded-by; deprecated with a non-empty superseded-by; an in-force (accepted/proposed) ADR carrying a superseded-by. These complement the bidirectionality check without double-reporting.
• Stale touches (warning): a touches: entry that is a literal filesystem path (not a glob, not a config key) which no longer resolves under --repo-root (default: git toplevel, else cwd) — the discovery surface may have drifted. Warning-tier only; counts toward exit 10 under --strict.

--strict makes warnings count toward exit 10. Exit 4 if a file's frontmatter is unparseable.

---

CI integration

ADRs only stay trustworthy if the integrity contract is machine-enforced. Gate the lint in CI; --strict turns the stale-touches drift warning into a hard signal.

# .github/workflows/adr-lint.yml
name: adr-lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint ADRs
        run: python skills/adr-ops/scripts/adr-lint.py --strict --dir docs/adr
        # exit 10 (findings, incl. stale-touches under --strict) fails the build

Local pre-commit gate: add python scripts/adr-lint.py --strict --dir docs/adr to a pre-commit hook so a one-sided supersession or a stale discovery surface is caught before the commit lands. A pre-edit hook can additionally call adr-touching.py <changed-path> and surface the governing ADR (exit 10) before a subsystem is modified.

---

See also

• references/canonical-format.md — the full template, field table, and body rules.
• references/lifecycle-and-supersession.md — status lifecycle + the three change modes.
• assets/ADR-template.md — copy-ready canonical template.