adrkit

Decision memory for human- and agent-authored plans. Machine-readable ADRs, enforceable in CI, legible to agents — without leaving git.

Quickstart JSON Schema View on GitHub

The problem

Your organization decides something. Six months later nobody remembers, the decision gets re-litigated, and the code drifts from what was agreed. Now agents write plans too — faster than anyone can review them, with no memory of what was already decided and rejected.

Most ADR tooling is a markdown template and a static site generator. That records decisions. It doesn’t make them do anything.

The idea

Treat a decision record as typed data with a markdown body, and give it one field that changes everything — affects, declaring what the decision governs:

---
id: "0042"
title: Use server-side rendering for authenticated routes
status: accepted
reversibility: one-way-door
blastRadius: cross-team
affects:
  - type: path
    pattern: "apps/web/app/(authed)/**"
  - type: package
    pattern: "next@>=16"
---

Now a tool can answer “which decisions govern this pull request?” — and put the answer where the next decision is actually being made.

What works today

Typed, validated records

A strict JSON Schema — a superset of MADR — that editors and CI in any language can validate against.

adr lint

Validate records against the schema, enforce unique ids, and flag dangling references or an accepted record that declares a conflict.

adr migrate --from madr

Adopt an existing MADR corpus in place, additively, without breaking your current tooling.

adr explain / graph

Print every decision governing a file and the matcher that fired, or emit the decision graph as DOT or JSON.

On the roadmap

CI comment

Surface governing decisions on the pull requests that touch them.

MCP server

Let agents retrieve prior decisions — including the rejected ones — before proposing something already tried.

Evaluator

Score proposals against a published rubric and route them; deterministic checks first, humans on the conditions that warrant them.

It never approves anything. It routes, and humans decide.

Design commitments

These are enforced, not aspirational — and the project governs itself with them. Each links to the record that decided it.

Browse the decision recordsadrkit's first commit is its own decision corpus. Every choice here is a typed ADR.