adr

Architecture Decision Records (ADRs) for any repository, built for coding agents. The plugin tells agents why code is the way it is, stops them from undoing deliberate decisions, and turns the important ones into checks. Nothing in it assumes a language or framework.

What it does

Plus scripts/validate-adrs.py, a dependency-free Python script for structural validation, and an optional, off-by-default Stop hook that suggests /adr:new (see hooks/README.md).

Install

/plugin marketplace add BipBop-Labs/bipbop-skills
/plugin install adr@bipbop

Codex CLI:

codex plugin marketplace add BipBop-Labs/bipbop-skills --ref main
codex plugin add adr@bipbop

Update

/plugin marketplace update bipbop
/plugin update adr@bipbop
/reload-plugins

Codex CLI:

codex plugin marketplace upgrade bipbop

Typical workflow

1. /adr:init in the target repository. It creates docs/adr/ with README.md (index), template.md, known-debt.md, adds a short block to CLAUDE.md or AGENTS.md, and offers to wire the validator into pre-commit or CI. If ADRs already exist elsewhere, it adopts them.
2. /adr:distill on an existing codebase. Candidates arrive five at a time with evidence, a clearly labelled guess at the rationale, and the alternatives apparently avoided. You accept, mark as debt, reject, or skip. State lives in docs/adr/.distill-state.json, so later runs do not re-ask and new code can be distilled incrementally.
3. /adr:new whenever a change hits a trigger (new dependency, boundary, data model, public interface, hard-to-reverse or questionable choice).
4. /adr:review before merging, to see which accepted decisions a diff touches, which changes need an ADR, and which known-debt items it fixes.

ADR format

docs/adr/NNNN-slug.md with YAML frontmatter:

---
id: ADR-0003
title: Outbound HTTP goes through one client
status: accepted        # proposed | accepted | superseded | deprecated | rejected
date: 2026-10-02
deciders: [maria]
tags: [http, dependencies]
paths: [src/net/**]
supersedes: []
superseded_by: []
---

Sections: Context, Decision, Options considered, Consequences, Rationale status (confirmed or unknown), Evidence. Full template in skills/adr/templates/adr-template.md.

Rules: to change an accepted ADR, edit it and add a line to its ## History. A new ADR supersedes it only when a different decision replaces it whole. A @decision ADR-NNNN comment in code means read that ADR before touching the spot. known-debt.md lists things that look deliberate but are not; agents may fix those.

Validation script

python3 "$CLAUDE_PLUGIN_ROOT/scripts/validate-adrs.py" [--root .] [--adr-dir docs/adr] [--strict] [--fail-on-proposed] [--json] [--no-code-scan]
python3 "$CLAUDE_PLUGIN_ROOT/scripts/validate-adrs.py" --print-setup   # pre-commit and CI snippets

Checks: required frontmatter and allowed statuses; unique, sequential numbers matching filenames; index in sync with the folder; supersede links resolving both ways; referenced paths still existing (warning); @decision tags pointing to existing, non-superseded ADRs. With --fail-on-proposed, an ADR still proposed is an error. Exit codes: 0 clean, 1 errors (or warnings with --strict), 2 no ADR folder or bad usage.

It does not judge whether code complies with a decision. That is /adr:review and per-decision checks from skills/adr/references/enforcement-by-stack.md.

For CI, copy the script into the repository (/adr:init offers to) so the job does not depend on a plugin cache path, and run it with --strict --fail-on-proposed so an ADR nobody has accepted or rejected does not merge. Leave --fail-on-proposed out of pre-commit hooks: drafting a proposed ADR locally is normal.

Design notes

RESEARCH.md covers the format choice, existing tooling, prior Claude Code art, the enforcement table, and the evidence, including what is not proven.