@rvdbreemen/adr-kit-opencode 0.52.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 (129) hide show
  1. package/.claude-plugin/plugin.json +29 -0
  2. package/LICENSE +21 -0
  3. package/README.md +850 -0
  4. package/bin/adr +1552 -0
  5. package/bin/adr-audit +454 -0
  6. package/bin/adr-context +584 -0
  7. package/bin/adr-discover +546 -0
  8. package/bin/adr-doctor +166 -0
  9. package/bin/adr-generate-scripts +421 -0
  10. package/bin/adr-grill-signal +131 -0
  11. package/bin/adr-guardian +1263 -0
  12. package/bin/adr-index +199 -0
  13. package/bin/adr-judge +2832 -0
  14. package/bin/adr-judge-precommit +87 -0
  15. package/bin/adr-lint +2087 -0
  16. package/bin/adr-mcp +1093 -0
  17. package/bin/adr-migrate +644 -0
  18. package/bin/adr-quality +275 -0
  19. package/bin/adr-readiness +211 -0
  20. package/bin/adr-readiness-ci +111 -0
  21. package/bin/adr-related +401 -0
  22. package/bin/adr-renumber +254 -0
  23. package/bin/adr-retire +467 -0
  24. package/bin/adr-settings +399 -0
  25. package/bin/adr-status +797 -0
  26. package/bin/adr-suggest +803 -0
  27. package/bin/adr-watch +674 -0
  28. package/bin/adr_catalog.py +536 -0
  29. package/bin/adr_config.py +280 -0
  30. package/bin/adr_doctor_checks.py +407 -0
  31. package/bin/adr_doctor_core.py +342 -0
  32. package/bin/adr_doctor_models.py +186 -0
  33. package/bin/adr_doctor_probes.py +216 -0
  34. package/bin/adr_format.py +786 -0
  35. package/bin/adr_grill_signal.py +123 -0
  36. package/bin/adr_guardian_queue.py +218 -0
  37. package/bin/adr_history_scan.py +278 -0
  38. package/bin/adr_index_core.py +443 -0
  39. package/bin/adr_llm.py +333 -0
  40. package/bin/adr_llm_judge_migration.py +314 -0
  41. package/bin/adr_quality_core.py +674 -0
  42. package/bin/adr_query.py +678 -0
  43. package/bin/adr_readiness.py +442 -0
  44. package/bin/adr_readiness_ci.py +123 -0
  45. package/bin/adr_regex.py +165 -0
  46. package/bin/adr_regex_worker.py +30 -0
  47. package/bin/adr_retrieval_health.py +385 -0
  48. package/bin/adr_schema.py +448 -0
  49. package/bin/adr_state.py +172 -0
  50. package/bin/bump-version +71 -0
  51. package/clients/workflows.json +229 -0
  52. package/hooks/__init__.py +1 -0
  53. package/hooks/adapters/__init__.py +13 -0
  54. package/hooks/adapters/claude.py +27 -0
  55. package/hooks/adapters/codex.py +26 -0
  56. package/hooks/adapters/copilot.py +11 -0
  57. package/hooks/adr-hook.py +128 -0
  58. package/hooks/adr_hook_core.py +843 -0
  59. package/hooks/adr_pr_guard.py +367 -0
  60. package/instructions/ADR-guide.md +48 -0
  61. package/instructions/adr.coding.md +82 -0
  62. package/instructions/adr.review.md +182 -0
  63. package/opencode/plugin.ts +451 -0
  64. package/package.json +41 -0
  65. package/schemas/adr-context-probes.schema.json +56 -0
  66. package/schemas/adr-enforcement.schema.json +57 -0
  67. package/schemas/adr-frontmatter.schema.json +144 -0
  68. package/schemas/adr-index.schema.json +276 -0
  69. package/schemas/adr-kit-config.schema.json +371 -0
  70. package/schemas/adr-readiness.schema.json +41 -0
  71. package/schemas/client-capabilities.schema.json +503 -0
  72. package/schemas/client-certification.schema.json +101 -0
  73. package/schemas/doctor-output.schema.json +92 -0
  74. package/schemas/marketplace.json.schema.json +70 -0
  75. package/schemas/plugin.json.schema.json +67 -0
  76. package/scripts/adr_settings.py +239 -0
  77. package/scripts/benchmark-adr-grilling.py +323 -0
  78. package/scripts/benchmark-client-generation.py +178 -0
  79. package/scripts/build-client-adapters.py +139 -0
  80. package/scripts/bump-version.py +304 -0
  81. package/scripts/check-branch-sync.py +243 -0
  82. package/scripts/check-release-version.py +81 -0
  83. package/scripts/client_certification.py +153 -0
  84. package/scripts/client_evidence.py +280 -0
  85. package/scripts/client_generation.py +288 -0
  86. package/scripts/client_generation_artifacts.py +351 -0
  87. package/scripts/client_generation_model.py +173 -0
  88. package/scripts/client_generation_state.py +260 -0
  89. package/scripts/client_support_matrix.py +360 -0
  90. package/scripts/install-agent-envs.py +300 -0
  91. package/scripts/probe-client-events.py +183 -0
  92. package/scripts/project_setup.py +379 -0
  93. package/scripts/refresh-otgw-corpus.py +219 -0
  94. package/scripts/settings.py +81 -0
  95. package/scripts/setup-project.py +205 -0
  96. package/scripts/sync-agent-plugins.py +17 -0
  97. package/scripts/version_sites.py +377 -0
  98. package/skills/adr/SKILL.md +780 -0
  99. package/skills/audit/SKILL.md +103 -0
  100. package/skills/context/SKILL.md +77 -0
  101. package/skills/grill/SKILL.md +84 -0
  102. package/skills/grill/agents/openai.yaml +4 -0
  103. package/skills/guardian/SKILL.md +316 -0
  104. package/skills/init/SKILL.md +499 -0
  105. package/skills/install-hooks/SKILL.md +154 -0
  106. package/skills/judge/SKILL.md +168 -0
  107. package/skills/lint/SKILL.md +321 -0
  108. package/skills/migrate/SKILL.md +313 -0
  109. package/skills/related/SKILL.md +62 -0
  110. package/skills/retire/SKILL.md +41 -0
  111. package/skills/review/SKILL.md +167 -0
  112. package/skills/settings/SKILL.md +73 -0
  113. package/skills/setup/SKILL.md +128 -0
  114. package/skills/supersede/SKILL.md +136 -0
  115. package/skills/upgrade/SKILL.md +273 -0
  116. package/templates/adr-kit-guide.md +354 -0
  117. package/templates/adr-template.canonical.md +115 -0
  118. package/templates/adr-template.madr.md +131 -0
  119. package/templates/adr-template.md +131 -0
  120. package/templates/adr-template.nygard.md +111 -0
  121. package/templates/cc-settings/guardian-hook-entry.json +9 -0
  122. package/templates/githooks/pre-commit +337 -0
  123. package/templates/github-workflows/adr-audit.yml +58 -0
  124. package/templates/github-workflows/adr-guardian-audit.yml +133 -0
  125. package/templates/github-workflows/adr-index-check.yml +30 -0
  126. package/templates/github-workflows/adr-judge.yml +31 -0
  127. package/templates/github-workflows/adr-readiness.yml +18 -0
  128. package/templates/validate_adr_template.py +38 -0
  129. package/templates/validate_adr_template.sh +74 -0
@@ -0,0 +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.
@@ -0,0 +1,154 @@
1
+ ---
2
+ name: install-hooks
3
+ description: "Install or remove ADR Kit's deterministic pre-commit gate. Use for ADR hooks, pre-commit enforcement, or uninstalling the owned git hook."
4
+ argument-hint: "[--uninstall]"
5
+ disable-model-invocation: true
6
+ allowed-tools: [Read, Write, Edit, Bash]
7
+ ---
8
+
9
+ # adr-kit install-hooks
10
+
11
+ This is the **hooks** mode of `/adr-kit:setup` (spec R19: one entry point,
12
+ four modes). Invoked directly or via `/adr-kit:setup hooks`, the procedure
13
+ is identical -- this file owns it.
14
+
15
+ Use `$ARGUMENTS` only for `--uninstall`; empty means install. Reject all other
16
+ arguments.
17
+
18
+ You install or uninstall the adr-kit pre-commit hook in the project the user is currently in (`pwd` should be the project root).
19
+
20
+ ## Default behaviour: install
21
+
22
+ ### Step 1 — Resolve the plugin's hook template
23
+
24
+ ```bash
25
+ ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
26
+ TEMPLATE="$ADR_KIT/templates/githooks/pre-commit"
27
+ ```
28
+
29
+ If `$TEMPLATE` does not exist or is empty, exit with an error: the plugin install is broken; tell the user to reinstall via `/plugin install adr-kit@rvdbreemen-adr-kit`.
30
+
31
+ ### Step 2 — Detect existing hooks
32
+
33
+ Three cases:
34
+
35
+ - **No `.githooks/pre-commit`.** Mkdir `.githooks/`, copy the template, `chmod +x`, set `core.hooksPath`. Done.
36
+ - **Existing `.githooks/pre-commit` is byte-identical to the template.** No-op. Tell the user it's already installed.
37
+ - **Existing `.githooks/pre-commit` differs.** Read both. Show the user the existing content (truncated to first 30 lines). Ask:
38
+ - `prepend adr-kit before existing` — write a wrapper script that calls adr-kit then `exec`s the original. Save the original as `.githooks/pre-commit.adr-kit-saved`.
39
+ - `replace` — overwrite. Save the old hook as `.githooks/pre-commit.backup-<timestamp>` for safety.
40
+ - `abort` — do nothing.
41
+ Apply the user's choice.
42
+
43
+ ### Step 3 — Activate
44
+
45
+ Run `git config core.hooksPath .githooks`. Confirm with `git config --get core.hooksPath`. If the project already has `core.hooksPath` set to a different directory, do NOT overwrite — tell the user, ask whether to change the config or to symlink the hook into the existing hooks dir.
46
+
47
+ ### Step 4 — Confirm
48
+
49
+ Print:
50
+
51
+ ```
52
+ Pre-commit ADR judge installed.
53
+ - hook: .githooks/pre-commit (mode 755)
54
+ - core.hooksPath: .githooks
55
+ - disable a single commit: ADR_KIT_HOOK_DISABLE=1 git commit ...
56
+ - remove permanently: /adr-kit:install-hooks --uninstall
57
+ - LLM pass is opt-in (off by default). Enable per-project: judge.llm_enabled:true in docs/adr/.adr-kit.json. Enable one commit: ADR_KIT_LLM=1 git commit ...
58
+ - ADR-suggest is opt-in too: suggest.enabled:true, or ADR_KIT_SUGGEST=1 for one commit.
59
+ ```
60
+
61
+ ## Uninstall behaviour: `--uninstall`
62
+
63
+ When invoked as `/adr-kit:install-hooks --uninstall`:
64
+
65
+ 1. Read `.githooks/pre-commit`. Verify it is the adr-kit hook (look for the line `# adr-kit pre-commit hook` near the top). If it is NOT the adr-kit hook, refuse — tell the user the hook in place isn't ours and we won't touch it.
66
+ 2. Three paths:
67
+ - **No saved original** (`.githooks/pre-commit.adr-kit-saved` does not exist). Remove `.githooks/pre-commit`. If `.githooks/` is now empty, remove it too. Run `git config --unset core.hooksPath`.
68
+ - **Saved original exists.** Restore: rename `.githooks/pre-commit.adr-kit-saved` → `.githooks/pre-commit`. Leave `core.hooksPath` set to `.githooks`.
69
+ - **`.githooks/pre-commit.backup-<timestamp>` exists** (from a prior `replace` install). Tell the user the backup is there and ask whether to restore that instead. Apply choice.
70
+ 3. Confirm with one line: `Pre-commit ADR judge uninstalled. (restored prior hook | removed .githooks/ | unset core.hooksPath)`
71
+
72
+ ## Guardian (SessionStart) hook — project-scoped install
73
+
74
+ The ADR Guardian has **two registration paths** (spec §7):
75
+
76
+ - **Plugin-level (default, frictionless):** The adr-kit plugin declares a `SessionStart` hook in its manifest. It auto-registers in every Claude Code session when the plugin is enabled globally, and self-guards (exits silently when no `docs/adr/` with ADRs is present). This is the recommended path.
77
+ - **Project-scoped (explicit):** Adds the guardian's `SessionStart` entry directly to the project's `.claude/settings.json`. Contained to this project only. Use when the user wants explicit per-project control or does not enable the plugin globally.
78
+
79
+ ### Adding the project-scoped guardian hook
80
+
81
+ When the user asks to add the guardian hook to the project's `.claude/settings.json`:
82
+
83
+ 1. Read `.claude/settings.json` (create it as `{}` if missing).
84
+ 2. Check if `hooks.SessionStart` already contains an entry whose `command` contains the string `adr-guardian`. If yes: print "Already installed" and stop.
85
+ 3. If no SessionStart array exists: create it. Parse the JSON structurally — never do text substitution on a JSON file.
86
+ 4. Append the following hook object to `hooks.SessionStart[0].hooks` (create the array path if absent):
87
+
88
+ ```json
89
+ {
90
+ "type": "command",
91
+ "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",
92
+ "timeout": 10
93
+ }
94
+ ```
95
+
96
+ 5. Write the updated JSON back. The existing `SessionStart` hooks (if any) are **preserved byte-for-byte** — only the new entry is appended.
97
+ 6. Confirm: "Guardian hook added to .claude/settings.json. It will fire at the next session start."
98
+
99
+ ### Removing the project-scoped guardian hook
100
+
101
+ When the user asks to remove the guardian hook from `.claude/settings.json`:
102
+
103
+ 1. Read `.claude/settings.json`. Parse as JSON.
104
+ 2. Find entries in `hooks.SessionStart[*].hooks[*]` whose `command` contains `adr-guardian`. If none found: print "Guardian hook not found in .claude/settings.json" and stop.
105
+ 3. Remove exactly those entries. Leave all sibling hooks untouched.
106
+ 4. If the containing `hooks` array becomes empty after removal, remove the empty array (but keep the parent `SessionStart` entry if other entries exist in other groups).
107
+ 5. Write the updated JSON back.
108
+ 6. Confirm: "Guardian hook removed from .claude/settings.json."
109
+
110
+ **Safety invariant:** Never remove or modify any hook entry that does not contain `adr-guardian` in its `command`. This is the cozempic lesson — a remove that also clobbers unrelated hooks is worse than not removing at all.
111
+
112
+ ### Adding .adr-kit-state.json to .gitignore
113
+
114
+ After adding the guardian hook (project-scoped or as part of `/adr-kit:init`):
115
+
116
+ ```bash
117
+ echo "docs/adr/.adr-kit-state.json" >> .gitignore
118
+ ```
119
+
120
+ Verify it is not already present first (idempotent). The state file is per-machine and must never be committed.
121
+
122
+ ## CI gates — offer the shipped workflow templates
123
+
124
+ The git hook judges one commit. Two gates that a hook cannot cover ship as
125
+ copyable workflows in `templates/github-workflows/`; offer them, do not install
126
+ them silently, because a workflow file is the project's business:
127
+
128
+ - **`adr-judge.yml`** — judges the whole branch on every pull request. This is
129
+ what the reviewer is actually being asked to accept, and it uses the CI-sized
130
+ diff budget so raising it never weakens the commit-time gate.
131
+ - **`adr-readiness.yml`** — refuses to merge implementation that is linked to a
132
+ Proposed decision nobody accepted.
133
+ - **`adr-guardian-audit.yml`** — the weekly staleness sweep, reported into one
134
+ tracking issue.
135
+ - **`adr-index-check.yml`** — fails when the generated indexes no longer match
136
+ the ADRs. The commit hook can only warn about this, because it reads the
137
+ worktree while the commit is the staged snapshot; CI checks out the commit
138
+ itself, so it is the only place the block is honest.
139
+
140
+ Copy on request into `.github/workflows/`, and tell the user the checkout must
141
+ use `fetch-depth: 0` or the diff has only one side.
142
+
143
+ Note for Claude Code users: the branch is also judged *before* the pull request
144
+ exists, by the pre-tool guard on `gh pr create`. The workflow remains worth
145
+ installing anyway - it covers pushes from a laptop, a different client, and
146
+ anyone not working through an agent at all.
147
+
148
+ ## Constraints
149
+
150
+ - **Never silently overwrite a pre-existing user hook.** Always detect, show, ask.
151
+ - **Set `core.hooksPath` only when needed.** If the user already has it pointing at a custom dir, propose a symlink rather than redirecting their config.
152
+ - **Idempotent in both directions.** Re-running install when already installed is a no-op. Re-running uninstall when nothing is installed is a no-op (with a warning).
153
+ - **`chmod +x`** the hook after writing — without the executable bit, git silently ignores it.
154
+ - **Do not commit the hook.** The hook lives in `.githooks/`, which the project may or may not have in `.gitignore`. Don't add it to git here; the user decides whether to track it.