adrkit

Memoria de decisiones para planes escritos por humanos y agentes — registros de decisiones de arquitectura que son legibles por máquina, aplicables en CI y comprensibles para agentes, sin salir de git.

La mayoría de las herramientas ADR son una plantilla de markdown y un generador de sitios estáticos. Eso registra una decisión; no hace que la decisión haga nada. adrkit trata un registro como datos tipados con un cuerpo markdown y añade un campo — affects — para que una herramienta pueda responder "¿qué decisiones rigen esta pull request?" y poner la respuesta donde se está tomando la siguiente decisión.

Inicio rápido

La CLI se publica como @adrkit/cli y expone el binario adr. Los artefactos publicados están dirigidos a 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?

O añádelo a un proyecto (los repositorios que usan Bun pueden usar bun add -D @adrkit/cli / bunx):

npm i -D @adrkit/cli

La biblioteca pura se instala de forma independiente: npm i @adrkit/core @adrkit/evaluator.

Consulta la guía de inicio rápido y la referencia completa de comandos.

Related MCP server: agentic-os-mcp

Elige un punto de partida

Uso en contenedor

A partir de la primera versión en pasos que contenga ADR-0032, las versiones se publican como una imagen OCI multiarquitectura en ghcr.io/mbeacom/adrkit. Fija una etiqueta inmutable vX.Y.Z en la automatización; vX y latest solo se mueven después de que esa versión en pasos se haya completado:

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

El comando MCP mantiene stdin abierto porque MCP usa stdio. Su montaje de repositorio es de solo lectura, según el contrato del servidor; usa una ruta absoluta del host en la configuración del cliente MCP. Para comandos CLI que escriben intencionalmente (new, o migrate sin --dry-run), omite --read-only y el sufijo :ro del montaje. La imagen se ejecuta como el usuario no root node; en un host con un UID/GID diferente, añade --user "$(id -u):$(id -g)". En hosts SELinux, añade la etiqueta de montaje bind adecuada (por ejemplo, :Z).

La imagen predeterminada trata un selector no reconocido como un subcomando adr. Los selectores explícitos son cli/adr/adrkit, mcp/adrkit-mcp, ci/adrkit-ci y queue-action/adrkit-queue-action. El --help predeterminado describe estos selectores; cli --help abre la referencia de comandos CLI. El contenedor también reserva -h, container-help y --container-help; los subcomandos de ayuda CLI como help lint pasan sin cambios.

Construye la misma fuente localmente con Docker o Podman. Los objetivos específicos cli, mcp, ci y queue-action están aislados para políticas locales e inspección de SBOM; el registro publica solo el objetivo todo-en-uno adrkit:

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

Los dos puntos de entrada de CI preservan el contrato de ejecución existente de GitHub Actions: esperan GITHUB_WORKSPACE, la carga útil del evento y el entorno del repositorio, los valores INPUT_* y un token. Para GitHub Actions alojado, las Actions respaldadas por repositorio siguen siendo la interfaz más simple: mbeacom/adrkit/packages/ci@v0 y mbeacom/adrkit/packages/ci/queue@v0. La publicación y recuperación del contenedor están documentadas en docs/RELEASING.md.

Cómo se ve

adr queue emite el backlog de revisión como una proyección determinista y de solo lectura del corpus — idéntica byte por byte para entradas idénticas:

# 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 |

En CI, la Action @adrkit/ci comenta las decisiones que rigen en las PRs que las tocan — solo lectura, solo comentarios, sin base de datos, sin aprobación. Consulta Uso en CI.

Para agentes: el servidor MCP

El gancho más diferenciador: @adrkit/mcp es un servidor local, de solo lectura Model Context Protocol que permite a un agente recuperar decisiones previas — incluidas las rechazadas y las superadas — antes de proponer algo ya intentado. Sin escrituras, sin HTTP/auth, sin modelo, incrustaciones o acceso a red, y sin índice persistente. Expone exactamente cuatro herramientas:

Ejecútalo contra el corpus de un repositorio:

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

--cwd (env ADRKIT_MCP_CWD) debe ser la raíz de un worktree de Git; --dir (env ADRKIT_MCP_DIR, por defecto docs/adr) se resuelve dentro de ella. stdout lleva solo marcos JSON-RPC; los diagnósticos van a stderr; el cementerio se incluye por defecto. Consulta la guía de configuración de MCP y packages/mcp/README.md para los contratos completos de las herramientas.

Para flujos de trabajo basados en especificaciones: la extensión Spec Kit

Spec Kit te lleva de specify a plan a tasks a implement. Lo que no hace es comprobar el plan que acaba de producir contra las decisiones que ya tomaste, ni registrar las nuevas decisiones que ese plan contiene — así que cada característica comienza desde un contexto vacío y re-litiga cuestiones ya resueltas.

@adrkit/spec-kit cierra ese bucle:

Además, un hook after_plan que ofrece ejecutar la comprobación. Es opcional por construcción, y los hooks solo pueden alcanzar comandos que no escriben — draft está deliberadamente inalcanzable desde cualquier hook, porque un hook en fase de plan que creara registros sin que se le pida fabricaría memoria de decisiones en lugar de registrarla.

Fijado a Spec Kit >=0.13.0,<0.16.0 y probado contra 0.13.0, 0.14.4 y 0.15.1. Está disponible en el catálogo comunitario de Spec Kit; consulta el README del paquete para la configuración.

Para cualquier agente de codificación: el plugin

Spec Kit es un flujo de trabajo. El lugar donde se escriben los planes ahora es dentro de un agente de codificación que no tiene idea de que tu corpus de decisiones existe.

packages/adapters/agent-plugin empaqueta el mismo bucle como componentes de agente portátiles — instalables en GitHub Copilot CLI, Claude Code, opencode y cualquier cosa que APM tenga como objetivo:

copilot plugin marketplace add mbeacom/adrkit && copilot plugin install adrkit@adrkit
/plugin marketplace add mbeacom/adrkit        # Claude Code, then /plugin install adrkit@adrkit
apm install mbeacom/adrkit/packages/adapters/agent-plugin --target opencode

Cada componente invoca la CLI adr, así que instálala también si aún no lo has hecho — npm i -g @adrkit/cli, o añade @adrkit/cli al proyecto. Los componentes la resuelven desde $ADRKIT_CLI, luego ./node_modules/.bin/adr, y luego PATH.

Deliberadamente no incluye ninguna configuración de MCP: Copilot CLI lanza los servidores MCP de un plugin fuera del espacio de trabajo y fuera de cualquier repositorio Git, por lo que el servidor de adrkit sale durante initialize. En su lugar, MCP se conecta por proyecto — consulta el README del plugin para la configuración específica del host y ADR-0028. La expansión de backfill está autorizada por ADR-0034.

Estado: instalable hoy desde este repositorio y con versionado independiente de los paquetes npm. Hace que el bucle context -> check -> backfill -> draft esté disponible dentro de los hosts actuales de agentes de codificación.

El flujo de trabajo de backfill es de solo lectura hasta que un humano selecciona un candidato. Consulta la guía para el enrutamiento de fuentes, los umbrales de evidencia, el tratamiento de estados y el traspaso /adr-backfill → /adr-draft.

Con versionado independiente según ADR-0007. El flujo de trabajo original de context/check/draft/queue está en el escalón 1 de ADR-0014 — cobertura unitaria y de contrato, más verificación de mantenedores contra los hosts instalados. La adición de backfill v0.2.0 está validada por contrato y con hosts estáticos, y cuenta con una ejecución funcional reciente de consumidor sintético de Copilot que demuestra la conciliación de candidatos y la ausencia de escrituras. No existe ninguna ejecución persistente de repositorio de referencia ni validación externa para el plugin.

El problema

Tu organización decide algo. Seis meses después nadie lo recuerda, la decisión se vuelve a cuestionar y el código se desvía de lo acordado. Ahora los agentes también escriben planes — más rápido de lo que cualquiera puede revisarlos, sin memoria de lo que ya se decidió y rechazó.

La idea

Trata un registro de decisión como datos tipados con cuerpo Markdown y dale un campo que lo cambia todo — affects, que declara qué gobierna la decisión:

---
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\\)/**"   # ( and ) are glob syntax — escape them
  - type: package
    pattern: "next@>=16"
---

Ahora una herramienta puede responder "¿qué decisiones gobiernan esta pull request?" — y poner la respuesta donde realmente se toma la siguiente decisión.

Qué hace

• adr lint — valida registros, detecta ciclos de sustitución y encuentra decisiones que se contradicen silenciosamente entre sí. Advierte cuando el markdown del directorio del corpus no es descubrible, de modo que "checked 0 records" nunca sea silencioso.

• adr migrate --from madr — adopta un corpus MADR existente en su lugar, de forma aditiva, sin romper tus herramientas actuales. Lee estado, fecha y decisores del frontmatter de MADR 3.x, las viñetas * Status: de MADR 2.x y las secciones ## Status de Nygard. --rename también renombra cada archivo a <id>-<slug>.md.

• adr explain <path> — imprime cada decisión que gobierna un archivo y por qué. Las decisiones llegan a un archivo en dos direcciones y la salida las mantiene separadas: el patrón affects del propio registro coincidió (via path: src/**), o el archivo declaró la decisión por sí mismo con un marcador @adr 0012 en un comentario (declared by src/sync.ts:3). Los marcadores permiten que affects permanezca acotado — los archivos definitorios — mientras que el código circundante se adhiere una línea a la vez, en cualquier lenguaje, sin cambios de esquema. Solo los registros accepted se notifican como gobernantes; las propuestas coincidentes y los registros superseded/rejected/deprecated se enumeran por separado.

• adr check <files...> — valida los registros cambiados y lista las decisiones que gobiernan un conjunto de archivos modificados, incluidas las declaraciones @adr entrantes. Las lecturas de marcadores están limitadas a 3,000 archivos / 16 lecturas concurrentes, 64 declaraciones por archivo y 10,000 declaraciones por lote, todo informado en --json; las afirmaciones de marcadores y las advertencias de escaneo nunca influyen en el código de salida.

• adr evaluate <proposal> --snapshot <bundle.json> --date YYYY-MM-DD — ejecuta el Pass 0 determinista y sin modelo sobre un ADR propuesto más un paquete de instantánea inmutable sin conexión. Aplica las once reglas de la rúbrica, escala en disparadores probados a un humano activo designado (o a un unresolved explícito), y devuelve un Pass0Report enriquecido más un evaluationPatch compatible con el esquema. No lee ningún modelo, red, reloj o (en la biblioteca) sistema de archivos, y enruta — nunca aprueba, persiste ni escribe.

• adr queue — emite la cola de operaciones ARB: una proyección determinista y de solo lectura de los metadatos review del corpus (niveles, estado de SLA, aprobaciones, objeciones) como Markdown o JSON QueueReport v1; también una Action de gestión de incidencias.

• Comentario de CI — la GitHub Action @adrkit/ci muestra las decisiones gobernantes en las PRs que las tocan o las declaran explícitamente; las coincidencias de patrones se muestran como via y las afirmaciones de marcadores escritas en la PR como declared by. El comentario también distingue los archivos de marcadores que no pudo inspeccionar, las declaraciones de marcadores omitidas por un límite de seguridad y las afirmaciones que leyó pero no pudo vincular. Todo es informativo: nunca hacen fallar el trabajo. Se ejecuta solo con el GITHUB_TOKEN predeterminado y se degrada (nunca falla el trabajo) ante un token de fork de solo lectura.

• Servidor MCP — permite a los agentes recuperar decisiones anteriores, incluidas las rechazadas, antes de proponer algo que ya se ha intentado.

Nunca aprueba nada. Enruta, y los humanos deciden.

Usa ambas CI Actions desde su tag major móvil (consulta Uso en CI):

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/checkout@v4
  - uses: mbeacom/adrkit/packages/ci@v0

¿Por qué no MADR simple — o "MADR estructurado"?

El frontmatter de adrkit es un superconjunto estricto de MADR, así que esto no es "en lugar de MADR" — puedes aplicar adr migrate --from madr a un corpus existente en su lugar. La diferencia es lo que ocurre después de que el registro exista.

Una plantilla — incluyendo una variante de MADR más estructurada — estandariza cómo escribes una decisión. No hace lo siguiente:

• aplicarlo en CI — adrkit resuelve affects y comenta las decisiones gobernantes en las PRs que modifican los archivos que gobiernan;

• responder "¿qué decisiones gobiernan esta PR?" — eso requiere un comparador puro y reproducible sobre campos affects tipados (ADR-0009), no prosa;

• permitir que un agente recupere el cementerio — el servidor MCP de solo lectura expone los registros rejected/superseded/deprecated para que un agente deje de volver a proponerlos.

Un esquema que puedas entregar a un linter, un resolvedor, un agente y un trabajo de CI es un artefacto distinto de una convención de encabezados. Esa es toda la tesis.

Estado del proyecto

adrkit sigue en pre-1.0, pero varias superficies están listas para usarse hoy. Esta tabla es la versión corta:

Compromisos de diseño

Estos se aplican, no son aspiracionales. Cada uno enlaza al registro que lo decidió.

Dogfooding

Cada decisión de este proyecto está gobernada por este proyecto. El primer commit del repositorio es su propio corpus de decisiones — consulta docs/adr/. La rúbrica del evaluador también está versionada aquí. El evaluador publicado implementa actualmente solo el Pass 0 determinista; los passes posteriores siguen siendo objetivos de diseño documentados, no comportamiento publicado.

Licencia

Apache-2.0 — consulta LICENSE.

Excepción: el contenido de schema/ se publica además bajo CC0. El esquema está pensado para convertirse en un contrato compartido; las implementaciones competidoras deberían poder adoptarlo sin ninguna consideración de licencia.

Cadena de herramientas

Construido con Bun — consulta ADR-0010. Bun es solo una dependencia de desarrollo. Nada de lo publicado por este proyecto lo requiere: la CLI, la GitHub Action y el servidor MCP están orientados a Node y se someten a pruebas de humo bajo Node 22 y 24 en CI.

Contribuciones

Consulta CONTRIBUTING.md, incluida la rampa de entrada "Tu primera PR". Las contribuciones requieren una firma de DCO y deben compilarse desde un clon limpio sin credenciales configuradas.