By rvdbreemen
Architecture Decision Record toolkit for AI coding agents. Four modes: /adr-kit:init for one-shot project bootstrap; pre-commit verification via bin/adr-judge (declarative Enforcement blocks plus Claude Sonnet LLM judge, opt-in since v0.17); on-demand /adr-kit:adr authoring and /adr-kit:judge resolution; and the ADR Guardian (v0.18): a SessionStart staleness detector with two-tier cadence (drift daily, LLM bi-weekly) and mix-by-finding-type in-session responses.
Based on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
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.
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.
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.
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.
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.
Modifies files
Hook triggers on file write and edit operations
Uses power tools
Uses Bash, Write, or Edit tools
Architecture decisions your AI coding agents actually follow.
adr-kit turns Architecture Decision Records from passive documentation into active guardrails. Your agent gets the relevant decisions injected while it codes, every commit is checked against the accepted decisions, and a guardian watches for decisions that go stale. One toolkit covers the whole lifecycle: capture, enforce, maintain, retire.
Works as a Claude Code plugin and as plain files for Cursor, GitHub Copilot, OpenAI Codex CLI, Claude Cowork, and any agent that supports the Agent Skills format. The engines are dependency-free Python 3.9+ (stdlib only, no build step, no API key required for any default 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.
AI coding agents are fast, confident, and have no memory of why your system is built the way it is. Left alone, they will cheerfully reintroduce the database driver you migrated away from, bypass the repository layer you standardized on, and make new architectural decisions without telling anyone. Human teams have the same failure mode, just slower.
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:
And because decisions age, a periodic guardian flags drift between code and decisions, retirement candidates, and decisions that were made but never recorded.
/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 slim stub into your CLAUDE.md (full guide lands at .claude/adr-kit-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) and walks you through recording them as Accepted ADRs in batches, then 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 cannot commit a violation without it being flagged.
Prefer a lighter start? /adr-kit:setup writes only the CLAUDE.md stub and guide, skipping the audit and the hook; you can add those later with /adr-kit:init or /adr-kit:install-hooks.
The same skill, agent, and instruction files install as plain files; only the directory layout differs per tool. INSTALL.md documents every path and ships a one-shot script (scripts/install-adr-kit.sh style) that lays the files down for all four tool families at once. Quick orientation:
| Tool | Target layout |
|---|---|
| OpenAI Codex CLI | .codex/skills/, .codex/agents/, .codex/instructions/ (or paste into AGENTS.md) |
| Cursor | .cursor/skills/, .cursor/rules/*.mdc |
| GitHub Copilot | .github/skills/, .github/agents/, .github/instructions/ |
| Claude Cowork | shares the .claude/ convention with Claude Code |
| Anything else | file-based config dir, or paste SKILL.md into the system prompt |
On top of the file install, every tool that speaks MCP (Cursor, Cline, Windsurf, Copilot, Codex) can connect to the bundled MCP server for the enforcement and context tools; see below.
The CLI engines under bin/ run anywhere with Python 3.9+, no pip install, so enforcement in CI works regardless of which editor your team uses.
Three layers, each with a clear path:
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimnpx claudepluginhub rvdbreemen/adr-kit --plugin adr-kitComprehensive skill pack with 66 specialized skills for full-stack developers: 12 language experts (Python, TypeScript, Go, Rust, C++, Swift, Kotlin, C#, PHP, Java, SQL, JavaScript), 10 backend frameworks, 6 frontend/mobile, plus infrastructure, DevOps, security, and testing. Features progressive disclosure architecture for 50% faster loading.
Upstash Context7 MCP server for up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.
Harness-native ECC operator layer - 67 agents, 271 skills, 92 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses
Develop, test, build, and deploy Godot 4.x games with Claude Code. Includes GdUnit4 testing, web/desktop exports, CI/CD pipelines, and deployment to Vercel/GitHub Pages/itch.io.
Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review
Access thousands of AI prompts and skills directly in your AI coding assistant. Search prompts, discover skills, save your own, and improve prompts with AI.