@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.
- package/.claude-plugin/plugin.json +29 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- 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.
|