@rvdbreemen/adr-kit-opencode 0.52.0 → 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.
Files changed (83) hide show
  1. package/.claude-plugin/plugin.json +29 -29
  2. package/README.md +865 -850
  3. package/bin/adr +0 -0
  4. package/bin/adr-audit +0 -0
  5. package/bin/adr-context +0 -0
  6. package/bin/adr-discover +0 -0
  7. package/bin/adr-doctor +0 -0
  8. package/bin/adr-generate-scripts +0 -0
  9. package/bin/adr-grill-signal +0 -0
  10. package/bin/adr-guardian +0 -0
  11. package/bin/adr-index +0 -0
  12. package/bin/adr-judge +0 -0
  13. package/bin/adr-judge-precommit +0 -0
  14. package/bin/adr-lint +0 -0
  15. package/bin/adr-mcp +96 -4
  16. package/bin/adr-migrate +0 -0
  17. package/bin/adr-quality +0 -0
  18. package/bin/adr-readiness +0 -0
  19. package/bin/adr-readiness-ci +0 -0
  20. package/bin/adr-related +0 -0
  21. package/bin/adr-renumber +254 -254
  22. package/bin/adr-retire +0 -0
  23. package/bin/adr-settings +0 -0
  24. package/bin/adr-status +0 -0
  25. package/bin/adr-suggest +0 -0
  26. package/bin/adr-watch +0 -0
  27. package/bin/adr_doctor_probes.py +2 -0
  28. package/bin/bump-version +0 -0
  29. package/clients/workflows.json +229 -229
  30. package/hooks/__init__.py +1 -1
  31. package/hooks/adapters/__init__.py +13 -13
  32. package/hooks/adapters/claude.py +27 -27
  33. package/hooks/adapters/codex.py +26 -26
  34. package/hooks/adapters/copilot.py +11 -11
  35. package/hooks/adr-hook.py +128 -128
  36. package/hooks/adr_hook_core.py +843 -843
  37. package/hooks/adr_pr_guard.py +367 -367
  38. package/instructions/ADR-guide.md +101 -48
  39. package/instructions/adr.coding.md +82 -82
  40. package/instructions/adr.review.md +182 -182
  41. package/opencode/plugin.ts +1 -4
  42. package/package.json +5 -2
  43. package/schemas/adr-context-probes.schema.json +56 -56
  44. package/schemas/adr-enforcement.schema.json +57 -57
  45. package/schemas/adr-frontmatter.schema.json +144 -144
  46. package/schemas/adr-index.schema.json +276 -276
  47. package/schemas/adr-kit-config.schema.json +371 -371
  48. package/schemas/adr-readiness.schema.json +41 -41
  49. package/schemas/client-capabilities.schema.json +503 -503
  50. package/schemas/client-certification.schema.json +101 -101
  51. package/schemas/doctor-output.schema.json +92 -92
  52. package/skills/adr/SKILL.md +780 -780
  53. package/skills/audit/SKILL.md +103 -103
  54. package/skills/context/SKILL.md +77 -77
  55. package/skills/grill/SKILL.md +84 -84
  56. package/skills/grill/agents/openai.yaml +4 -4
  57. package/skills/guardian/SKILL.md +316 -316
  58. package/skills/init/SKILL.md +499 -499
  59. package/skills/install-hooks/SKILL.md +154 -154
  60. package/skills/judge/SKILL.md +168 -168
  61. package/skills/lint/SKILL.md +321 -321
  62. package/skills/migrate/SKILL.md +313 -313
  63. package/skills/related/SKILL.md +62 -62
  64. package/skills/retire/SKILL.md +41 -41
  65. package/skills/review/SKILL.md +167 -167
  66. package/skills/settings/SKILL.md +73 -73
  67. package/skills/setup/SKILL.md +128 -128
  68. package/skills/supersede/SKILL.md +136 -136
  69. package/skills/upgrade/SKILL.md +273 -273
  70. package/templates/adr-kit-guide.md +354 -354
  71. package/templates/adr-template.canonical.md +115 -115
  72. package/templates/adr-template.madr.md +131 -131
  73. package/templates/adr-template.md +131 -131
  74. package/templates/adr-template.nygard.md +111 -111
  75. package/templates/cc-settings/guardian-hook-entry.json +9 -9
  76. package/templates/githooks/pre-commit +1 -1
  77. package/templates/github-workflows/adr-audit.yml +58 -58
  78. package/templates/github-workflows/adr-guardian-audit.yml +133 -133
  79. package/templates/github-workflows/adr-index-check.yml +30 -30
  80. package/templates/github-workflows/adr-judge.yml +31 -31
  81. package/templates/github-workflows/adr-readiness.yml +18 -18
  82. package/templates/validate_adr_template.py +38 -38
  83. package/templates/validate_adr_template.sh +74 -74
@@ -1,499 +1,499 @@
1
- ---
2
- name: init
3
- description: "Initialize ADR Kit in a project. Use for adr-kit init, first-time ADR setup, architecture audit, managed guidance, and the pre-commit gate."
4
- argument-hint: "[no arguments]"
5
- disable-model-invocation: true
6
- allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task]
7
- ---
8
-
9
- # adr-kit init
10
-
11
- This is the **adopt** mode of `/adr-kit:setup` (spec R19: one entry point,
12
- four modes). Invoked directly or via `/adr-kit:setup adopt`, the procedure
13
- is identical -- this file owns it.
14
-
15
- `$ARGUMENTS` is reserved for future init options and should normally be empty.
16
- Reject unknown arguments instead of guessing.
17
-
18
- You are running the one-shot project bootstrap for adr-kit. Your job is to take a project that has either no ADRs or only legacy-shaped ADRs and:
19
-
20
- 1. Write the project's instruction layout with `scripts/setup-project.py`, which owns every file in it.
21
- New ADRs use MADR unless `docs/adr/.adr-kit.json` selects
22
- `template.profile: "nygard"` or `"canonical"`.
23
- 2. Discover decision-shaped artefacts in the source and documentation, create a starter work queue of Proposed ADRs, and confirm each decision independently.
24
- 3. Install the pre-commit hook so future commits are guarded against ADR drift.
25
- 4. Lint everything to confirm the resulting ADR set passes the four verification gates.
26
-
27
- This is a deep, one-shot operation. Do not skip steps. Do interact with the user — batched approval beats silent autopilot every time.
28
-
29
- ## Step 0 — Verify Python 3
30
-
31
- adr-kit requires Python 3.10 or later. Before doing anything else, verify it is available.
32
-
33
- ### Detection
34
-
35
- Run these checks in order:
36
-
37
- ```bash
38
- python3 --version 2>/dev/null || python --version 2>/dev/null || py --version 2>/dev/null
39
- ```
40
-
41
- Parse the output. Acceptable: any Python 3.10+ version string. Not acceptable: Python 2.x, Python 3.9 or earlier, command not found, or no output.
42
-
43
- **If Python 3 is found:** print `[adr-kit] Python OK: <version>` and continue to Step 1.
44
-
45
- **If Python 3 is NOT found:** offer installation. Detect the platform:
46
-
47
- ```bash
48
- uname -s 2>/dev/null || echo "windows"
49
- ```
50
-
51
- Then present platform-specific installation guidance:
52
-
53
- ---
54
-
55
- ### macOS — Python not found
56
-
57
- ```bash
58
- # Option A (recommended): Install via Homebrew
59
- brew install python3
60
-
61
- # Option B: Install Xcode Command Line Tools (includes python3)
62
- xcode-select --install
63
-
64
- # Option C: Download from python.org
65
- # https://www.python.org/downloads/macos/
66
- ```
67
-
68
- Ask the user: `Run 'brew install python3' now? (Y/n)`
69
- - If yes: run `brew install python3` via Bash. After it completes, verify again with `python3 --version`. If successful: confirm and continue.
70
- - If no: print the install instructions and tell the user to re-run `/adr-kit:init` after installing.
71
-
72
- ---
73
-
74
- ### Linux (Debian/Ubuntu)
75
-
76
- ```bash
77
- sudo apt-get update && sudo apt-get install -y python3 python3-pip
78
- ```
79
-
80
- Ask: `Run this command now? (Y/n)`
81
- - If yes: run it. Verify after. Continue if successful.
82
-
83
- ### Linux (Red Hat/Fedora/CentOS)
84
-
85
- ```bash
86
- sudo dnf install python3 # Fedora/RHEL 8+
87
- # or: sudo yum install python3
88
- ```
89
-
90
- ### Linux (Arch)
91
-
92
- ```bash
93
- sudo pacman -S python
94
- ```
95
-
96
- For generic Linux, detect the distro from `/etc/os-release` and present the matching command. If uncertain, present all three and ask the user to choose.
97
-
98
- ---
99
-
100
- ### Windows — Python not found
101
-
102
- Present these options in order:
103
-
104
- **Option A (recommended): Windows Package Manager (winget)**
105
- ```powershell
106
- winget install Python.Python.3.12
107
- ```
108
- Ask: `Run this in a terminal now? (Y/n)` — if yes, run it via PowerShell.
109
-
110
- **Option B: Microsoft Store**
111
- Open: `ms-windows-store://pdp/?ProductId=9NCVDN91XZQP`
112
- (or search "Python 3" in the Microsoft Store)
113
-
114
- **Option C: python.org installer**
115
- Download from: https://www.python.org/downloads/windows/
116
- Instruct: Check "Add Python to PATH" during installation.
117
-
118
- After any Windows installation, verify:
119
- ```powershell
120
- python --version
121
- ```
122
-
123
- **IMPORTANT for Windows users:** After installation, a new terminal session may be needed to pick up the updated PATH. Tell the user to close and reopen the terminal, then re-run `/adr-kit:init`.
124
-
125
- ---
126
-
127
- ### All platforms — After successful installation
128
-
129
- 1. Verify the installed version: `python3 --version` (or `python --version` on Windows).
130
- 2. Confirm the version is 3.10+. If it is 3.9 or earlier, warn: `[adr-kit] WARN: Python 3.9 or earlier detected. adr-kit requires 3.10+. Some features will not work.`
131
- 3. Print: `[adr-kit] Python 3.x.y installed. Continuing setup...`
132
- 4. Continue to Step 1.
133
-
134
- If the user declines installation and Python is unavailable: print the error below and stop.
135
-
136
- ```
137
- [adr-kit] ERROR: Python 3 is required but not installed.
138
- Install Python 3.10+ from https://www.python.org/downloads/ and re-run /adr-kit:init.
139
- ```
140
-
141
- ## Step 1 — Project hookup
142
-
143
- ### 1a. Write the instruction layout
144
-
145
- Do not hand-write the instruction block or the guide. `scripts/setup-project.py`
146
- owns the layout and is the only thing that knows all of it: `CLAUDE.md`,
147
- `AGENTS.md`, `.github/copilot-instructions.md` and `.adr-kit/ADR-guide.md`.
148
- Describing an older layout in prose here is how the three clients drifted apart
149
- -- the Codex and Copilot init skills delegate to this command while this file
150
- still wrote a guide under `.claude/` and a stub block the same repository
151
- classifies as legacy.
152
-
153
- Preview, then apply:
154
-
155
- ```bash
156
- python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root . --dry-run
157
- python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root .
158
- ```
159
-
160
- Two properties the command guarantees, and this skill must not undermine:
161
-
162
- - **Idempotent.** Re-running on a current project changes nothing.
163
- - **Bounded.** It writes only inside its managed markers, so user content around
164
- them stays byte-exact, and it never touches `.adr-kit/ADR-guide.local.md`.
165
-
166
- **A v0.11 footprint stops this step.** If `CLAUDE.md` carries an inline
167
- `## ADR Kit Rules` section, do not run the writer. Tell the user to run
168
- `/adr-kit:upgrade`, which performs that migration explicitly. Silently rewriting
169
- a v0.11 footprint is the one thing setup may never do.
170
-
171
- Relay the command's per-change output, and say plainly when there was nothing to
172
- do -- a no-op is the expected result of a second run.
173
-
174
- ## Step 1b — The signer: propose, never assume
175
-
176
- Do this before Step 3, because that is where `bin/adr new` first runs and it
177
- refuses to write an unsigned Status History entry. Discovering that refusal
178
- halfway through a batch of reconstructed ADRs is the worst moment to meet it.
179
-
180
- ```bash
181
- python3 "$ADR_KIT/bin/adr" signer --suggest --adr-dir docs/adr
182
- ```
183
-
184
- Read-only: it finds candidates and writes nothing. It looks at the signed-in
185
- GitHub account (`gh api user`, when the CLI is available) and at
186
- `git config user.name`, ranks them, and shows each with its source — a proposal
187
- the user cannot trace is one they cannot judge, and this value lands in an
188
- immutable history.
189
-
190
- - **Candidates found** — show them and ask which to adopt, or let the user type a
191
- different name. Then write it:
192
- `python3 "$ADR_KIT/bin/adr" signer --set "User: <chosen>"`.
193
- - **Already configured** — say so and move on. Do not overwrite it.
194
- - **Nothing found** — ask for the name outright rather than guessing.
195
-
196
- **Bot and CI identities are deliberately not offered.** `github-actions[bot]`,
197
- `runner`, a bare `user`: those are configured values that name a machine, and R8
198
- asks for evidence of which *human* accepted a decision.
199
-
200
- The value is machine-local by design (`docs/adr/.adr-kit.local.json`, gitignored)
201
- because writing one person's name into the tracked config would sign every
202
- teammate's acceptances.
203
-
204
- ## Step 2 — Candidate discovery
205
-
206
- Run `bin/adr-discover` to scan the project. Use `--output` to drop the result next to the existing ADRs:
207
-
208
- ```bash
209
- $ADR_KIT/bin/adr-discover --root . --output docs/adr/.adr-kit-init-candidates.json
210
- ```
211
-
212
- (`$ADR_KIT` is the plugin path resolved in step 1a.)
213
-
214
- The output is a JSON file with:
215
- - `tooling-*` candidates (build system, CI, runtime markers)
216
- - `deps-*` candidates (one per dependency manifest found)
217
- - `doc-quote-*` candidates (one per documentation file containing decision-narrative phrases, with up to 5 example snippets)
218
- - `history-*` candidates from the git log: commit subjects that announce a
219
- change of direction, the files rewritten far more often than the rest, and
220
- the order in which tooling and dependencies arrived.
221
-
222
- **Every candidate carries `source`, and the difference matters.** `source:
223
- "tree"` is a fact about a file that exists. `source: "history"` is a claim
224
- someone typed once, in a hurry, possibly about a decision that was reversed
225
- three commits later — those candidates carry a `why_this_is_weak` note saying
226
- so. Never write an ADR from a history candidate without confirming it against
227
- the code as it stands now. Do surface them: the *why* of an existing codebase
228
- lives in its history, which is exactly what a working-tree scan cannot see.
229
-
230
- `history.available: false` means the scan could not read a history (no git, no
231
- commits, not a repository). Say so plainly rather than presenting a tree-only
232
- scan as complete.
233
-
234
- Open the file. Tell the user the headline counts: `<N total candidates: <X>
235
- tooling, <Y> dependency, <Z> documented, <H> from history>`.
236
-
237
- ## Step 3 — Deep LLM curation
238
-
239
- Read every candidate's evidence file(s) (or relevant section), plus the project's `README.md`, root `AGENTS.md`/`CLAUDE.md`, and the existing `docs/adr/ADR-*.md` files. Your job: decide for each candidate whether it warrants an ADR and dedupe against ADRs that already exist.
240
-
241
- For each candidate, classify:
242
- - **`keep`** — material architectural decision; needs an ADR.
243
- - **`merge with ADR-NNN`** — already documented in an existing ADR; no new file needed.
244
- - **`drop`** — not architecturally significant (e.g., a casual doc phrase that didn't actually drive a decision).
245
-
246
- Process candidates in **batches of 5–10**. For each batch:
247
-
248
- 1. Print a numbered list with: candidate id, your proposed classification, your reasoning (one sentence), and (for `keep`) the proposed ADR title and decision_type.
249
- 2. Ask the user: `Approve all [yes] | reject specific (list ids) | drop classification suggestion (id → drop) | refine title/type (id → ...)`.
250
- 3. Apply the user's choices. For every `keep` candidate, create the record with
251
- the lifecycle command, **named explicitly**:
252
-
253
- ```bash
254
- $ADR_KIT/bin/adr new "<Title>" --adr-dir docs/adr
255
- ```
256
-
257
- Do not write the file with the Write tool. `bin/adr new` allocates the next
258
- number, honours `template.profile`, writes `Status: Proposed, <today>`, and
259
- regenerates all three indexes inside one transaction. A hand-written file
260
- gets none of that, and the index it leaves behind is stale from the moment
261
- it lands.
262
-
263
- Include an `## Enforcement` block when the rule is declarative,
264
- `llm_judge: true` when it is not, or omit the section when no code surface
265
- exists.
266
-
267
- **When the decision is already shipped, record that.** An init scan is
268
- reconstructing decisions the code already implements, so set
269
- `documents_shipped: true` and list the concrete evidence in `verified_in`
270
- (the candidate's `evidence_files` are exactly that). Use:
271
-
272
- ```bash
273
- $ADR_KIT/bin/adr document ADR-NNN --verified-in <path> [--verified-in <path>]
274
- ```
275
-
276
- This is not a shortcut to acceptance; it is the honest metadata, and it is
277
- what makes step 3b's supported path available at all.
278
- 4. Explain and select grill depth per candidate:
279
- - **compact confirmation** only when chosen decision, rationale,
280
- alternatives, and consequences each have direct cited evidence;
281
- - **deep grill** when any of those fields, ownership, or conflict resolution
282
- is missing or inferred.
283
- Resolve duplicates and conflicts by merging, linking, rejecting, or
284
- escalating before acceptance.
285
- 5. Confirm each ADR separately. A batch response may select candidates but
286
- cannot accept multiple decisions. On interruption, retain valid Proposed
287
- records, Open Questions, a consistent index, and one
288
- `/adr-kit:grill ADR-NNN` resume command per unfinished record.
289
-
290
- Do not race ahead. Wait for the user's response per batch.
291
-
292
- ## Step 3b — Acceptance, and what "never silently accept" actually forbids
293
-
294
- Reconstructing a decision the code already implements is documentation, not
295
- authorisation: nobody is being asked to approve a new direction, they are being
296
- asked to confirm that the record matches what already ships. That is why the
297
- kit has an auto-accept path at all, and init is what it exists for.
298
-
299
- What "never silently accept" forbids is the *silently*, not the accepting. So:
300
-
301
- 1. Show the user the batch of records and what each one documents.
302
- 2. Ask once, explicitly, for that batch:
303
- `Accept these <N> as documentation of shipped behaviour? [yes / grill first / list ids to hold back]`
304
- 3. On `yes`, accept each through the supported path:
305
-
306
- ```bash
307
- $ADR_KIT/bin/adr accept ADR-NNN --auto --auto-mode auto --repo-root .
308
- ```
309
-
310
- `--auto` is not a bypass. It re-runs every acceptance gate and additionally
311
- demands `documents_shipped: true`, at least one `verified_in` pointer, no
312
- unresolved Open Questions, and a quality score above the configured
313
- threshold. A record that fails any of those refuses to accept and tells you
314
- which one. That refusal is the point: it is the difference between "the user
315
- approved this batch" and "the record is good enough to stand".
316
- 4. Anything held back, or anything `--auto` refused, stays `Proposed` and gets
317
- `/adr-kit:grill ADR-NNN`.
318
-
319
- Never accept without step 2's question, and never accept a record the user has
320
- not seen. Batch approval selects *which* records; each still passes its own
321
- gates on its own.
322
-
323
- When all candidates are processed, summarise: `<created N new ADRs, accepted A
324
- as shipped documentation, held B for grilling, merged M, dropped K>`.
325
-
326
- ## Step 3c — Verify the index rather than assuming it
327
-
328
- Every lifecycle command regenerates the indexes in its own transaction, so
329
- after a clean run this passes. Run it anyway, because "should have" is not a
330
- guarantee and a stale index misinforms every later reader and every agent:
331
-
332
- ```bash
333
- $ADR_KIT/bin/adr-index docs/adr --check
334
- ```
335
-
336
- Exit 0 means the three generated artefacts match the ADRs. **Init does not
337
- finish while this is non-zero.** On failure, run `$ADR_KIT/bin/adr-index
338
- docs/adr` to regenerate, then re-run the check and say what was stale — a
339
- record written outside the lifecycle command is the usual cause, and the user
340
- should know it happened.
341
-
342
- ## Step 4 — Hook installation
343
-
344
- Run the `install-hooks` skill (or do its work inline if delegating is awkward):
345
-
346
- 1. Resolve the plugin's `templates/githooks/pre-commit` path (same plugin path as step 1a).
347
- 2. Read it. Write to project `.githooks/pre-commit`. Make it executable (`chmod +x .githooks/pre-commit`).
348
- 3. If the project already has a `.githooks/pre-commit`, do NOT overwrite. Read both. Tell the user the existing hook content. Ask: `prepend adr-kit check before existing hook | replace | abort install`. On `prepend`, write a wrapper that runs adr-kit then exec's the original (saved as `.githooks/pre-commit.adr-kit-saved`).
349
- 4. Run `git config core.hooksPath .githooks` once. Confirm with `git config --get core.hooksPath`.
350
-
351
- ### 4a — Choose the judge backend (ADR-017)
352
-
353
- The declarative Enforcement gate is always-on, deterministic and free. The LLM pass is **on by default** and needs one decision from the user: which model reviews their commits.
354
-
355
- Print this notice first, verbatim. Do not shorten the cost paragraph and do not name a specific model — no model is pinned any more.
356
-
357
- ```
358
- [adr-kit] The pre-commit judge runs two passes.
359
-
360
- Declarative gate always on, regex and globs, no model, no cost.
361
- LLM pass on by default, for ADRs you mark `llm_judge: true`.
362
-
363
- What the LLM pass costs: ONE model call per llm_judge ADR, on every commit that
364
- touches its scope, every time. The calls are deliberately isolated from each
365
- other -- a shared prompt let one ADR's text flip another ADR's verdict -- so the
366
- cost is LINEAR in the number of opted-in ADRs and is not amortised across them.
367
- No ADR carries `llm_judge: true` until an author adds it, so a fresh project
368
- pays nothing until someone opts a decision in.
369
-
370
- Where that call goes: the CLI of the agent you already use (ADR-036 reduced the
371
- judge to this host backend; an operator can still point one run elsewhere with
372
- `ADR_KIT_LLM_CMD` or `--llm-cmd`, which is an environment fact and never
373
- repository configuration). No model flag is passed, so your own configured
374
- model answers, and no extra credential is needed beyond the agent you are
375
- already signed in to. An unavailable backend degrades to declarative-only and
376
- never blocks a commit.
377
- ```
378
-
379
- Then ask: `LLM pass? [1] on (host CLI) [2] off (1)`
380
-
381
- Apply the answer with the kit's own command — do **not** hand-write the JSON, because the command validates what it wrote and refuses an incomplete choice. Resolve the plugin path first if it is not already in scope from step 1a:
382
-
383
- ```bash
384
- ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
385
- ```
386
-
387
- - **on** — you know which client you are running in, because you are reading this client's copy of this skill. Pass that id:
388
- ```bash
389
- "$ADR_KIT/bin/adr-judge" --adr-dir docs/adr --set-backend host --host-client claude-code-cli
390
- ```
391
- Each client's copy of this skill names its own id: this one is `claude-code-cli`. The judge cannot work this out at commit time — a `git commit` happens whether or not any agent is running — which is why it is recorded now, into the gitignored `docs/adr/.adr-kit.local.json`, while it is known with certainty.
392
- - **off** — merge `{"judge": {"llm_enabled": false}}` into `docs/adr/.adr-kit.json`. Say plainly that the declarative gate still runs and that `/adr-kit:judge` still gives LLM review on demand.
393
-
394
- Ignore the local file in version control (idempotent):
395
-
396
- ```bash
397
- grep -q "\.adr-kit\.local\.json" .gitignore 2>/dev/null || echo "docs/adr/.adr-kit.local.json" >> .gitignore
398
- ```
399
-
400
- Then ask one more question (default No): `Enable per-commit ADR-suggest nudges (a second model call per commit, advisory only)? (y/N)` and merge `{"suggest": {"enabled": <true|false>}}`.
401
-
402
- Confirm by showing the resolved configuration rather than by asserting it:
403
-
404
- ```bash
405
- "$ADR_KIT/bin/adr-judge" --adr-dir docs/adr --show-config
406
- ```
407
-
408
- Print the final one-liner: `Pre-commit ADR judge installed (declarative gate always-on; LLM pass on <backend>). Disable a single commit with ADR_KIT_HOOK_DISABLE=1 git commit ...; skip the LLM pass for one commit with ADR_KIT_NO_LLM=1 git commit ...; change the backend later with /adr-kit:judge settings; remove permanently with /adr-kit:install-hooks --uninstall.`
409
-
410
- ## Step 5 — Final lint
411
-
412
- Run the kit's lint binary on the freshly populated ADR directory:
413
-
414
- ```bash
415
- $ADR_KIT/bin/adr-lint docs/adr/
416
- ```
417
-
418
- Report the result: `<N PASS, M ADVISORY, K FAIL>`. If any FAIL: list them with the gate name and ask the user whether to fix now (re-invoke `adr-generator` for the offending ADR) or defer to a follow-up.
419
-
420
- ## Step 5b — Guardian setup (new in v0.18.0)
421
-
422
- After the hook and LLM opt-in are configured, offer the ADR Guardian.
423
-
424
- Print this notice:
425
-
426
- ```
427
- [adr-guardian] The ADR Guardian is a SessionStart staleness detector (v0.18.0).
428
- It checks ADR health at session start and nudges when a sweep is due:
429
- - cheap tier (drift + retire + lint): daily, free
430
- - LLM tier (suggest + audit): bi-weekly, asks before spending (~$0.10–0.30)
431
- Two registration paths:
432
- A. Plugin-level (default, recommended): auto-registers when the adr-kit plugin is enabled.
433
- The guardian self-guards (no-ops silently in non-ADR projects).
434
- B. Project-scoped: adds a SessionStart entry to .claude/settings.json (explicit, contained).
435
- ```
436
-
437
- Ask two questions (default A/No):
438
-
439
- 1. `Enable guardian? (Y/n)` — Write `{"guardian": {"enabled": true}}` into `docs/adr/.adr-kit.json` (merge if present). If No: write `{"guardian": {"enabled": false}}` and skip the rest of this step.
440
- 2. `Register project-scoped SessionStart hook in .claude/settings.json? (y/N)` — If yes, follow the instructions in `skills/install-hooks/SKILL.md` under "Adding the project-scoped guardian hook". If no, remind the user the plugin-level hook is used by default.
441
-
442
- Add `.adr-kit-state.json` to the project's `.gitignore` (idempotent):
443
-
444
- ```bash
445
- grep -q "\.adr-kit-state\.json" .gitignore 2>/dev/null || echo "docs/adr/.adr-kit-state.json" >> .gitignore
446
- ```
447
-
448
- Confirm: `[adr-guardian] enabled (<path>); state file gitignored.`
449
-
450
- ## Step 6 — Generate standalone validation scripts (optional)
451
-
452
- Ask the user: "Generate standalone validation scripts for CI/CD pipelines? (Y/n)"
453
-
454
- If yes:
455
-
456
- ```bash
457
- ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
458
- "$ADR_KIT/bin/adr-generate-scripts" --lang shell --output .generated/
459
- ```
460
-
461
- This generates shell scripts in `.generated/<ADR-NNN>/validate.sh` that validate code against ADR Enforcement rules without requiring adr-kit. Useful for CI/CD pipelines that run outside Claude Code.
462
-
463
- If the user says no (or presses Enter on the default), skip silently. If `.generated/` already contains scripts from a previous run, the generator overwrites them — this is idempotent.
464
-
465
- ## Wrap-up
466
-
467
- Print a final summary in this exact shape:
468
-
469
- ```
470
- adr-kit init complete:
471
- - layout: <files setup-project.py wrote> (created | refreshed | unchanged)
472
- - audit: <N> candidates → <X> kept, <Y> merged, <Z> dropped
473
- - ADRs: <N> created, <M> already present
474
- - hook: installed (or already present + reason)
475
- - llm: backend <host|off>, suggest <enabled|disabled>
476
- - guardian: <enabled|disabled> (plugin-level | project-scoped | disabled)
477
- - lint: <P> PASS, <A> ADVISORY, <F> FAIL
478
- - scripts: generated | skipped (user declined)
479
- ```
480
-
481
- Suggest a first commit staging exactly what was written: `git add docs/adr/ .adr-kit/ CLAUDE.md AGENTS.md .githooks/pre-commit && git commit -m "chore(adr-kit): bootstrap"`. Do not run the commit yourself; let the user inspect first.
482
-
483
- ## Constraints
484
-
485
- - **Do not skip steps.** Each step has an idempotency story; running them in order produces a consistent project state.
486
- - **Batch selection, individual gates.** Do not silently mass-generate or
487
- accept ADRs. Five to ten candidates may be triaged per round; the user
488
- approves a batch, and every record still passes its own acceptance gates on
489
- its own through `bin/adr accept --auto`. A record the user has not seen is
490
- never accepted, and a record that fails a gate is never accepted regardless
491
- of what the batch answer was.
492
- - **Reconstruction is documentation, not authorisation.** Init records
493
- decisions the code already implements, which is why `--auto` exists and why
494
- it demands `documents_shipped: true` and a `verified_in` pointer before it
495
- will run. A decision that is *not* already shipped is a new decision: it goes
496
- through `/adr-kit:grill` and ordinary acceptance, never `--auto`.
497
- - **Resolve the plugin path dynamically.** The kit lives at `~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/<version>/`. Use the `ls | sort -V | tail -1` resolver above; do not hardcode a version.
498
- - **Preserve user CLAUDE.md content.** Only the marked stub block (or a v0.11-style `## ADR Kit Rules` section being replaced) may be modified. Everything else stays byte-exact.
499
- - **Re-runnable.** A second invocation on a project where init already succeeded should detect the existing footprint and either skip or refresh, not regenerate.
1
+ ---
2
+ name: init
3
+ description: "Initialize ADR Kit in a project. Use for adr-kit init, first-time ADR setup, architecture audit, managed guidance, and the pre-commit gate."
4
+ argument-hint: "[no arguments]"
5
+ disable-model-invocation: true
6
+ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task]
7
+ ---
8
+
9
+ # adr-kit init
10
+
11
+ This is the **adopt** mode of `/adr-kit:setup` (spec R19: one entry point,
12
+ four modes). Invoked directly or via `/adr-kit:setup adopt`, the procedure
13
+ is identical -- this file owns it.
14
+
15
+ `$ARGUMENTS` is reserved for future init options and should normally be empty.
16
+ Reject unknown arguments instead of guessing.
17
+
18
+ You are running the one-shot project bootstrap for adr-kit. Your job is to take a project that has either no ADRs or only legacy-shaped ADRs and:
19
+
20
+ 1. Write the project's instruction layout with `scripts/setup-project.py`, which owns every file in it.
21
+ New ADRs use MADR unless `docs/adr/.adr-kit.json` selects
22
+ `template.profile: "nygard"` or `"canonical"`.
23
+ 2. Discover decision-shaped artefacts in the source and documentation, create a starter work queue of Proposed ADRs, and confirm each decision independently.
24
+ 3. Install the pre-commit hook so future commits are guarded against ADR drift.
25
+ 4. Lint everything to confirm the resulting ADR set passes the four verification gates.
26
+
27
+ This is a deep, one-shot operation. Do not skip steps. Do interact with the user — batched approval beats silent autopilot every time.
28
+
29
+ ## Step 0 — Verify Python 3
30
+
31
+ adr-kit requires Python 3.10 or later. Before doing anything else, verify it is available.
32
+
33
+ ### Detection
34
+
35
+ Run these checks in order:
36
+
37
+ ```bash
38
+ python3 --version 2>/dev/null || python --version 2>/dev/null || py --version 2>/dev/null
39
+ ```
40
+
41
+ Parse the output. Acceptable: any Python 3.10+ version string. Not acceptable: Python 2.x, Python 3.9 or earlier, command not found, or no output.
42
+
43
+ **If Python 3 is found:** print `[adr-kit] Python OK: <version>` and continue to Step 1.
44
+
45
+ **If Python 3 is NOT found:** offer installation. Detect the platform:
46
+
47
+ ```bash
48
+ uname -s 2>/dev/null || echo "windows"
49
+ ```
50
+
51
+ Then present platform-specific installation guidance:
52
+
53
+ ---
54
+
55
+ ### macOS — Python not found
56
+
57
+ ```bash
58
+ # Option A (recommended): Install via Homebrew
59
+ brew install python3
60
+
61
+ # Option B: Install Xcode Command Line Tools (includes python3)
62
+ xcode-select --install
63
+
64
+ # Option C: Download from python.org
65
+ # https://www.python.org/downloads/macos/
66
+ ```
67
+
68
+ Ask the user: `Run 'brew install python3' now? (Y/n)`
69
+ - If yes: run `brew install python3` via Bash. After it completes, verify again with `python3 --version`. If successful: confirm and continue.
70
+ - If no: print the install instructions and tell the user to re-run `/adr-kit:init` after installing.
71
+
72
+ ---
73
+
74
+ ### Linux (Debian/Ubuntu)
75
+
76
+ ```bash
77
+ sudo apt-get update && sudo apt-get install -y python3 python3-pip
78
+ ```
79
+
80
+ Ask: `Run this command now? (Y/n)`
81
+ - If yes: run it. Verify after. Continue if successful.
82
+
83
+ ### Linux (Red Hat/Fedora/CentOS)
84
+
85
+ ```bash
86
+ sudo dnf install python3 # Fedora/RHEL 8+
87
+ # or: sudo yum install python3
88
+ ```
89
+
90
+ ### Linux (Arch)
91
+
92
+ ```bash
93
+ sudo pacman -S python
94
+ ```
95
+
96
+ For generic Linux, detect the distro from `/etc/os-release` and present the matching command. If uncertain, present all three and ask the user to choose.
97
+
98
+ ---
99
+
100
+ ### Windows — Python not found
101
+
102
+ Present these options in order:
103
+
104
+ **Option A (recommended): Windows Package Manager (winget)**
105
+ ```powershell
106
+ winget install Python.Python.3.12
107
+ ```
108
+ Ask: `Run this in a terminal now? (Y/n)` — if yes, run it via PowerShell.
109
+
110
+ **Option B: Microsoft Store**
111
+ Open: `ms-windows-store://pdp/?ProductId=9NCVDN91XZQP`
112
+ (or search "Python 3" in the Microsoft Store)
113
+
114
+ **Option C: python.org installer**
115
+ Download from: https://www.python.org/downloads/windows/
116
+ Instruct: Check "Add Python to PATH" during installation.
117
+
118
+ After any Windows installation, verify:
119
+ ```powershell
120
+ python --version
121
+ ```
122
+
123
+ **IMPORTANT for Windows users:** After installation, a new terminal session may be needed to pick up the updated PATH. Tell the user to close and reopen the terminal, then re-run `/adr-kit:init`.
124
+
125
+ ---
126
+
127
+ ### All platforms — After successful installation
128
+
129
+ 1. Verify the installed version: `python3 --version` (or `python --version` on Windows).
130
+ 2. Confirm the version is 3.10+. If it is 3.9 or earlier, warn: `[adr-kit] WARN: Python 3.9 or earlier detected. adr-kit requires 3.10+. Some features will not work.`
131
+ 3. Print: `[adr-kit] Python 3.x.y installed. Continuing setup...`
132
+ 4. Continue to Step 1.
133
+
134
+ If the user declines installation and Python is unavailable: print the error below and stop.
135
+
136
+ ```
137
+ [adr-kit] ERROR: Python 3 is required but not installed.
138
+ Install Python 3.10+ from https://www.python.org/downloads/ and re-run /adr-kit:init.
139
+ ```
140
+
141
+ ## Step 1 — Project hookup
142
+
143
+ ### 1a. Write the instruction layout
144
+
145
+ Do not hand-write the instruction block or the guide. `scripts/setup-project.py`
146
+ owns the layout and is the only thing that knows all of it: `CLAUDE.md`,
147
+ `AGENTS.md`, `.github/copilot-instructions.md` and `.adr-kit/ADR-guide.md`.
148
+ Describing an older layout in prose here is how the three clients drifted apart
149
+ -- the Codex and Copilot init skills delegate to this command while this file
150
+ still wrote a guide under `.claude/` and a stub block the same repository
151
+ classifies as legacy.
152
+
153
+ Preview, then apply:
154
+
155
+ ```bash
156
+ python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root . --dry-run
157
+ python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root .
158
+ ```
159
+
160
+ Two properties the command guarantees, and this skill must not undermine:
161
+
162
+ - **Idempotent.** Re-running on a current project changes nothing.
163
+ - **Bounded.** It writes only inside its managed markers, so user content around
164
+ them stays byte-exact, and it never touches `.adr-kit/ADR-guide.local.md`.
165
+
166
+ **A v0.11 footprint stops this step.** If `CLAUDE.md` carries an inline
167
+ `## ADR Kit Rules` section, do not run the writer. Tell the user to run
168
+ `/adr-kit:upgrade`, which performs that migration explicitly. Silently rewriting
169
+ a v0.11 footprint is the one thing setup may never do.
170
+
171
+ Relay the command's per-change output, and say plainly when there was nothing to
172
+ do -- a no-op is the expected result of a second run.
173
+
174
+ ## Step 1b — The signer: propose, never assume
175
+
176
+ Do this before Step 3, because that is where `bin/adr new` first runs and it
177
+ refuses to write an unsigned Status History entry. Discovering that refusal
178
+ halfway through a batch of reconstructed ADRs is the worst moment to meet it.
179
+
180
+ ```bash
181
+ python3 "$ADR_KIT/bin/adr" signer --suggest --adr-dir docs/adr
182
+ ```
183
+
184
+ Read-only: it finds candidates and writes nothing. It looks at the signed-in
185
+ GitHub account (`gh api user`, when the CLI is available) and at
186
+ `git config user.name`, ranks them, and shows each with its source — a proposal
187
+ the user cannot trace is one they cannot judge, and this value lands in an
188
+ immutable history.
189
+
190
+ - **Candidates found** — show them and ask which to adopt, or let the user type a
191
+ different name. Then write it:
192
+ `python3 "$ADR_KIT/bin/adr" signer --set "User: <chosen>"`.
193
+ - **Already configured** — say so and move on. Do not overwrite it.
194
+ - **Nothing found** — ask for the name outright rather than guessing.
195
+
196
+ **Bot and CI identities are deliberately not offered.** `github-actions[bot]`,
197
+ `runner`, a bare `user`: those are configured values that name a machine, and R8
198
+ asks for evidence of which *human* accepted a decision.
199
+
200
+ The value is machine-local by design (`docs/adr/.adr-kit.local.json`, gitignored)
201
+ because writing one person's name into the tracked config would sign every
202
+ teammate's acceptances.
203
+
204
+ ## Step 2 — Candidate discovery
205
+
206
+ Run `bin/adr-discover` to scan the project. Use `--output` to drop the result next to the existing ADRs:
207
+
208
+ ```bash
209
+ $ADR_KIT/bin/adr-discover --root . --output docs/adr/.adr-kit-init-candidates.json
210
+ ```
211
+
212
+ (`$ADR_KIT` is the plugin path resolved in step 1a.)
213
+
214
+ The output is a JSON file with:
215
+ - `tooling-*` candidates (build system, CI, runtime markers)
216
+ - `deps-*` candidates (one per dependency manifest found)
217
+ - `doc-quote-*` candidates (one per documentation file containing decision-narrative phrases, with up to 5 example snippets)
218
+ - `history-*` candidates from the git log: commit subjects that announce a
219
+ change of direction, the files rewritten far more often than the rest, and
220
+ the order in which tooling and dependencies arrived.
221
+
222
+ **Every candidate carries `source`, and the difference matters.** `source:
223
+ "tree"` is a fact about a file that exists. `source: "history"` is a claim
224
+ someone typed once, in a hurry, possibly about a decision that was reversed
225
+ three commits later — those candidates carry a `why_this_is_weak` note saying
226
+ so. Never write an ADR from a history candidate without confirming it against
227
+ the code as it stands now. Do surface them: the *why* of an existing codebase
228
+ lives in its history, which is exactly what a working-tree scan cannot see.
229
+
230
+ `history.available: false` means the scan could not read a history (no git, no
231
+ commits, not a repository). Say so plainly rather than presenting a tree-only
232
+ scan as complete.
233
+
234
+ Open the file. Tell the user the headline counts: `<N total candidates: <X>
235
+ tooling, <Y> dependency, <Z> documented, <H> from history>`.
236
+
237
+ ## Step 3 — Deep LLM curation
238
+
239
+ Read every candidate's evidence file(s) (or relevant section), plus the project's `README.md`, root `AGENTS.md`/`CLAUDE.md`, and the existing `docs/adr/ADR-*.md` files. Your job: decide for each candidate whether it warrants an ADR and dedupe against ADRs that already exist.
240
+
241
+ For each candidate, classify:
242
+ - **`keep`** — material architectural decision; needs an ADR.
243
+ - **`merge with ADR-NNN`** — already documented in an existing ADR; no new file needed.
244
+ - **`drop`** — not architecturally significant (e.g., a casual doc phrase that didn't actually drive a decision).
245
+
246
+ Process candidates in **batches of 5–10**. For each batch:
247
+
248
+ 1. Print a numbered list with: candidate id, your proposed classification, your reasoning (one sentence), and (for `keep`) the proposed ADR title and decision_type.
249
+ 2. Ask the user: `Approve all [yes] | reject specific (list ids) | drop classification suggestion (id → drop) | refine title/type (id → ...)`.
250
+ 3. Apply the user's choices. For every `keep` candidate, create the record with
251
+ the lifecycle command, **named explicitly**:
252
+
253
+ ```bash
254
+ $ADR_KIT/bin/adr new "<Title>" --adr-dir docs/adr
255
+ ```
256
+
257
+ Do not write the file with the Write tool. `bin/adr new` allocates the next
258
+ number, honours `template.profile`, writes `Status: Proposed, <today>`, and
259
+ regenerates all three indexes inside one transaction. A hand-written file
260
+ gets none of that, and the index it leaves behind is stale from the moment
261
+ it lands.
262
+
263
+ Include an `## Enforcement` block when the rule is declarative,
264
+ `llm_judge: true` when it is not, or omit the section when no code surface
265
+ exists.
266
+
267
+ **When the decision is already shipped, record that.** An init scan is
268
+ reconstructing decisions the code already implements, so set
269
+ `documents_shipped: true` and list the concrete evidence in `verified_in`
270
+ (the candidate's `evidence_files` are exactly that). Use:
271
+
272
+ ```bash
273
+ $ADR_KIT/bin/adr document ADR-NNN --verified-in <path> [--verified-in <path>]
274
+ ```
275
+
276
+ This is not a shortcut to acceptance; it is the honest metadata, and it is
277
+ what makes step 3b's supported path available at all.
278
+ 4. Explain and select grill depth per candidate:
279
+ - **compact confirmation** only when chosen decision, rationale,
280
+ alternatives, and consequences each have direct cited evidence;
281
+ - **deep grill** when any of those fields, ownership, or conflict resolution
282
+ is missing or inferred.
283
+ Resolve duplicates and conflicts by merging, linking, rejecting, or
284
+ escalating before acceptance.
285
+ 5. Confirm each ADR separately. A batch response may select candidates but
286
+ cannot accept multiple decisions. On interruption, retain valid Proposed
287
+ records, Open Questions, a consistent index, and one
288
+ `/adr-kit:grill ADR-NNN` resume command per unfinished record.
289
+
290
+ Do not race ahead. Wait for the user's response per batch.
291
+
292
+ ## Step 3b — Acceptance, and what "never silently accept" actually forbids
293
+
294
+ Reconstructing a decision the code already implements is documentation, not
295
+ authorisation: nobody is being asked to approve a new direction, they are being
296
+ asked to confirm that the record matches what already ships. That is why the
297
+ kit has an auto-accept path at all, and init is what it exists for.
298
+
299
+ What "never silently accept" forbids is the *silently*, not the accepting. So:
300
+
301
+ 1. Show the user the batch of records and what each one documents.
302
+ 2. Ask once, explicitly, for that batch:
303
+ `Accept these <N> as documentation of shipped behaviour? [yes / grill first / list ids to hold back]`
304
+ 3. On `yes`, accept each through the supported path:
305
+
306
+ ```bash
307
+ $ADR_KIT/bin/adr accept ADR-NNN --auto --auto-mode auto --repo-root .
308
+ ```
309
+
310
+ `--auto` is not a bypass. It re-runs every acceptance gate and additionally
311
+ demands `documents_shipped: true`, at least one `verified_in` pointer, no
312
+ unresolved Open Questions, and a quality score above the configured
313
+ threshold. A record that fails any of those refuses to accept and tells you
314
+ which one. That refusal is the point: it is the difference between "the user
315
+ approved this batch" and "the record is good enough to stand".
316
+ 4. Anything held back, or anything `--auto` refused, stays `Proposed` and gets
317
+ `/adr-kit:grill ADR-NNN`.
318
+
319
+ Never accept without step 2's question, and never accept a record the user has
320
+ not seen. Batch approval selects *which* records; each still passes its own
321
+ gates on its own.
322
+
323
+ When all candidates are processed, summarise: `<created N new ADRs, accepted A
324
+ as shipped documentation, held B for grilling, merged M, dropped K>`.
325
+
326
+ ## Step 3c — Verify the index rather than assuming it
327
+
328
+ Every lifecycle command regenerates the indexes in its own transaction, so
329
+ after a clean run this passes. Run it anyway, because "should have" is not a
330
+ guarantee and a stale index misinforms every later reader and every agent:
331
+
332
+ ```bash
333
+ $ADR_KIT/bin/adr-index docs/adr --check
334
+ ```
335
+
336
+ Exit 0 means the three generated artefacts match the ADRs. **Init does not
337
+ finish while this is non-zero.** On failure, run `$ADR_KIT/bin/adr-index
338
+ docs/adr` to regenerate, then re-run the check and say what was stale — a
339
+ record written outside the lifecycle command is the usual cause, and the user
340
+ should know it happened.
341
+
342
+ ## Step 4 — Hook installation
343
+
344
+ Run the `install-hooks` skill (or do its work inline if delegating is awkward):
345
+
346
+ 1. Resolve the plugin's `templates/githooks/pre-commit` path (same plugin path as step 1a).
347
+ 2. Read it. Write to project `.githooks/pre-commit`. Make it executable (`chmod +x .githooks/pre-commit`).
348
+ 3. If the project already has a `.githooks/pre-commit`, do NOT overwrite. Read both. Tell the user the existing hook content. Ask: `prepend adr-kit check before existing hook | replace | abort install`. On `prepend`, write a wrapper that runs adr-kit then exec's the original (saved as `.githooks/pre-commit.adr-kit-saved`).
349
+ 4. Run `git config core.hooksPath .githooks` once. Confirm with `git config --get core.hooksPath`.
350
+
351
+ ### 4a — Choose the judge backend (ADR-017)
352
+
353
+ The declarative Enforcement gate is always-on, deterministic and free. The LLM pass is **on by default** and needs one decision from the user: which model reviews their commits.
354
+
355
+ Print this notice first, verbatim. Do not shorten the cost paragraph and do not name a specific model — no model is pinned any more.
356
+
357
+ ```
358
+ [adr-kit] The pre-commit judge runs two passes.
359
+
360
+ Declarative gate always on, regex and globs, no model, no cost.
361
+ LLM pass on by default, for ADRs you mark `llm_judge: true`.
362
+
363
+ What the LLM pass costs: ONE model call per llm_judge ADR, on every commit that
364
+ touches its scope, every time. The calls are deliberately isolated from each
365
+ other -- a shared prompt let one ADR's text flip another ADR's verdict -- so the
366
+ cost is LINEAR in the number of opted-in ADRs and is not amortised across them.
367
+ No ADR carries `llm_judge: true` until an author adds it, so a fresh project
368
+ pays nothing until someone opts a decision in.
369
+
370
+ Where that call goes: the CLI of the agent you already use (ADR-036 reduced the
371
+ judge to this host backend; an operator can still point one run elsewhere with
372
+ `ADR_KIT_LLM_CMD` or `--llm-cmd`, which is an environment fact and never
373
+ repository configuration). No model flag is passed, so your own configured
374
+ model answers, and no extra credential is needed beyond the agent you are
375
+ already signed in to. An unavailable backend degrades to declarative-only and
376
+ never blocks a commit.
377
+ ```
378
+
379
+ Then ask: `LLM pass? [1] on (host CLI) [2] off (1)`
380
+
381
+ Apply the answer with the kit's own command — do **not** hand-write the JSON, because the command validates what it wrote and refuses an incomplete choice. Resolve the plugin path first if it is not already in scope from step 1a:
382
+
383
+ ```bash
384
+ ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
385
+ ```
386
+
387
+ - **on** — you know which client you are running in, because you are reading this client's copy of this skill. Pass that id:
388
+ ```bash
389
+ "$ADR_KIT/bin/adr-judge" --adr-dir docs/adr --set-backend host --host-client claude-code-cli
390
+ ```
391
+ Each client's copy of this skill names its own id: this one is `claude-code-cli`. The judge cannot work this out at commit time — a `git commit` happens whether or not any agent is running — which is why it is recorded now, into the gitignored `docs/adr/.adr-kit.local.json`, while it is known with certainty.
392
+ - **off** — merge `{"judge": {"llm_enabled": false}}` into `docs/adr/.adr-kit.json`. Say plainly that the declarative gate still runs and that `/adr-kit:judge` still gives LLM review on demand.
393
+
394
+ Ignore the local file in version control (idempotent):
395
+
396
+ ```bash
397
+ grep -q "\.adr-kit\.local\.json" .gitignore 2>/dev/null || echo "docs/adr/.adr-kit.local.json" >> .gitignore
398
+ ```
399
+
400
+ Then ask one more question (default No): `Enable per-commit ADR-suggest nudges (a second model call per commit, advisory only)? (y/N)` and merge `{"suggest": {"enabled": <true|false>}}`.
401
+
402
+ Confirm by showing the resolved configuration rather than by asserting it:
403
+
404
+ ```bash
405
+ "$ADR_KIT/bin/adr-judge" --adr-dir docs/adr --show-config
406
+ ```
407
+
408
+ Print the final one-liner: `Pre-commit ADR judge installed (declarative gate always-on; LLM pass on <backend>). Disable a single commit with ADR_KIT_HOOK_DISABLE=1 git commit ...; skip the LLM pass for one commit with ADR_KIT_NO_LLM=1 git commit ...; change the backend later with /adr-kit:judge settings; remove permanently with /adr-kit:install-hooks --uninstall.`
409
+
410
+ ## Step 5 — Final lint
411
+
412
+ Run the kit's lint binary on the freshly populated ADR directory:
413
+
414
+ ```bash
415
+ $ADR_KIT/bin/adr-lint docs/adr/
416
+ ```
417
+
418
+ Report the result: `<N PASS, M ADVISORY, K FAIL>`. If any FAIL: list them with the gate name and ask the user whether to fix now (re-invoke `adr-generator` for the offending ADR) or defer to a follow-up.
419
+
420
+ ## Step 5b — Guardian setup (new in v0.18.0)
421
+
422
+ After the hook and LLM opt-in are configured, offer the ADR Guardian.
423
+
424
+ Print this notice:
425
+
426
+ ```
427
+ [adr-guardian] The ADR Guardian is a SessionStart staleness detector (v0.18.0).
428
+ It checks ADR health at session start and nudges when a sweep is due:
429
+ - cheap tier (drift + retire + lint): daily, free
430
+ - LLM tier (suggest + audit): bi-weekly, asks before spending (~$0.10–0.30)
431
+ Two registration paths:
432
+ A. Plugin-level (default, recommended): auto-registers when the adr-kit plugin is enabled.
433
+ The guardian self-guards (no-ops silently in non-ADR projects).
434
+ B. Project-scoped: adds a SessionStart entry to .claude/settings.json (explicit, contained).
435
+ ```
436
+
437
+ Ask two questions (default A/No):
438
+
439
+ 1. `Enable guardian? (Y/n)` — Write `{"guardian": {"enabled": true}}` into `docs/adr/.adr-kit.json` (merge if present). If No: write `{"guardian": {"enabled": false}}` and skip the rest of this step.
440
+ 2. `Register project-scoped SessionStart hook in .claude/settings.json? (y/N)` — If yes, follow the instructions in `skills/install-hooks/SKILL.md` under "Adding the project-scoped guardian hook". If no, remind the user the plugin-level hook is used by default.
441
+
442
+ Add `.adr-kit-state.json` to the project's `.gitignore` (idempotent):
443
+
444
+ ```bash
445
+ grep -q "\.adr-kit-state\.json" .gitignore 2>/dev/null || echo "docs/adr/.adr-kit-state.json" >> .gitignore
446
+ ```
447
+
448
+ Confirm: `[adr-guardian] enabled (<path>); state file gitignored.`
449
+
450
+ ## Step 6 — Generate standalone validation scripts (optional)
451
+
452
+ Ask the user: "Generate standalone validation scripts for CI/CD pipelines? (Y/n)"
453
+
454
+ If yes:
455
+
456
+ ```bash
457
+ ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
458
+ "$ADR_KIT/bin/adr-generate-scripts" --lang shell --output .generated/
459
+ ```
460
+
461
+ This generates shell scripts in `.generated/<ADR-NNN>/validate.sh` that validate code against ADR Enforcement rules without requiring adr-kit. Useful for CI/CD pipelines that run outside Claude Code.
462
+
463
+ If the user says no (or presses Enter on the default), skip silently. If `.generated/` already contains scripts from a previous run, the generator overwrites them — this is idempotent.
464
+
465
+ ## Wrap-up
466
+
467
+ Print a final summary in this exact shape:
468
+
469
+ ```
470
+ adr-kit init complete:
471
+ - layout: <files setup-project.py wrote> (created | refreshed | unchanged)
472
+ - audit: <N> candidates → <X> kept, <Y> merged, <Z> dropped
473
+ - ADRs: <N> created, <M> already present
474
+ - hook: installed (or already present + reason)
475
+ - llm: backend <host|off>, suggest <enabled|disabled>
476
+ - guardian: <enabled|disabled> (plugin-level | project-scoped | disabled)
477
+ - lint: <P> PASS, <A> ADVISORY, <F> FAIL
478
+ - scripts: generated | skipped (user declined)
479
+ ```
480
+
481
+ Suggest a first commit staging exactly what was written: `git add docs/adr/ .adr-kit/ CLAUDE.md AGENTS.md .githooks/pre-commit && git commit -m "chore(adr-kit): bootstrap"`. Do not run the commit yourself; let the user inspect first.
482
+
483
+ ## Constraints
484
+
485
+ - **Do not skip steps.** Each step has an idempotency story; running them in order produces a consistent project state.
486
+ - **Batch selection, individual gates.** Do not silently mass-generate or
487
+ accept ADRs. Five to ten candidates may be triaged per round; the user
488
+ approves a batch, and every record still passes its own acceptance gates on
489
+ its own through `bin/adr accept --auto`. A record the user has not seen is
490
+ never accepted, and a record that fails a gate is never accepted regardless
491
+ of what the batch answer was.
492
+ - **Reconstruction is documentation, not authorisation.** Init records
493
+ decisions the code already implements, which is why `--auto` exists and why
494
+ it demands `documents_shipped: true` and a `verified_in` pointer before it
495
+ will run. A decision that is *not* already shipped is a new decision: it goes
496
+ through `/adr-kit:grill` and ordinary acceptance, never `--auto`.
497
+ - **Resolve the plugin path dynamically.** The kit lives at `~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/<version>/`. Use the `ls | sort -V | tail -1` resolver above; do not hardcode a version.
498
+ - **Preserve user CLAUDE.md content.** Only the marked stub block (or a v0.11-style `## ADR Kit Rules` section being replaced) may be modified. Everything else stays byte-exact.
499
+ - **Re-runnable.** A second invocation on a project where init already succeeded should detect the existing footprint and either skip or refresh, not regenerate.