Decisions that reach the code.
adrkit turns architecture decisions into typed, locatable records — so the constraints your team accepted remain visible where the next change is made.
The schema, resolver, CLI, CI comments, deterministic Pass 0 evaluator, and read-only MCP server are all published. Evaluator Passes 1–3 and external validation of the ARB queue are the parts still marked open.
@adrkit/core, @adrkit/cli, @adrkit/evaluator, and @adrkit/mcp are on npm, plus the independently versioned @adrkit/spec-kit extension; the CI Action ships at mbeacom/adrkit/packages/ci@v0.
Corpus validation, path explanation, graphing, migration, the ARB queue, PR comments, the read-only MCP server, the Spec Kit extension, and the deterministic Pass 0 evaluator.
Multi-pass evaluation and Backstage catalog integration are in development.
A decision should not disappear after the meeting.
Six months later, the same choice gets debated again. The code has drifted. The people — and now the agents — proposing the next change cannot see what was already accepted or rejected.
Most ADR tools preserve prose. adrkit preserves consequence.
Proof in the repository, not the pitch.
The current CLI reads typed frontmatter, validates the corpus, resolves what a record governs, and keeps migration additive.
adr lintWorks todayValidate the corpus
Check every record against the schema, enforce unique ids, catch dangling links, and flag accepted records that declare conflicts.
adr explainWorks todayLocate governing decisions
Give adrkit a path. It returns every decision that governs it and the matcher that fired — as readable output or JSON.
adr graphWorks todayInspect the decision graph
Inspect a focused terminal view, render a GitHub-ready Mermaid map, or emit deterministic Graphviz DOT and JSON instead of leaving relationships trapped in individual files.
adr migrate --from madrWorks todayAdopt without a rewrite
Add adrkit fields to an existing MADR corpus in place. The migration is additive and preserves current tooling and prose.
One field makes a decision locatable.
affects declares what a record governs. That turns an ADR from passive documentation into data a tool can resolve.
Declare the reach
A record names the paths, packages, APIs, resources, or data it governs.
Resolve the match
A pure function compares a changed target with the corpus and explains every match.
Surface the constraint
adr explainprints it, the CI Action comments it on the pull request that touches it, and the MCP server hands it to an agent before it drafts a plan.
Shipped, and honestly still ahead.
The surfaces once listed here as planned have shipped — the CI comment and Pass 0 in v0.1.0, agent retrieval in v0.2.0, and the Spec Kit extension since, on its own version line. What remains is stated plainly — no item claims more than the repository proves.
- Works today
Pull-request context
The
packages/ciAction comments the accepted decisions governing touched files, read-only, on the default token. - Works today
Agent retrieval
The
@adrkit/mcpserver exposes accepted and rejected decisions over stdio, so a new plan does not repeat an old argument. - Works today
Deterministic evaluation
adr evaluateruns the model-free Pass 0 rubric and routes to a named human — it never approves. - Works today
Spec-driven planning
@adrkit/spec-kitadds three namespaced commands to a Spec Kit project, so a plan is written against the decisions that govern it. - Planned
Evaluator Passes 1–3
Only the deterministic Pass 0 is built. The later probabilistic passes are not.
- In development
Backstage catalog integration
The repository contains the adapter boundaries and catalog-envelope work; the integration is not released yet.
It never approves anything. It routes, and humans decide.
adrkit governs itself. The repository’s first commit is its own decision corpus, including the trade-offs and rejected alternatives behind the project.
Read the decisions that built adrkit