adr-kit
A complete Architecture Decision Record (ADR) toolkit for AI coding agents. Drop into any project to give Claude Code, Claude Cowork, Cursor, GitHub Copilot, OpenAI Codex CLI, or any agent that supports the Agent Skills format a shared, enforceable ADR workflow.
Pre-1.0: the toolkit is functional and in use, but the API and conventions may change before v1.0.0. Pin to a specific tag if you need stability across upgrades. Latest release: see the badge above.
What it does
- Skill (
SKILL.md): the comprehensive ADR guide. When to write one, what to write, how to verify it, how to supersede it. Includes anti-rationalization guards (the excuses agents use to skip documentation) and four named verification gates (Completeness, Evidence, Clarity, Consistency).
- Agent (
agents/adr-generator.md): a focused subagent for creating a new ADR. Hand it a decision and it produces a fully populated docs/adr/ADR-XXX-title.md file.
- Lint skill (
/adr-kit:lint, since v0.7.0): checks existing ADRs against the four gates with file:line citations. Supports scoped policy via .adr-kit.json since v0.9.0.
- Lint CLI (
bin/adr-lint, since v0.10.0): deterministic Python CLI for CI / pre-commit / batch validation. Same gate logic as the skill, exit-code-based.
- Migrate skill (
/adr-kit:migrate, since v0.11.0): guided rewrite of legacy-shaped ADRs into the canonical-seven-section template. Read-then-confirm workflow. No fabrication; uses TODO placeholders for genuine content gaps.
- Instructions (
instructions/): two path-specific instruction files, one for coding work (adr.coding.md) and one for code review (adr.review.md). They tell the agent which ADR rules apply and when.
- Template (
examples/ADR-template.md): a clean ADR file you can copy.
The pieces work together: the skill is the reference, the agent does the writing, the lint flags deviations, the migrate command brings legacy work into shape, the instructions tell the agent what to do at the right moment.
Why ADRs
Architecture Decision Records are short markdown files that capture why a system is built the way it is: the problem, the chosen solution, the alternatives that were rejected, the consequences accepted. They live in the repo (docs/adr/) alongside the code they describe.
ADRs are the antidote to "why does this exist?" archaeology three years after the fact. They are also the antidote to silent architectural drift: when the next change conflicts with a documented ADR, the conflict surfaces in code review instead of in a postmortem.
This toolkit adds two patterns to the basic ADR tradition:
- Anti-rationalization guards: a table of excuses agents (and humans) use to skip writing an ADR ("it's obvious", "I'll do it later", "the code speaks for itself"), with counter-arguments. Pre-flight discipline.
- Verification gates: four named gates an ADR must pass before its Status can flip from
Proposed to Accepted. Reviewer can block on a single named gate ("this fails the Evidence gate, please add measurements").
Install
Claude Code (recommended): four slash commands
/plugin marketplace add rvdbreemen/adr-kit
/plugin install adr-kit@rvdbreemen-adr-kit
/reload-plugins
/adr-kit:setup
The first three install the plugin: marketplace registration, plugin install, plugin reload. The fourth is a one-time per-project setup: it appends a short "ADR Kit Rules" section to your project's CLAUDE.md (creating the file if needed) so future sessions know about the skill, the adr-generator subagent, and the path-specific instructions. The setup command is idempotent: re-running it skips the append if the section is already there.
Optional fifth command: /adr-kit:lint reads every ADR-*.md in your docs/adr/ directory and reports per-file, per-gate pass/fail with line-level citations for failures. Useful right after install to see how your existing ADRs measure up against the four gates, and useful before merging a PR that touches an ADR. Read-only.
Claude Cowork shares the .claude/ convention; the same plugin commands work once your workspace is connected to a repo.
Other AI coding tools: copy the files
For Cursor, GitHub Copilot, OpenAI Codex CLI, and any other agent that reads skills from its own directory layout, see INSTALL.md. It documents the per-tool target paths and includes a one-shot install script that lays everything down in one command.
File map