@rvdbreemen/adr-kit-opencode 0.52.2 → 0.53.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +12 -8
- package/bin/adr-mcp +96 -4
- package/bin/adr_doctor_probes.py +2 -0
- package/instructions/ADR-guide.md +64 -11
- package/package.json +1 -1
- package/templates/adr-kit-guide.md +1 -1
- package/templates/cc-settings/guardian-hook-entry.json +1 -1
- package/templates/githooks/pre-commit +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "adr-kit",
|
|
3
3
|
"description": "Architecture Decision Record toolkit for AI coding agents: bootstrap, multi-format authoring, bounded deterministic enforcement, lifecycle workflows, context injection, generated graph indexes, and local health checks.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.53.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Robert van den Breemen",
|
|
7
7
|
"url": "https://github.com/rvdbreemen"
|
package/README.md
CHANGED
|
@@ -307,12 +307,12 @@ configured:
|
|
|
307
307
|
}
|
|
308
308
|
```
|
|
309
309
|
|
|
310
|
-
For another project, use the published package for v0.52.
|
|
310
|
+
For another project, use the published package for v0.52.0:
|
|
311
311
|
|
|
312
312
|
```json
|
|
313
313
|
{
|
|
314
314
|
"$schema": "https://opencode.ai/config.json",
|
|
315
|
-
"plugin": ["@rvdbreemen/adr-kit-opencode@0.52.
|
|
315
|
+
"plugin": ["@rvdbreemen/adr-kit-opencode@0.52.0"]
|
|
316
316
|
}
|
|
317
317
|
```
|
|
318
318
|
|
|
@@ -434,7 +434,7 @@ Three layers, each with a clear path:
|
|
|
434
434
|
A deliberately thin MCP server (stdio, newline-delimited JSON-RPC 2.0, Python
|
|
435
435
|
stdlib only, zero dependencies) that exposes the guardrails to Claude Code,
|
|
436
436
|
OpenAI Codex, GitHub Copilot CLI, or another compatible local stdio MCP
|
|
437
|
-
client.
|
|
437
|
+
client. Seven tools, all key-free:
|
|
438
438
|
|
|
439
439
|
| Tool | Arguments | Wraps |
|
|
440
440
|
| --- | --- | --- |
|
|
@@ -443,6 +443,8 @@ client. Five tools, all key-free:
|
|
|
443
443
|
| `adr_status` | none | `adr-status --format json` |
|
|
444
444
|
| `adr_quality` | `adr_id?` (string) | `adr-quality --format json` per ADR |
|
|
445
445
|
| `adr_readiness` | `adr_id?`, `all_proposed?`, `changed_paths?`, `source_text?`, `today?` | shared read-only readiness model |
|
|
446
|
+
| `adr_lint` | `strict?` (boolean) | `adr-lint --format json` |
|
|
447
|
+
| `adr_related` | `adr_id` (string) | `adr-related --format json` |
|
|
446
448
|
|
|
447
449
|
```bash
|
|
448
450
|
# Claude Code
|
|
@@ -462,10 +464,12 @@ For another stdio client, place the following in its MCP configuration:
|
|
|
462
464
|
}
|
|
463
465
|
```
|
|
464
466
|
|
|
465
|
-
Why only
|
|
467
|
+
Why only seven tools? Contrast is the feature: adr-kit ships the smallest
|
|
466
468
|
surface that carries the guardrails and readiness facts, and nothing that needs
|
|
467
|
-
an API key.
|
|
468
|
-
|
|
469
|
+
an API key. ADR-040 records the admission criterion — read-only, deterministic
|
|
470
|
+
and key-free, agent-query-shaped, and covering a development-cycle step no
|
|
471
|
+
exposed tool already covers. Grilling itself stays in the client session so an
|
|
472
|
+
engineer or architect remains part of the decision.
|
|
469
473
|
|
|
470
474
|
## Slash commands
|
|
471
475
|
|
|
@@ -665,7 +669,7 @@ jobs:
|
|
|
665
669
|
- uses: actions/checkout@v4
|
|
666
670
|
with:
|
|
667
671
|
fetch-depth: 0 # both sides of the diff must be available
|
|
668
|
-
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.
|
|
672
|
+
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.53.0
|
|
669
673
|
with:
|
|
670
674
|
adr-dir: docs/adr/
|
|
671
675
|
```
|
|
@@ -679,7 +683,7 @@ The action also takes `max-diff-bytes` (default 32 MiB, available from the relea
|
|
|
679
683
|
```yaml
|
|
680
684
|
repos:
|
|
681
685
|
- repo: https://github.com/rvdbreemen/adr-kit
|
|
682
|
-
rev: v0.
|
|
686
|
+
rev: v0.53.0
|
|
683
687
|
hooks:
|
|
684
688
|
- id: adr-judge
|
|
685
689
|
```
|
package/bin/adr-mcp
CHANGED
|
@@ -26,7 +26,7 @@ the same answer. That is deliberate - the spec forbids relying on prior
|
|
|
26
26
|
requests over the same connection to establish context. See ADR-016 and
|
|
27
27
|
docs/research/2026-07-29-mcp-2026-07-28-revision.md.
|
|
28
28
|
|
|
29
|
-
Exposes exactly
|
|
29
|
+
Exposes exactly 7 tools, each a subprocess call into a sibling bin/ script:
|
|
30
30
|
|
|
31
31
|
adr_context {query, limit?, paths?, components?, symbols?, topics?,
|
|
32
32
|
statuses?, authorities?, include_history?, strict_index?}
|
|
@@ -37,6 +37,12 @@ Exposes exactly 5 tools, each a subprocess call into a sibling bin/ script:
|
|
|
37
37
|
adr_quality {adr_id?} -> bin/adr-quality --format json per ADR
|
|
38
38
|
adr_readiness {adr_id?, all_proposed?, base?, head?, today?}
|
|
39
39
|
-> bin/adr-readiness --format json
|
|
40
|
+
adr_lint {strict?} -> bin/adr-lint --format json
|
|
41
|
+
adr_related {adr_id} -> bin/adr-related --format json
|
|
42
|
+
|
|
43
|
+
Admission is governed by ADR-040: a CLI joins this surface only when it is
|
|
44
|
+
read-only, deterministic and key-free, agent-query-shaped, and covers an
|
|
45
|
+
agent-guide cycle step no exposed tool already covers.
|
|
40
46
|
|
|
41
47
|
adr-suggest is intentionally NOT exposed: it is an LLM-only advisory (its
|
|
42
48
|
deterministic part is just a docs-only skip filter), and this server stays
|
|
@@ -112,9 +118,10 @@ MODERN_CACHE_SCOPE = "public"
|
|
|
112
118
|
|
|
113
119
|
MODERN_INSTRUCTIONS = (
|
|
114
120
|
"adr-kit: read-only Architecture Decision Record tooling. Call tools/list "
|
|
115
|
-
"for the
|
|
116
|
-
"adr_status, adr_quality, adr_readiness). Every
|
|
117
|
-
"project_root and adr_dir arguments to select the
|
|
121
|
+
"for the seven deterministic, key-free tools (adr_context, adr_judge, "
|
|
122
|
+
"adr_status, adr_quality, adr_readiness, adr_lint, adr_related). Every "
|
|
123
|
+
"tool accepts optional project_root and adr_dir arguments to select the "
|
|
124
|
+
"active workspace."
|
|
118
125
|
)
|
|
119
126
|
|
|
120
127
|
# Per-tool subprocess timeout. The wrapped CLIs are regex-only and fast;
|
|
@@ -331,6 +338,46 @@ TOOL_DEFINITIONS: List[Dict[str, Any]] = [
|
|
|
331
338
|
},
|
|
332
339
|
},
|
|
333
340
|
},
|
|
341
|
+
{
|
|
342
|
+
"name": "adr_lint",
|
|
343
|
+
"description": (
|
|
344
|
+
"Lint the ADR set against the deterministic verification gates. "
|
|
345
|
+
"Read-only, key-free. Returns the adr-lint JSON report and exit "
|
|
346
|
+
"status (0 = clean, 1 = failing findings)."
|
|
347
|
+
),
|
|
348
|
+
"inputSchema": {
|
|
349
|
+
"type": "object",
|
|
350
|
+
"properties": {
|
|
351
|
+
"strict": {
|
|
352
|
+
"type": "boolean",
|
|
353
|
+
"description": (
|
|
354
|
+
"CI governance mode: enable the schema gate and make "
|
|
355
|
+
"findings FAIL. False by default."
|
|
356
|
+
),
|
|
357
|
+
},
|
|
358
|
+
**WORKSPACE_PROPERTIES,
|
|
359
|
+
},
|
|
360
|
+
},
|
|
361
|
+
},
|
|
362
|
+
{
|
|
363
|
+
"name": "adr_related",
|
|
364
|
+
"description": (
|
|
365
|
+
"Show the dependency graph (inbound + outbound edges) for one "
|
|
366
|
+
"ADR: related decisions, supersession links, mentions, and "
|
|
367
|
+
"dangling references. Read-only, deterministic. Returns JSON."
|
|
368
|
+
),
|
|
369
|
+
"inputSchema": {
|
|
370
|
+
"type": "object",
|
|
371
|
+
"properties": {
|
|
372
|
+
"adr_id": {
|
|
373
|
+
"type": "string",
|
|
374
|
+
"description": "ADR identifier such as 'ADR-007', 'adr-7' or '7'.",
|
|
375
|
+
},
|
|
376
|
+
**WORKSPACE_PROPERTIES,
|
|
377
|
+
},
|
|
378
|
+
"required": ["adr_id"],
|
|
379
|
+
},
|
|
380
|
+
},
|
|
334
381
|
]
|
|
335
382
|
|
|
336
383
|
|
|
@@ -678,12 +725,57 @@ def tool_adr_readiness(
|
|
|
678
725
|
return _text_result(_parse_json_or_raw(out))
|
|
679
726
|
|
|
680
727
|
|
|
728
|
+
def tool_adr_lint(arguments: Dict[str, Any], root: Path, adr_dir: Path) -> Dict[str, Any]:
|
|
729
|
+
try:
|
|
730
|
+
root, adr_dir = _call_paths(arguments, root, adr_dir)
|
|
731
|
+
except ValueError as exc:
|
|
732
|
+
return _text_result(f"adr_lint: {exc}", is_error=True)
|
|
733
|
+
strict = arguments.get("strict", False)
|
|
734
|
+
if not isinstance(strict, bool):
|
|
735
|
+
return _text_result("adr_lint: 'strict' must be a boolean", is_error=True)
|
|
736
|
+
args = ["--format", "json", "--repo-root", str(root)]
|
|
737
|
+
if strict:
|
|
738
|
+
args.append("--strict")
|
|
739
|
+
args.append(str(adr_dir))
|
|
740
|
+
rc, out, err = run_cli("adr-lint", args, root)
|
|
741
|
+
if rc == 2:
|
|
742
|
+
return _text_result(
|
|
743
|
+
f"adr-lint exited 2 (config/input error): {err.strip() or out.strip()}",
|
|
744
|
+
is_error=True,
|
|
745
|
+
)
|
|
746
|
+
# rc 0 (clean) and rc 1 (failing findings) are both valid lint outcomes.
|
|
747
|
+
payload = {"exit_code": rc, "verdict": "findings" if rc == 1 else "ok",
|
|
748
|
+
"result": _parse_json_or_raw(out)}
|
|
749
|
+
return _text_result(payload)
|
|
750
|
+
|
|
751
|
+
|
|
752
|
+
def tool_adr_related(arguments: Dict[str, Any], root: Path, adr_dir: Path) -> Dict[str, Any]:
|
|
753
|
+
try:
|
|
754
|
+
root, adr_dir = _call_paths(arguments, root, adr_dir)
|
|
755
|
+
except ValueError as exc:
|
|
756
|
+
return _text_result(f"adr_related: {exc}", is_error=True)
|
|
757
|
+
adr_id = arguments.get("adr_id")
|
|
758
|
+
if not isinstance(adr_id, str) or not adr_id.strip():
|
|
759
|
+
return _text_result(
|
|
760
|
+
"adr_related: 'adr_id' must be a non-empty string", is_error=True
|
|
761
|
+
)
|
|
762
|
+
args = ["--format", "json", "--adr-dir", str(adr_dir), adr_id]
|
|
763
|
+
rc, out, err = run_cli("adr-related", args, root)
|
|
764
|
+
if rc != 0:
|
|
765
|
+
return _text_result(
|
|
766
|
+
f"adr-related exited {rc}: {err.strip() or out.strip()}", is_error=True
|
|
767
|
+
)
|
|
768
|
+
return _text_result(_parse_json_or_raw(out))
|
|
769
|
+
|
|
770
|
+
|
|
681
771
|
TOOL_HANDLERS = {
|
|
682
772
|
"adr_context": tool_adr_context,
|
|
683
773
|
"adr_judge": tool_adr_judge,
|
|
684
774
|
"adr_status": tool_adr_status,
|
|
685
775
|
"adr_quality": tool_adr_quality,
|
|
686
776
|
"adr_readiness": tool_adr_readiness,
|
|
777
|
+
"adr_lint": tool_adr_lint,
|
|
778
|
+
"adr_related": tool_adr_related,
|
|
687
779
|
}
|
|
688
780
|
|
|
689
781
|
|
package/bin/adr_doctor_probes.py
CHANGED
|
@@ -4,31 +4,84 @@
|
|
|
4
4
|
# ADR Kit agent guide
|
|
5
5
|
|
|
6
6
|
Architecture decisions live in `docs/adr/`. Read the source ADR before treating
|
|
7
|
-
a generated summary as binding.
|
|
7
|
+
a generated summary as binding. This guide is written so an agent can operate
|
|
8
|
+
adr-kit autonomously: every step names the tool to call, what comes back, and
|
|
9
|
+
how to react. Steps marked **human-gated** must never be performed without an
|
|
10
|
+
explicit human decision.
|
|
11
|
+
|
|
12
|
+
## Tool surface
|
|
13
|
+
|
|
14
|
+
Every step below is callable two ways. Shell-less clients use the MCP tools;
|
|
15
|
+
clients with a shell may use the CLI directly. Both delegate to the same
|
|
16
|
+
deterministic engines, so results are identical.
|
|
17
|
+
|
|
18
|
+
| Phase | MCP tool | CLI equivalent | Mutates? |
|
|
19
|
+
| --- | --- | --- | --- |
|
|
20
|
+
| Find governing ADRs | `adr_context` | `bin/adr-context --format json` | no |
|
|
21
|
+
| Follow ADR graph links | `adr_related` | `bin/adr-related --format json` | no |
|
|
22
|
+
| Judge a diff | `adr_judge` | `bin/adr-judge --json` | no |
|
|
23
|
+
| Lint the ADR set | `adr_lint` | `bin/adr-lint --format json` | no |
|
|
24
|
+
| Score ADR quality | `adr_quality` | `bin/adr-quality --format json` | no |
|
|
25
|
+
| Check lifecycle readiness | `adr_readiness` | `bin/adr-readiness --format json` | no |
|
|
26
|
+
| Repository health | `adr_status` | `bin/adr-status --format json` | no |
|
|
27
|
+
| Create / edit / accept ADRs | — (deliberately absent) | `bin/adr new`, `answer`, `relate`, ... | yes |
|
|
28
|
+
|
|
29
|
+
The MCP server is read-only by design (ADR-011, ADR-040): no MCP tool can
|
|
30
|
+
create, edit, accept, or index an ADR. Lifecycle mutation always goes through
|
|
31
|
+
the CLI, and acceptance always goes through a human.
|
|
8
32
|
|
|
9
33
|
## Before implementation
|
|
10
34
|
|
|
11
|
-
1. Query the task with `
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
35
|
+
1. Query the task with `adr_context` (MCP) or `bin/adr-context`. Pass the task
|
|
36
|
+
description as `query`; add `paths` for the files you expect to touch.
|
|
37
|
+
2. Read every returned Accepted ADR at the source, and call `adr_related` on
|
|
38
|
+
each id you rely on to see supersession, related decisions, and dangling
|
|
39
|
+
links. A superseded ADR is history, not guidance: follow the successor.
|
|
40
|
+
3. If the work introduces or changes a long-lived decision, create a Proposed
|
|
41
|
+
record with `bin/adr new` (or `adr-kit:adr`) before writing the code.
|
|
42
|
+
**Human-gated:** the record stays Proposed until a human accepts it; never
|
|
43
|
+
run `bin/adr accept` on your own initiative.
|
|
15
44
|
|
|
16
45
|
## During implementation
|
|
17
46
|
|
|
18
47
|
- Treat hook-provided ADR context as advisory steering. Hooks fail open.
|
|
19
48
|
- Treat deterministic pre-commit enforcement as the blocking floor.
|
|
20
49
|
- Never rewrite an Accepted ADR. Create a Proposed successor and use the
|
|
21
|
-
supersession lifecycle.
|
|
50
|
+
supersession lifecycle (`bin/adr supersede`, human-gated like acceptance).
|
|
22
51
|
- Keep generated indexes and client artifacts deterministic; edit their
|
|
23
52
|
canonical sources instead.
|
|
24
53
|
|
|
25
54
|
## Before completion
|
|
26
55
|
|
|
27
|
-
1. Run
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
56
|
+
1. Run `adr_lint` with `strict: true` (MCP) or `bin/adr-lint --strict`.
|
|
57
|
+
React: `verdict: ok` proceeds; `verdict: findings` lists failing files and
|
|
58
|
+
findings — fix the ADR content, never weaken the gate. Exit 2 is a config
|
|
59
|
+
error: report it, do not work around it.
|
|
60
|
+
2. After ADR changes, regenerate `docs/adr/ADR-INDEX.md`,
|
|
61
|
+
`docs/adr/ADR-INDEX.json`, and the generated README block with
|
|
62
|
+
`bin/adr-index docs/adr` (CLI only; index generation mutates).
|
|
63
|
+
3. Judge the staged diff with `adr_judge` (MCP, pass the unified diff) or
|
|
64
|
+
`bin/adr-judge`. React: `verdict: ok` proceeds; `verdict: violation` names
|
|
65
|
+
the ADR and rule per finding — change the code to comply, or propose a
|
|
66
|
+
successor ADR if the decision itself is wrong. Never commit past a
|
|
67
|
+
violation.
|
|
68
|
+
4. For a Proposed ADR, check `adr_readiness`. React: `classification` tells
|
|
69
|
+
you what is missing (open questions, implementation links, quality). Fix
|
|
70
|
+
what is mechanical; leave acceptance to a human.
|
|
71
|
+
5. Record the decision, evidence, and verification in the project task.
|
|
72
|
+
|
|
73
|
+
## Human-gated actions
|
|
74
|
+
|
|
75
|
+
These require an explicit human decision, every time:
|
|
76
|
+
|
|
77
|
+
- `bin/adr accept` (and `--confirm`): acceptance writes a person's name into
|
|
78
|
+
an immutable status history (ADR-011, ADR-027).
|
|
79
|
+
- `bin/adr supersede`, `bin/adr reject`: same lifecycle authority.
|
|
80
|
+
- Choosing or changing the lifecycle signer (`bin/adr signer --set`).
|
|
81
|
+
|
|
82
|
+
Everything else in the tables above is safe for autonomous use: the read-only
|
|
83
|
+
tools always, and the mutating authoring commands (`new`, `answer`, `relate`,
|
|
84
|
+
`adr-index`) when the task itself calls for them.
|
|
32
85
|
|
|
33
86
|
## Ownership
|
|
34
87
|
|
package/package.json
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- adr-kit-guide v0.
|
|
1
|
+
<!-- adr-kit-guide v0.53.0 -->
|
|
2
2
|
<!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
|
|
3
3
|
<!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
|
|
4
4
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"_comment": "ADR Guardian SessionStart hook entry for .claude/settings.json",
|
|
3
3
|
"_note": "Add this entry under hooks.SessionStart[0].hooks[] in the project's .claude/settings.json.",
|
|
4
4
|
"_remove_marker": "adr-guardian-session-start",
|
|
5
|
-
"_wrapper_version": "0.
|
|
5
|
+
"_wrapper_version": "0.53.0",
|
|
6
6
|
"type": "command",
|
|
7
7
|
"command": "ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ 2>/dev/null | sort -V | tail -1) && [ -n \"$ADR_KIT\" ] && _PY=$(command -v python3 || command -v python || command -v py) && [ -n \"$_PY\" ] && \"$_PY\" \"$ADR_KIT/bin/adr-guardian\" check 2>/dev/null || true",
|
|
8
8
|
"timeout": 10
|
|
@@ -52,7 +52,7 @@ set -e
|
|
|
52
52
|
# freezes at install time. adr-guardian compares this stamp against the
|
|
53
53
|
# installed plugin version and nudges /adr-kit:upgrade when the wrapper lags.
|
|
54
54
|
# Maintained by scripts/bump-version.py; do not edit by hand.
|
|
55
|
-
ADR_KIT_WRAPPER_VERSION="0.
|
|
55
|
+
ADR_KIT_WRAPPER_VERSION="0.53.0"
|
|
56
56
|
|
|
57
57
|
if [ "${ADR_KIT_HOOK_DISABLE:-0}" = "1" ]; then
|
|
58
58
|
echo "[adr-kit] hook disabled for this commit (ADR_KIT_HOOK_DISABLE=1)" >&2
|