adr-kit

Architecture Decision Record (ADR) management skill. Creates, maintains, and enforces architectural decisions with anti-rationalization guards and named verification gates. Drop into any project to give an AI coding agent a shared, enforceable ADR workflow.

One-shot project bootstrap for adr-kit. Hooks the kit into CLAUDE.md (via a slim stub + a copy of templates/adr-kit-guide.md → .claude/adr-kit-guide.md), runs bin/adr-audit to enumerate decision-shaped artefacts in source + documentation, walks the user through batch approval to generate Accepted ADRs via the adr-generator subagent, installs the pre-commit hook, and finally lints. Idempotent across re-runs. User-invocable only — this is a side-effecting operation.

One-time project setup for adr-kit. Hooks `CLAUDE.md` (slim stub with @-import) and drops the canonical guide at `.claude/adr-kit-guide.md`. v0.11-style inline `## ADR Kit Rules` sections are detected and left untouched (run `/adr-kit:upgrade` to migrate them). Idempotent across re-runs. The lighter cousin of `/adr-kit:init` — `setup` does not run a codebase audit or install the pre-commit hook.

Install or uninstall the adr-kit pre-commit hook in the current project. Copies templates/githooks/pre-commit into .githooks/pre-commit, makes it executable, and runs `git config core.hooksPath .githooks`. Idempotent. Used internally by /adr-kit:init and /adr-kit:upgrade; also exposed standalone for users who want to add or remove the hook independently.

Guided rewrite of legacy-shaped ADRs into the canonical-seven-section template enforced by /adr-kit:lint. Promotes inline status / date lines to a

ADR-set health sweep for adr-kit. Runs the due health tier(s) — cheap (drift + stale + lint) and/or LLM (suggest + audit) — applies mix-by-finding-type responses, and stamps the state file when done. Invoke after seeing an [adr-guardian] ... DUE block at session start, or on demand to run a full health sweep. Accepts optional arg: cheap | llm | all. LLM tier always asks before spending.

Shows the dependency graph for one Architecture Decision Record. Give it an ADR id (e.g. "ADR-007") and it lists outbound edges (Related Decisions entries, Supersedes claims, Superseded by / Amended by status refs) and inbound edges (every other ADR that references it, with the reference kind), flagging dangling references to ADRs that do not exist. Read-only and safe to call from parallel subagents. Invoke before superseding or retiring an ADR, or whenever you need to know what depends on a decision.

Guided supersession of an existing Architecture Decision Record. Shows the target's dependency graph first, drafts the superseding ADR via the adr-generator subagent (Status Proposed, back-linked), and only after explicit user approval flips the old ADR's Status line to "Superseded by ADR-M", appends status_history entries on both sides, and wires Related Decisions both ways. Verifies the chain with bin/adr-related and bin/adr-lint. Refuses to overwrite an existing supersession that points at a different ADR.

Refresh a project's installed adr-kit artifacts after a plugin update, and migrate legacy footprints. Runs adr-guardian artifacts to detect copied wrappers (git pre-commit hook, project-scoped settings entry, guide file) that lag the installed plugin version, refreshes them idempotently, and still handles the legacy v0.11 to v0.12 migration (CLAUDE.md stub, guide copy, hook install, Enforcement backfill). Safe to re-run.

PR/branch-level ADR audit. Validates the COMMITTED work of the current branch (or a PR) against the project's ADRs in two passes - enforcement (bin/adr-judge on the merge-base range diff, same engine as the pre-commit hook and the CI action) and discovery (find NEW architectural decisions in the diff plus commit messages plus PR description that no ADR documents yet, then draft Proposed ADRs for the ones the user picks). Invoke before opening or merging a PR, or on an existing PR to make sure nothing undocumented slips through. Complements /adr-kit:judge, which only sees the staging area.

Loads the Architecture Decision Records most relevant to a task before you implement it, so existing decisions are honored without burning context on the whole ADR set. Give it a topic (e.g. "mqtt discovery", "heap allocation", "caching") and it returns the 3-5 most relevant Accepted ADRs as readable context — title, one-line decision, file path, and relevance score. Read-only and safe to call from parallel subagents. Invoke before starting implementation in a project that has ADRs.

Interactive judge of a staged git diff against the project's Accepted ADRs. Runs bin/adr-judge with the LLM pass (Claude Sonnet by default, since v0.13.0) — same engine the pre-commit hook uses, so verdicts are consistent. On violation, walks the user through three resolution paths (write a new ADR, supersede an existing ADR, fix the code). Pairs with the pre-commit hook — invoke before committing on important changes, or after the hook blocks you to drive the resolution.

Lints existing Architecture Decision Records against four verification gates plus the deterministic status-history audit. Run on a single ADR file or on the whole docs/adr/ tree. Reports pass/fail per gate per file with file:line citations for failures. Read-only.

Audits Accepted Architecture Decision Records for possible retirement using deterministic staleness, technology-removal, supersession, and enforcement-policy signals. Produces ranked candidates for human review; never edits ADRs.