adr-kit

Architecture decisions your AI coding agents actually follow.

Coding agent? Installing ADR Kit: read INSTALL-AGENT.md and stop there: it is the complete client-neutral runbook. Working in a project that already has ADR Kit: the agent contract is the whole brief.

Your codebase is full of decisions: the database you migrated to, the layer nothing may bypass, the framework you committed to, the pattern you standardized on. Almost none of it is visible in the code. It lives in the heads of the people who were there, and a coding agent has no head. It is fast, confident, and starts every session with total amnesia. Left alone it reintroduces the driver you dropped, bypasses the repository layer, and makes new architectural decisions without telling anyone.

adr-kit makes architecture decisions executable. Architecture Decision Records stop being documentation nobody re-reads and become guardrails that run: the decisions relevant to the current task are retrieved and injected while the agent works, the governing decision is delivered before a file is edited, every commit is checked against declarative rules with file:line citations, and a guardian watches for decisions that have drifted out of date. One toolkit covers the whole lifecycle (capture, enforce, maintain, retire) across Claude Code, OpenAI Codex, the standalone GitHub Copilot CLI, and OpenCode.

For the agent, it removes the guessing. Instead of reading every ADR, or none, it queries a generated index and gets a ranked, explained shortlist for the task in front of it. It receives the binding decision as context at the moment it writes the file, not as a review comment three days later. And it gets a deterministic pass/fail at commit time that no amount of confident prose can talk its way around.

For you, writing a decision down finally pays off the same week. The ADR you record on Monday blocks the violation on Thursday without you being in the room. Half-formed intent becomes a real decision record through a guided interview that asks one evidence-backed question at a time. The guardian tells you which decisions have gone stale, which were made but never recorded, and which are ready to retire, so the decision log stays worth reading instead of becoming another folder of dead markdown.

The engines are deterministic, stdlib-only Python 3.10+: no build step, no service, no API key on any default path. LLM passes exist, are opt-in, cost nothing until you enable them, and never run in a hook hot path.

Pre-1.0: functional and in daily use, but conventions may still evolve before v1.0.0. Pin a tag if you need stability across upgrades.

Audit posture: the 2026-07-18 source audit drove fail-closed enforcement, exact staged-snapshot handling, transaction-safe lifecycle/state updates, and cross-platform packaging fixes. ADR Kit remains a development guardrail, not a sandbox, branch-protection replacement, or sole merge control.

Start here

Agent contract

Three rules cover almost everything an agent needs in an ADR Kit project. Full reference: docs/README.md.

1. Find the decisions for a task by querying the index, not by reading the set.

python bin/adr-context --format json "<task description>"

It queries the generated docs/adr/ADR-INDEX.json instead of opening every ADR, and returns explainable matches from lifecycle, scope, paths, components, symbols, topics, and relationships. Open only the returned Markdown ADRs before applying a constraint: the Markdown is the authority, the index is the lookup. Regenerate with python bin/adr-index docs/adr and verify with python bin/adr-index --check docs/adr. Never hand-edit either generated index. See Selective ADR context.

2. Treat an injected decision as binding. When an [adr-inject] ADR-NNN ... governs <file> block arrives before an edit, the quoted Decision is a constraint on that edit, not background reading. Accepted ADRs govern; Proposed ADRs are advisory and labelled as such; historical ADRs are opt-in.

3. Never invent an ADR format. Run python bin/adr profiles --format json and accept only a returned profile id with its returned template path. MADR is the preferred default; nygard and canonical are the other shipped profiles. Never synthesize an unregistered template.

What's new

These are the releases that change what ADR Kit does; full detail, including the patch releases, is in CHANGELOG.md.

Upgrading from before 0.40.0: update ADR Kit, run python bin/adr-index docs/adr, then add retrieval probes before enabling strict index or strict completeness policy. Projects without retrieval metadata keep working; completeness is advisory by default, and no ADR body profile or lifecycle transition changed.

Why

ADRs are the established answer: short markdown files in your repo that record the problem, the decision, the alternatives rejected, and the consequences accepted. What was always missing is enforcement. A decision nobody re-reads is a decision nobody follows.

adr-kit closes that loop three times over:

1. Before the agent edits: the decisions relevant to the task are ranked and injected as context.
2. While the agent edits: a hook nudges it the moment a change touches files governed by a decision.
3. When the work lands: declarative rules from each ADR are checked against the diff at commit time and in CI, deterministically and key-free.

And because decisions age, a periodic guardian flags drift between code and decisions, retirement candidates, and decisions that were made but never recorded.

One engine, three certified CLIs plus OpenCode

ADR Kit ships separate integration payloads for Claude Code CLI, OpenAI Codex CLI, and the standalone GitHub Copilot CLI. All three carry the same 15 workflows, the same deterministic engines, the same key-free five-tool MCP server, and English skill metadata; only the native event surface differs. A separate native OpenCode plugin uses the same engines and adds OpenCode-native config, skills, commands, hooks, compaction context, and MCP registration. The generated client support matrix remains the three-client certification view; OpenCode evidence and boundaries live in docs/clients/opencode.md. Per-client detail lives in docs/clients/.

Lifecycle behavior is quiet-by-default: routine successful hooks print nothing, relevant ADR context still reaches the agent, and actionable warnings stay visible. Where a client has no native pre-edit event, deterministic pre-commit enforcement remains the backstop, so no client is silently less governed than another.

Install

Coding agents should follow INSTALL-AGENT.md. The sections below are the human-oriented quick reference.

Install every detected CLI

From a cloned checkout:

python scripts/install-agent-envs.py --detect-only
python scripts/install-agent-envs.py --project-root /path/to/project

The installer verifies real executable and version output for claude, codex, and the standalone copilot CLI. It installs ADR Kit through every detected client's native plugin API on Windows, macOS, and Linux. Before touching a client, it validates the complete source and the Python 3.10+ interpreter that is running the installer. It prepares a persistent user-local marketplace with that exact interpreter embedded in the Codex and Copilot MCP configuration, then completes a real MCP initialize/tools-list smoke test. Use --clients codex,copilot, --dry-run, or --source /path/to/adr-kit for explicit and automated installs. The post-install format scan is read-only: it reports deterministic preview commands or guided migration steps and never rewrites an ADR.

Register ADR Kit in a project

Preview and apply the shared project guidance separately from native plugin registration. This is also the enforcement setup for OpenCode projects:

python scripts/setup-project.py --project-root /path/to/project --dry-run
python scripts/setup-project.py --project-root /path/to/project
python scripts/settings.py --project-root /path/to/project show

Setup writes generated .adr-kit/ADR-guide.md, adds independent owned blocks to AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md, and installs the deterministic pre-commit gate by default. It preserves all bytes outside the marker blocks. An existing generated guide is backed up before replacement; project-specific guidance belongs in user-owned .adr-kit/ADR-guide.local.md.

Settings use global defaults with per-project overrides. The effective output shows the value and source of every option. Disable or re-enable pre-commit, for example:

python scripts/settings.py --project-root /path/to/project set pre_commit.enabled false
python scripts/setup-project.py --project-root /path/to/project
python scripts/settings.py --project-root /path/to/project set pre_commit.enabled true
python scripts/setup-project.py --project-root /path/to/project

Settings also cover verified stable updates, trigger/frequency, offline and pinned operation, per-client opt-outs, doctor repair/check-only policy, and local versus paid/cloud judgment. No provider or model tag is a fallback default. --probe-models performs a bounded local identity check without invoking a model; zero or multiple candidates remain visibly unavailable or ambiguous. Paid/cloud judgment remains explicit opt-in, and no model runs in a hook hot path.

Claude Code

/plugin marketplace add rvdbreemen/adr-kit
/plugin install adr-kit@rvdbreemen-adr-kit
/reload-plugins
/adr-kit:init

The first three install the plugin. The fourth is the one-shot per-project bootstrap: it wires a marker-owned pointer into CLAUDE.md (the shared guide lands at .adr-kit/ADR-guide.md), audits your existing codebase for decisions already in effect (the database you chose, the framework you committed to, the patterns you standardized on), walks you through recording them as Accepted ADRs in batches, and installs the pre-commit enforcement hook. Idempotent: safe to re-run.

That is the whole setup. From the next session on, your agent knows the decisions, gets nudged when it touches them, and receives a local check when it commits.

Prefer a lighter start? Run scripts/setup-project.py --dry-run, then apply it. This installs the shared guide, three independent managed instruction blocks, and (by default) pre-commit without running the architecture audit. Disable pre-commit first through adr-kit:settings when guidance-only setup is required.

The Claude integration keeps only its manifest under .claude-plugin/. Plugin-root skills/, hooks/hooks.json, .mcp.json, agents, and bundled executables provide 15 workflows, six bounded hooks, and the five-tool MCP server.

OpenAI Codex

codex plugin marketplace add rvdbreemen/adr-kit
codex plugin add adr-kit@rvdbreemen-adr-kit-codex
codex mcp list

Codex does not use Claude's /adr-kit:... slash-command syntax. ADR Kit workflows appear as namespaced skills: open /skills, or invoke $adr-kit:context, $adr-kit:judge, $adr-kit:lint, and the other skills. The separate codex/ distribution contains all 15 workflows and the key-free five-tool MCP server. See the official Codex skills and plugin contracts.

Standalone GitHub Copilot CLI

copilot plugin marketplace add rvdbreemen/adr-kit
copilot plugin install adr-kit@rvdbreemen-adr-kit-copilot
copilot plugin list
copilot mcp list

This targets @github/copilot invoked as copilot, not gh copilot or VS Code agent mode. The separate copilot/ distribution follows GitHub's Copilot plugin contract and installs 15 skills plus the same key-free MCP server. Open /skills inside Copilot CLI to discover ADR Kit workflows. Its lower-camel hook package supplies proactive session/task context and PostToolUse; pre-commit remains the edit-enforcement backstop.

If an older installation reports that adr-mcp is missing under the active project (for example <project>/bin/adr-mcp), refresh both marketplace and plugin, then reload MCP servers:

copilot plugin marketplace update rvdbreemen-adr-kit-copilot
copilot plugin update adr-kit
copilot mcp get adr-kit

In copilot mcp get adr-kit, the executable argument must be ${PLUGIN_ROOT}/bin/adr-mcp; cwd remains . so ADR Kit serves the active project. Start a new Copilot session or run /mcp reload in the current one. Agents should use these native update commands instead of editing the installed .mcp.json or replacing ${PLUGIN_ROOT} with a machine-specific path.

OpenCode

OpenCode is supported through a separate native plugin package. It uses the same deterministic Python engines and five-tool MCP server as the certified clients, while adding OpenCode-native configuration, skills, commands, context, compaction, edit, shell, and session hooks.

From the ADR Kit checkout, the repository-local opencode.json is already configured:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["./"]
}

For another project, use the published package for v0.52.0:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@rvdbreemen/[email protected]"]
}

Future versions are staged through the documented npm workflow and require a maintainer approval before they become public. Until a future version is approved, point OpenCode at a reviewed checkout:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["/absolute/path/to/adr-kit", {"python": "/absolute/path/to/python"}]
  ]
}

The plugin adds only missing configuration entries and preserves user-owned skills, instructions, commands, references, and MCP servers. It delegates hook work to hooks/adr-hook.py; normal context is advisory and fail-open. The deterministic pre-commit and CI judge remain the enforcement floor:

python scripts/setup-project.py --project-root /path/to/project

OpenCode is intentionally outside clients/capabilities.json, the generated three-client support matrix, and the three-client native certification gate. See OpenCode support for options, manual MCP registration, and the tested support boundary.

Portable Agent Skills and MCP clients

INSTALL.md documents the native plugin layouts and portable fallbacks.

On top of the native installs, any compatible local stdio MCP client can connect to the bundled MCP server for enforcement and context tools.

The CLI engines under bin/ require Python 3.10+, with no pip install. The automatic installer embeds the absolute interpreter that launched it, so Windows python.exe and Unix python3-only installations need no manual MCP manifest edit. See INSTALL.md.

Upgrading

Three layers, each with a clear path:

• The plugin itself: updates through the normal Claude Code plugin update flow. The engines (judge, guardian, context ranker) always resolve the newest installed version automatically, so hooks you installed earlier keep running current code without any action.
• Copied artifacts (the git pre-commit wrapper, the project-scoped settings entry, the guide file): these freeze at install time by nature. Since v0.27.0 they carry version stamps, and the guardian tells you at session start when one lags the installed plugin (wrapper: ... STALE). Run /adr-kit:upgrade and they are refreshed idempotently; the same command still handles the legacy v0.11 to v0.12 footprint migration. You can inspect the state any time with bin/adr-guardian artifacts.
• Existing ADR sets: MADR and Nygard are first-class selectable profiles, and the older adr-kit canonical profile remains valid without rewriting. bin/adr-migrate --plan docs/adr detects metadata/filename upgrades and common external formats without writing. It prints deterministic dry-run commands where safe and guided migration instructions otherwise. Preview retrieval metadata and Decision Contract candidates separately with bin/adr-migrate --suggest-retrieval --dry-run docs/adr; it never writes.

The lifecycle: capture, guard, maintain

Capture decisions (and stop rationalizing them away)

• /adr-kit:adr loads the full authoring guide. Its two signature disciplines, borrowed and battle-tested from earlier skills (see Credits):
  • Anti-rationalization guards: a table of the excuses agents and humans use to skip writing an ADR ("it is obvious", "I will document it later", "the code speaks for itself"), each with a counter-argument. Fires before the decision goes unrecorded.
  • Four verification gates: Completeness, Evidence, Clarity, Consistency. An ADR cannot flip from Proposed to Accepted until it passes all four, and a reviewer can block on a single named gate ("fails Evidence, add measurements").
• /adr-kit:grill turns incomplete knowledge into a useful decision record. It reads repository facts first, labels claims as observed, human-stated, inferred, or unknown, and asks one unresolved decision question at a time. It can complete an existing Proposed ADR, reconstruct a decision from a PR, git range, chat log, or document, and revalidate an older decision. Source material is evidence, never acceptance authority.
• adr-audit readiness is the deterministic companion to grilling. It classifies a record, separates mechanical fixes from human decisions, resolves explicit implementation links, and emits stable human, JSON, or GitHub output without invoking a model or changing lifecycle state. See the ADR Grilling user guide for complete subject, reconstruction, resume, queue, acceptance, and CI examples.
• adr-generator agent scaffolds the ADR for you: decision tree for "does this need an ADR?", a proposed ## Enforcement block when the decision has a code surface, and a post-write quality check.
• /adr-kit:init's audit mines an existing codebase for decisions already in effect, so you start with a real decision log instead of an empty directory.
• /adr-kit:review audits a finished branch or PR: it enforces the existing ADRs against the committed range diff and, crucially, hunts for new decisions the branch introduced but never recorded, reading both the diff and the stated intent (commit messages, PR description), because decisions are often confessed in prose while the diff looks like plumbing. Found candidates are deduped against your existing set and drafted as Proposed, never auto-accepted.
• bin/adr-suggest (on by default) runs the same missing-decision detector per commit and prints a one-line nudge. It never blocks. Switch it off with suggest.enabled: false per project, or ADR_KIT_SUGGEST_DISABLE=1 for one run.

Guard the agent while it works

• Context lookup (/adr-kit:context, bin/adr-context): give it a task plus optional paths, components, symbols, topics, status, and authority filters. The shared schema-v2 index engine returns a bounded, explainable shortlist without scanning every Markdown ADR. Historical records are excluded unless requested; governing Accepted and advisory Proposed records remain distinct. Open each returned source ADR before applying it. See Selective ADR context.

• In-flight nudges (bin/adr-watch, v0.24.0+): a PostToolUse hook fires after every Edit/Write in Claude Code and checks the touched file against the Accepted ADRs (Enforcement path globs first, keyword relevance second):

  [adr-watch] ADR-007 (no direct DB calls outside repository layer) may apply to src/db/foo.py
  

  Deterministic, key-free, under 100ms, never blocks, and a per-session cooldown keeps it from nagging. This closes the gap between session-start context and commit-time enforcement: the agent is corrected while the file is still open.

• Edit-tier injection (bin/adr-watch --pre-edit, v0.31.0+): a PreToolUse hook fires before every Edit/Write and injects the top-ranked governing ADR's ## Decision text (bounded to a token budget), so the agent honours the decision as it writes, not after. The PostToolUse nudge above stays as a confirmation backstop. Same deterministic matcher, key-free, exits 0. Formalised in ADR-004.

• Decision indexes (bin/adr-index): generates two deterministic, timestamp-free views from the same format-aware records. docs/adr/ADR-INDEX.md is the compact one-row-per-ADR session map imported by CLAUDE.md; schema-v2 docs/adr/ADR-INDEX.json is the actual selective-context query database, with source fingerprints, retrieval metadata, decision contracts, and sorted relationship edges. Markdown ADRs remain authoritative.

• Commit-time enforcement (bin/adr-judge + pre-commit hook): every ADR can carry a fenced JSON ## Enforcement block with declarative rules (forbid_pattern, forbid_import, require_pattern, each optionally scoped by path_glob). On every git commit the hook runs those rules against the staged diff with file:line citations. Fast, deterministic, no LLM, no API key. ADRs whose rules are too nuanced for regex get a model-reviewed pass as well: llm_judge defaults to true, so a block that says nothing about it opts in, and only an explicit false opts out. Cost is bounded by scope rather than by the flag — an ADR is judged only when the diff touches a file matching its rules' path_glob set, so a commit outside every scope makes no model call at all. A block with no rules, or a rule without a glob, has no boundary to narrow with and is judged on every commit; prefer marking such a decision as having no code surface. Upgrading an existing project? bin/adr-migrate --enable-llm-judge --dry-run shows exactly what would change, and /adr-kit:upgrade asks before applying it.

• PR-time enforcement in CI: the same judge can run as a composite GitHub Action or through the pre-commit framework, giving local and CI workflows the same deterministic rule set. See CI integration and the audit notice above for current limitations.

• Audited escape hatch: hotfix has to land despite a FAIL? ADR_KIT_OVERRIDE="ADR-003: hotfix for incident 42" git commit ... downgrades that one ADR's violations to loud warnings, refuses an empty reason, logs the override locally, and pairs with an ADR-Override: commit trailer convention you can reconcile later with adr-judge --audit-overrides. Guardrails with a paper trail instead of --no-verify folklore.

Maintain the decision log (decisions age; the kit notices)

• The Guardian (bin/adr-guardian, /adr-kit:guardian): a session-start staleness detector with two tiers. The cheap tier (daily, free) checks for code drift against Enforcement rules, retirement candidates, lint health, and refreshes a bounded Proposed-ADR work queue. SessionStart reads only that local 24-hour cache and offers at most three next actions; it never scans or starts an interview in the hook. The LLM tier (bi-weekly, asks before spending) hunts for missing ADRs and runs the full model-reviewed audit. Findings get mixed responses by type: drift is surfaced loudly with file:line, missing decisions are offered for authoring, stale ADRs get a retirement draft for review. Never runs in the background, never spends without asking.
  • Team mode (v0.22.0+): a weekly CI cron sweep maintains a single "ADR guardian audit" tracking issue (created on findings, updated, closed when clean) so the whole team sees ADR health, not just whoever opened a session today. Copy templates/github-workflows/adr-guardian-audit.yml into your repo.
  • Trend history (v0.29.0+): every sweep appends to a 52-entry trend log, and the nudge shows the delta: trend: drift 2 -> 0, retire 1 -> 2, coverage 40% -> 45%. A KPI with memory, not a snapshot.
• Health dashboard (adr-audit status): totals, status breakdown, average age, enforcement health, retirement candidates, retrieval probe results, Accepted-binding metadata completeness, and the Enforcement coverage percentage of your Accepted ADRs. JSON, markdown, or table.
• Quality scoring (adr-audit quality): grades every ADR A to D across the four gates (Completeness 40%, Evidence 20%, Clarity 20%, Consistency 20%), with per-gate issue codes. Exits 1 below grade B, so you can gate CI on ADR quality.
• Generated index refresh (bin/adr-index docs/adr/): atomically rebuilds the sentinel-owned docs/adr/README.md block plus ADR-INDEX.md and ADR-INDEX.json. --check exits non-zero when any generated view is missing or stale, or duplicate ADR ids exist. Use --format graph --adr-dir docs/adr to inspect the graph without writing.
• Local doctor (adr-audit doctor): fast mode checks ADR/index state, retrieval probes and metadata completeness, settings, generated artifacts, managed guidance, Claude/Codex/Copilot identity, MCP launchers, and cached model health without login or model invocation. Probe failures block; metadata completeness is advisory unless configured strict. Default mode repairs only deterministic ADR Kit-owned drift; --check is read-only, --fix permits backed-up managed rewrites, and --deep adds bounded native, MCP, and local-model probes. See troubleshooting.
• Lifecycle commands (bin/adr, v0.32.0+): local propose, accept, supersede, reject, and document commands update frontmatter, the Status section, append-only Status History, reciprocal supersession links, and then refresh the generated README index.
• After-the-fact acceptance (bin/adr document + bin/adr accept --auto): mark already-shipped behavior with documents_shipped:true and local verified_in pointers, then verify strict lint, quality, and human readiness. The default assist mode reports eligibility without mutating; acceptance requires --confirm after the engineer reviews the packet. Existing projects that intentionally require the legacy automatic transition can explicitly configure lifecycle.auto_accept.mode: "auto".
• Retirement audit (/adr-kit:retire, bin/adr-retire): ranks Accepted ADRs for retirement using four deterministic signals (status age, technology removal, supersession, policy drift). Read-only; a recommendation always needs a human.
• Dependency graph (/adr-kit:related, bin/adr-related): who does ADR-007 point at, and who points back? Outbound and inbound edges per declared reference kind, with dangling links flagged. The same normalized edges are available repository-wide in ADR-INDEX.json.
• Guided supersession (/adr-kit:supersede): replace a decision without rewriting history. The skill shows the dependency graph first, drafts the successor as Proposed, and asks before changing lifecycle state. The lifecycle CLI enforces legal transitions and all acceptance gates, rejects competing chains, and updates both records plus generated indexes in one rollback-safe transaction.
• Team-safe numbering (bin/adr-renumber, v0.23.0+): two branches both claim ADR-043, both pass CI in isolation, the collision appears after merge. The lint gate fails the duplicate with both files named, and adr-renumber moves one to a free number, dry-run first, updating every cross-reference in the set (and never touching ADR-0430 when you renumber ADR-043).
• Lint (/adr-kit:lint, bin/adr-lint): validates every ADR against the gates with file:line citations and three result tiers (PASS, ADVISORY, FAIL). Every run also emits read-only migration notices for supported legacy files, Y-Statements, Tyree/Akerman records, arc42 decision sections, hybrids, and unknown ADR shapes. It provides an exact deterministic preview when safe and guided review otherwise; it never migrates automatically. The CLI form is deterministic and CI-ready; --strict enables canonical frontmatter validation, local verified_in evidence resolution, reciprocal supersession checks, and binding gate lookup for CI. The skill form adds model judgement on the Evidence and Clarity gates.

MCP server: bin/adr-mcp

A deliberately thin MCP server (stdio, newline-delimited JSON-RPC 2.0, Python stdlib only, zero dependencies) that exposes the guardrails to Claude Code, OpenAI Codex, GitHub Copilot CLI, or another compatible local stdio MCP client. Five tools, all key-free:

# Claude Code
claude mcp add adr-kit -- python /path/to/adr-kit/bin/adr-mcp --root "$(pwd)"

For another stdio client, place the following in its MCP configuration:

{
  "mcpServers": {
    "adr-kit": {
      "command": "python",
      "args": ["/path/to/adr-kit/bin/adr-mcp", "--root", "/path/to/your/project"]
    }
  }
}

Why only five tools? Contrast is the feature: adr-kit ships the smallest surface that carries the guardrails and readiness facts, and nothing that needs an API key. Grilling itself stays in the client session so an engineer or architect remains part of the decision.

Slash commands

/adr and /adr-kit:adr invoke the same skill; the prefix form is canonical.