adrkit

Decision memory for human- and agent-authored plans — architecture decision records that are machine-readable, enforceable in CI, and legible to agents, without leaving git.

Most ADR tooling is a markdown template and a static site generator. That records a decision; it doesn't make the decision do anything. adrkit treats a record as typed data with a markdown body and adds one field — affects — so a tool can answer "which decisions govern this pull request?" and put the answer where the next decision is being made.

Decision governance, not generated documentation

Generated knowledge systems answer "how does the system work now?" adrkit answers "what did people decide, what alternatives were rejected, and which decisions govern this change?" ADR-0037 sets that boundary: generated knowledge systems are downstream read models of adrkit's human-reviewed decision corpus, never decision authorities.

Tools such as OpenWiki can consume ADRs as evidence and turn them into browsable current-state documentation. That is complementary to adrkit: the generated wiki is a downstream read model, while the reviewed records in git retain authority over decision lifecycle and typed relationships. Machine verification of generated content is not human ratification of a decision.

See the provisional generated-knowledge guide for the OpenWiki setup being evaluated and the ownership boundary ADR-0037 sets between the two tools.

Quickstart

The CLI is published as @adrkit/cli and exposes the adr binary. Published artifacts target Node 22+:

npx @adrkit/cli lint                 # validate the corpus in docs/adr
npx @adrkit/cli explain src/payments/api.ts   # which decisions govern this file?

Or add it to a project (Bun-first repos can use bun add -D @adrkit/cli / bunx):

npm i -D @adrkit/cli

The pure library surfaces install independently: npm i @adrkit/core @adrkit/evaluator.

See the Quickstart guide and the full command reference.

Choose a starting point

Container usage

Beginning with the first lockstep release containing ADR-0032, releases are published as a multi-architecture OCI image at ghcr.io/mbeacom/adrkit. Pin an immutable vX.Y.Z tag in automation; vX and latest move only after that lockstep release has completed:

docker run --rm --read-only --network none \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z lint

docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z mcp

The MCP command keeps stdin open because MCP uses stdio. Its repository mount is read-only, matching the server contract; use an absolute host path in MCP client configuration. For CLI commands that intentionally write (new, or migrate without --dry-run), omit --read-only and the mount's :ro suffix. The image runs as the non-root node user; on a host with a different UID/GID, add --user "$(id -u):$(id -g)". On SELinux hosts, add the appropriate bind-mount label (for example, :Z).

The default image treats an unrecognized selector as an adr subcommand. Explicit selectors are cli/adr/adrkit, mcp/adrkit-mcp, ci/adrkit-ci, and queue-action/adrkit-queue-action. The default --help describes these selectors; cli --help opens the CLI command reference. The container also reserves -h, container-help, and --container-help; CLI help subcommands such as help lint otherwise pass through unchanged.

Build the same source locally with Docker or Podman. Purpose-specific cli, mcp, ci, and queue-action targets are isolated for local policy and SBOM inspection; the registry publishes only the all-in-one adrkit target:

docker build -f Containerfile -t adrkit:local .
docker build -f Containerfile --target mcp -t adrkit-mcp:local .
docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  adrkit-mcp:local

The two CI entry points preserve the existing GitHub Actions runtime contract: they expect GITHUB_WORKSPACE, the event payload and repository environment, INPUT_* values, and a token. For hosted GitHub Actions, the repository-backed Actions remain the simpler interface: mbeacom/adrkit/packages/ci@v0 and mbeacom/adrkit/packages/ci/queue@v0. Container publication and recovery are documented in docs/RELEASING.md.

The governing-decisions Action also has a repository-root entry point for its GitHub Marketplace listing. That root form is available beginning with v0.13.0; the existing packages/ci form remains supported. GitHub lists only root Action metadata, so the queue Action stays at its nested path.

What it looks like

adr queue emits the review backlog as a deterministic, read-only projection of the corpus — byte-for-byte identical for identical inputs:

# ARB Queue — 2026-07-25

Corpus fingerprint: `96e7f3185c5bb89bd1c87e10a28dcbef66703f381d3f14ea486ceaf29903cb00`
7 item(s) | 0 corpus finding(s) | 0 item(s) with findings

## Queue Items

| # | ID | Title | Tier | SLA State | Deadline | Approvals | Objections |
|---|----|-------|------|-----------|----------|-----------|------------|
| 1 | `0005` | Gate proposals with a deterministic-first evaluator … | arb | within-sla | 2027-01-18 | 0/- | 0 |
| 2 | `0015` | Validate descriptors against Backstage field formats … | arb | within-sla | 2027-01-25 | 0/- | 0 |

In CI, the @adrkit/ci Action comments the governing decisions on the PRs that touch them — read-only, comment-only, no database, no approval. See Use in CI.

For agents: the MCP server

The most differentiated hook: @adrkit/mcp is a local, read-only Model Context Protocol server that lets an agent retrieve prior decisions — including the rejected and superseded ones — before proposing something already tried. No writes, no HTTP/auth, no model, embedding, or network access, and no persistent index. It exposes exactly four tools:

Run it against a repository's corpus:

npx @adrkit/mcp             # or the adrkit-mcp bin
adrkit-mcp --cwd /path/to/repo --dir docs/adr

--cwd (env ADRKIT_MCP_CWD) must be a Git worktree root; --dir (env ADRKIT_MCP_DIR, default docs/adr) is resolved within it. stdout carries only JSON-RPC frames; diagnostics go to stderr; the graveyard is included by default. See the MCP setup guide and packages/mcp/README.md for the full tool contracts.

For spec-driven workflows: the Spec Kit extension

Spec Kit takes you from specify to plan to tasks to implement. What it does not do is check the plan it just produced against the decisions you already made, or record the new decisions that plan contains — so every feature starts from an empty context and re-litigates settled questions.

@adrkit/spec-kit closes that loop: