@rvdbreemen/adr-kit-opencode 0.52.0 → 0.52.2

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 (82) hide show
  1. package/.claude-plugin/plugin.json +29 -29
  2. package/README.md +861 -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 +0 -0
  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/bump-version +0 -0
  28. package/clients/workflows.json +229 -229
  29. package/hooks/__init__.py +1 -1
  30. package/hooks/adapters/__init__.py +13 -13
  31. package/hooks/adapters/claude.py +27 -27
  32. package/hooks/adapters/codex.py +26 -26
  33. package/hooks/adapters/copilot.py +11 -11
  34. package/hooks/adr-hook.py +128 -128
  35. package/hooks/adr_hook_core.py +843 -843
  36. package/hooks/adr_pr_guard.py +367 -367
  37. package/instructions/ADR-guide.md +48 -48
  38. package/instructions/adr.coding.md +82 -82
  39. package/instructions/adr.review.md +182 -182
  40. package/opencode/plugin.ts +1 -4
  41. package/package.json +5 -2
  42. package/schemas/adr-context-probes.schema.json +56 -56
  43. package/schemas/adr-enforcement.schema.json +57 -57
  44. package/schemas/adr-frontmatter.schema.json +144 -144
  45. package/schemas/adr-index.schema.json +276 -276
  46. package/schemas/adr-kit-config.schema.json +371 -371
  47. package/schemas/adr-readiness.schema.json +41 -41
  48. package/schemas/client-capabilities.schema.json +503 -503
  49. package/schemas/client-certification.schema.json +101 -101
  50. package/schemas/doctor-output.schema.json +92 -92
  51. package/skills/adr/SKILL.md +780 -780
  52. package/skills/audit/SKILL.md +103 -103
  53. package/skills/context/SKILL.md +77 -77
  54. package/skills/grill/SKILL.md +84 -84
  55. package/skills/grill/agents/openai.yaml +4 -4
  56. package/skills/guardian/SKILL.md +316 -316
  57. package/skills/init/SKILL.md +499 -499
  58. package/skills/install-hooks/SKILL.md +154 -154
  59. package/skills/judge/SKILL.md +168 -168
  60. package/skills/lint/SKILL.md +321 -321
  61. package/skills/migrate/SKILL.md +313 -313
  62. package/skills/related/SKILL.md +62 -62
  63. package/skills/retire/SKILL.md +41 -41
  64. package/skills/review/SKILL.md +167 -167
  65. package/skills/settings/SKILL.md +73 -73
  66. package/skills/setup/SKILL.md +128 -128
  67. package/skills/supersede/SKILL.md +136 -136
  68. package/skills/upgrade/SKILL.md +273 -273
  69. package/templates/adr-kit-guide.md +354 -354
  70. package/templates/adr-template.canonical.md +115 -115
  71. package/templates/adr-template.madr.md +131 -131
  72. package/templates/adr-template.md +131 -131
  73. package/templates/adr-template.nygard.md +111 -111
  74. package/templates/cc-settings/guardian-hook-entry.json +9 -9
  75. package/templates/githooks/pre-commit +1 -1
  76. package/templates/github-workflows/adr-audit.yml +58 -58
  77. package/templates/github-workflows/adr-guardian-audit.yml +133 -133
  78. package/templates/github-workflows/adr-index-check.yml +30 -30
  79. package/templates/github-workflows/adr-judge.yml +31 -31
  80. package/templates/github-workflows/adr-readiness.yml +18 -18
  81. package/templates/validate_adr_template.py +38 -38
  82. package/templates/validate_adr_template.sh +74 -74
@@ -1,780 +1,780 @@
1
- ---
2
- name: adr
3
- description: "Create or review Architecture Decision Records. Use for ADRs, architecture decisions, durable trade-offs, new dependencies, contracts, or patterns."
4
- argument-hint: "[short title of the decision]"
5
- license: MIT
6
- ---
7
-
8
- # ADR Skill: Architecture Decision Record Management
9
-
10
- Use `$ARGUMENTS` as the decision title or review target. If it is empty, infer
11
- the target only from the user's current request; otherwise ask one short question.
12
-
13
- ## Overview
14
-
15
- This skill enables systematic creation, maintenance, and enforcement of Architecture Decision Records. ADRs document significant architectural choices along with their context, alternatives considered, and consequences. They serve as living documentation so current and future developers (and AI agents) understand why the system is built the way it is.
16
-
17
- ## Guided authoring contract
18
-
19
- Treat `/adr-kit:adr <subject>` as the complete creation flow; do not add or
20
- suggest a separate create command.
21
-
22
- 1. First decide whether the subject is consequential and difficult to reverse.
23
- End with no ADR for an ordinary implementation choice.
24
- 2. For a qualifying subject, invoke `python <plugin-root>/bin/adr propose` so
25
- the lifecycle command creates a `Proposed` record.
26
- 3. Continue with `/adr-kit:grill ADR-NNN`. Cover context, decision,
27
- alternatives, consequences, evidence, scope, ownership, conflicts, and Open
28
- Questions. Also propose concise retrieval topics/components/symbols and a
29
- Decision Contract from settled facts so future agents can query the record
30
- selectively; the human reviews these candidates with the decision.
31
- 4. Show an acceptance packet containing decision, rationale, alternatives,
32
- consequences, evidence, scope, conflicts, and lifecycle effect. Require an
33
- explicit `yes` in this active session.
34
- 5. Only then invoke `python <plugin-root>/bin/adr accept ADR-NNN --confirm`.
35
- The flag is refused-by-default for a reason: without it an acceptance can
36
- happen by accident, and it writes a name into a history that is immutable
37
- afterwards. Pass it only after the human has said yes in this session.
38
- Missing
39
- evidence, strict lint failures, conflicts, and unresolved Open Questions
40
- remain authoritative blockers and become the next grill question.
41
-
42
- The skill bundles three patterns that distinguish it from a basic ADR template:
43
-
44
- 1. **Anti-Rationalization Guards**: a table of excuses agents and humans use to skip writing an ADR, paired with counter-arguments. Pre-flight discipline.
45
- 2. **Verification Gates**: four named gates an ADR must pass before its Status flips from `Proposed` to `Accepted`. Reviewers can block on a single named gate.
46
- 3. **Human Decision Documentation**: explicit `Decision Maker:` attribution so user-driven choices are visible in the record, distinct from agent-generated ADRs.
47
-
48
- ---
49
-
50
- ## When to Use
51
-
52
- ### Automatic triggers
53
-
54
- Use this skill automatically when:
55
-
56
- - Reviewing a PR or analysing code changes for architectural impact.
57
- - A change introduces a new pattern, dependency, or contract.
58
- - Refactoring proposals affect system design.
59
- - A user asks an architectural question ("why did we choose X?", "should we use Y or Z?").
60
-
61
- ### Explicit triggers
62
-
63
- Use this skill when the user mentions:
64
-
65
- - "Create an ADR" / "Document this decision" / "Architecture decision".
66
- - "Why did we choose...?" / "What alternatives did we consider?".
67
- - "Document my choice" / "Capture this trade-off".
68
-
69
- ### Decision triggers
70
-
71
- Create a new ADR when making a decision that:
72
-
73
- - Has long-term impact on architecture.
74
- - Affects multiple components or modules.
75
- - Involves trade-offs between alternatives.
76
- - Constrains future development choices.
77
- - Addresses a significant technical challenge.
78
- - Changes existing architectural patterns.
79
- - Requires a human decision that should be preserved.
80
-
81
- ### Do NOT create an ADR for
82
-
83
- - Bug fixes that do not change architecture.
84
- - Refactors that maintain the same external behaviour.
85
- - Configuration changes within an existing range.
86
- - Documentation updates (unless the doc *is* an ADR).
87
- - Minor feature additions within established patterns.
88
- - Temporary workarounds or experiments.
89
-
90
- ---
91
-
92
- ## Anti-Rationalization Guards
93
-
94
- ADRs fail not from lack of templates but from the agent (or human) talking themselves out of writing one. Below is a table of common excuses with their counter-arguments. When you hear yourself reaching for one of the left-column entries, stop and apply the right-column response.
95
-
96
- | Excuse | Counter-argument |
97
- |---|---|
98
- | "This decision is obvious" | Obvious to you, today, with the context fresh in your head. Not obvious to a maintainer in six months, an open-source contributor, or an AI agent reviewing the PR. Document the *why*. |
99
- | "I'll document it later" | You will not. The pattern goes in once and only comes out if a future bug forces it out. Cost of writing now: 15 to 30 minutes. Cost of re-deriving later: hours, sometimes a full incident. |
100
- | "The code speaks for itself" | Code shows *what* and *how*. ADRs document *why*. The why is never derivable from source: it lives in the constraints, the alternatives that were rejected, and the trade-offs accepted. |
101
- | "Everyone knows this pattern" | Everyone on the team *today*. Not the maintainer in three years. Not the contributor who shows up next week. Not the model running a future code review. |
102
- | "This is just the framework default" | Then say so explicitly. "Status: Accepted. We took the framework default for X because Y." Defaults embed assumptions; an ADR makes those assumptions inspectable. |
103
- | "It is too small to need an ADR" | Small *architecturally*? Then no ADR. Small *implementation* of a contract change? Still an ADR, because the contract is what future developers will trip over. |
104
- | "We can always change it later" | Every architectural choice constrains the next one. Document the chosen path now so a future change is a *deliberate* supersede, not an accidental drift. |
105
- | "I don't have time" | Pay 30 minutes now or pay hours when someone challenges the choice in code review six months from now and nobody can remember the rationale. |
106
- | "There are no real alternatives" | Almost never true. If you cannot name one, the alternative is "do nothing" or "the framework default": that is an alternative. Document it and the reason it lost. |
107
-
108
- This pattern was originally introduced by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) and was first combined with verification gates in a single ADR skill by [Jim van den Breemen's adr-skill](https://github.com/Jvdbreemen/adr-skill); `adr-kit` adapts that pairing.
109
-
110
- ---
111
-
112
- ## Initial Codebase Analysis
113
-
114
- ### First-time use: discovering undocumented decisions
115
-
116
- When introducing this skill to an existing codebase, perform a comprehensive architectural analysis to identify and document existing but undocumented decisions.
117
-
118
- #### Workflow
119
-
120
- **Step 1: identify architectural patterns.** Areas to analyse:
121
-
122
- - Platform and runtime choices (language, framework, deployment target).
123
- - Data and storage (database, schema, persistence patterns).
124
- - Protocol and integration (sync vs async, REST vs RPC, message bus).
125
- - Memory and resource management (when load-bearing).
126
- - Network and security (TLS posture, auth model, trust boundaries).
127
- - Build and tooling (build system, CI gates, test strategy).
128
- - Cross-cutting concerns (logging, error handling, observability).
129
-
130
- **Step 2: ask critical questions.** For each pattern discovered:
131
-
132
- - WHY was this approach chosen? (context, constraints).
133
- - WHAT alternatives exist? (at least 2 to 3 viable options).
134
- - WHY were alternatives rejected? (specific technical reasons).
135
- - WHAT are the consequences? (benefits, costs, risks).
136
- - HOW is this implemented? (code references, key files).
137
- - WHEN was this decided? (estimate from git log or release history if unknown).
138
-
139
- **Step 3: generate ADRs systematically.** For each undocumented decision:
140
-
141
- 1. Use a research subagent to understand the pattern.
142
- 2. Review code, comments, git history for context.
143
- 3. Identify constraints (memory, performance, compatibility, security).
144
- 4. Research alternatives even if obvious.
145
- 5. Document consequences: positive AND negative.
146
- 6. Create the ADR with `Status: Proposed`, even when code already shipped.
147
- 7. Link to actual implementation (files, commits), then grill the reconstructed
148
- rationale and request independent acceptance for this ADR.
149
-
150
- **Step 4: prioritize.** Start with foundational decisions that:
151
-
152
- - Affect multiple components.
153
- - Constrain future choices.
154
- - Are non-obvious or counterintuitive.
155
- - Have significant trade-offs.
156
- - Are frequently questioned.
157
-
158
- #### Trigger phrases
159
-
160
- ```
161
- "Analyze this codebase to identify undocumented architectural decisions"
162
- "Generate ADRs for existing architectural patterns in this codebase"
163
- "What architectural decisions should be documented in this project?"
164
- ```
165
-
166
- ---
167
-
168
- ## ADR Principles
169
-
170
- ### The golden rules
171
-
172
- 1. **One decision per ADR.** Each ADR captures a single architectural choice.
173
- 2. **Immutable history.** Never modify accepted ADRs; supersede with a new one instead.
174
- 3. **Context is king.** Explain WHY the decision was made, not just WHAT.
175
- 4. **Alternatives matter.** Document what was considered but rejected.
176
- 5. **Human decisions marked.** Clearly indicate when the decision came from a user or stakeholder.
177
- 6. **Critical analysis.** Be thorough, question assumptions, document trade-offs honestly.
178
- 7. **Understandable language.** Write for a developer unfamiliar with the decision; avoid unexplained jargon.
179
-
180
- ### Best practices
181
-
182
- ```
183
- GOOD AVOID
184
- Write for future developers Use jargon without explanation
185
- Include code examples Assume reader knows the context
186
- Reference related ADRs Skip alternatives ("only way")
187
- Use clear, simple language Make assumptions unstated
188
- Document driving constraints Forget to update status when superseding
189
- Explain consequences both ways Be vague ("better", "improves performance")
190
- Link to implementation Skip negative consequences
191
- Be critical, document risks Write marketing copy
192
- Provide specific evidence Use jargon without defining it
193
- ```
194
-
195
- ---
196
-
197
- ## Verification Gates
198
-
199
- An ADR moves from `Status: Proposed` to `Status: Accepted` only after all four gates pass. The gates are intentionally *named* so a reviewer can cite a single gate when blocking acceptance: "This ADR fails the Evidence gate, please add measurements."
200
-
201
- ### Gate 1: Completeness
202
-
203
- The ADR has filled every load-bearing section.
204
-
205
- - [ ] Problem statement is unambiguous; a reader knows what the decision is *about*
206
- - [ ] Decision is stated as a single, declarative sentence (not a discussion)
207
- - [ ] At least 2 alternatives considered, each with a "why not chosen" line
208
- - [ ] Consequences are listed in *both* directions (positive and negative); a one-sided ADR fails this gate
209
- - [ ] Risks are named explicitly, each with at least one mitigation
210
-
211
- ### Gate 2: Evidence
212
-
213
- Every claim that a reader could challenge is backed by something verifiable.
214
-
215
- - [ ] No bare adjectives where numbers are achievable: "saves 5 to 8 KB RAM" beats "saves memory"; "reduces request latency from 120 ms to 40 ms" beats "faster"
216
- - [ ] Constraint claims are anchored to a source: "the runtime allows 256 MB per worker" cites where (vendor doc, measured, ops policy)
217
- - [ ] Code references include `file:line` so the reviewer can verify
218
- - [ ] External claims (specs, RFCs, vendor docs) are linked, not paraphrased
219
-
220
- ### Gate 3: Clarity
221
-
222
- A reader who has never seen this codebase can follow the argument.
223
-
224
- - [ ] Acronyms defined on first use: "TLS (Transport Layer Security)"
225
- - [ ] Technical concepts explained when load-bearing: "back-pressure: a feedback signal from a slower consumer to a faster producer"
226
- - [ ] Code examples are concrete and runnable, not pseudo-code
227
- - [ ] The decision is explainable in one paragraph at the top, before the reader needs to read the alternatives
228
-
229
- ### Gate 4: Consistency
230
-
231
- The ADR fits the existing record without creating contradictions.
232
-
233
- - [ ] No conflict with an `Accepted` ADR; if there is, this ADR is a supersede with explicit reference
234
- - [ ] Cross-references to related ADRs are present and accurate
235
- - [ ] Terminology matches the project glossary and other ADRs
236
- - [ ] ADR number is the next sequential, no gap, no reuse
237
-
238
- This pattern was originally introduced by [trailofbits/skills](https://github.com/trailofbits/skills) and was first combined with anti-rationalization guards in a single ADR skill by [Jim van den Breemen's adr-skill](https://github.com/Jvdbreemen/adr-skill); `adr-kit` adapts that pairing.
239
-
240
- ---
241
-
242
- ## ADR Template
243
-
244
- MADR is the default profile. Create from the project configuration with:
245
-
246
- ```text
247
- python bin/adr profiles --format json
248
- python bin/adr new "Short imperative title" --adr-dir docs/adr
249
- ```
250
-
251
- Use `--profile madr|nygard|canonical` for a one-record override. The bundled
252
- templates are `templates/adr-template.{madr,nygard,canonical}.md`; the
253
- unqualified `templates/adr-template.md` is the MADR default. All profiles keep
254
- frontmatter, Status, Status History, Related Decisions, References, and
255
- Enforcement invariant. The older example below is the `canonical` profile,
256
- retained for backward-compatible projects.
257
-
258
- When the user requests a non-default format, first read the JSON catalog.
259
- Accept only a returned `id`, require `available: true`, and scaffold from that
260
- entry's `template` path through `adr new --profile <id>`. Never invent a
261
- profile name, infer one from an arbitrary filename, hand-map headings, or
262
- generate a substitute for a missing shipped template.
263
-
264
- ```markdown
265
- ---
266
- id: "ADR-XXX"
267
- title: "Title in title case"
268
- status: Proposed
269
- date: "YYYY-MM-DD"
270
- binding: false
271
- gate: null
272
- documents_shipped: false
273
- verified_in: []
274
- supersedes: []
275
- superseded_by: null
276
- format: canonical
277
- ---
278
-
279
- # ADR-XXX Title in title case
280
-
281
- ## Status
282
-
283
- Proposed, YYYY-MM-DD.
284
-
285
- (Later: Accepted; Deprecated; Rejected; Superseded by ADR-YYY; or Amended by ADR-YYY.)
286
-
287
- ## Status History
288
-
289
- status_history:
290
- - date: YYYY-MM-DD
291
- status: Proposed
292
- changed_by: Agent or User
293
- reason: Initial proposal
294
- changed_via: adr-kit
295
-
296
- ## Context
297
-
298
- One paragraph stating the problem clearly enough for a reader who has never seen this codebase. Include the constraints that drove the decision and the existing state that triggered the choice.
299
-
300
- ## Decision
301
-
302
- A single declarative sentence stating what was chosen. Optionally followed by 2 to 4 short paragraphs unpacking the choice.
303
-
304
- ## Alternatives Considered
305
-
306
- ### Alternative A: name
307
-
308
- Description and rejection reasoning.
309
-
310
- ### Alternative B: name
311
-
312
- (repeat structure)
313
-
314
- ### Alternative C: do nothing
315
-
316
- If "do nothing" was rejected, document why. If it was the right choice, this ADR is probably not needed.
317
-
318
- ## Consequences
319
-
320
- **Benefits**
321
-
322
- - Specific positive outcomes, with measurements when achievable.
323
-
324
- **Trade-offs**
325
-
326
- - The cost we accepted by making this choice.
327
-
328
- **Risks and mitigations**
329
-
330
- - *Risk*: what could go wrong. *Mitigation*: how we address it.
331
-
332
- ## Related Decisions
333
-
334
- - **ADR-YYY (Title)**: how it relates (supersedes, amends, depends on, complements).
335
-
336
- ## References
337
-
338
- - Implementation tasks or issue IDs.
339
- - Source files affected (file:line).
340
- - External specs, RFCs, vendor docs, or measurements.
341
- ```
342
-
343
- A clean copy is available at `examples/ADR-template.md`.
344
-
345
- ---
346
-
347
- ## Naming Convention
348
-
349
- ### Default
350
-
351
- ```
352
- Format: ADR-XXX-short-descriptive-title.md
353
-
354
- Where:
355
- - XXX = zero-padded sequential number (001, 002, ..., 099, 100, etc.)
356
- - short-descriptive-title = kebab-case description
357
-
358
- Examples:
359
- - ADR-001-postgresql-for-sensor-data.md
360
- - ADR-014-rest-api-versioning.md
361
- - ADR-042-grpc-internal-rpc.md
362
- - ADR-099-deprecated-static-bundling.md
363
-
364
- Wrong:
365
- - ADR-1-postgresql.md (not zero-padded)
366
- - adr-001-PostgreSQL.md (lowercase prefix, mixed case)
367
- - ADR-001_PostgreSQL.md (underscore instead of hyphen)
368
- ```
369
-
370
- ### Number assignment
371
-
372
- - Sequential numbering starting from 001.
373
- - Check `docs/adr/` for the highest number and increment.
374
- - Do not reuse numbers from deprecated or superseded ADRs.
375
- - Do not leave gaps in numbering.
376
-
377
- ### Project override
378
-
379
- The filename contract remains fixed. Select the body profile with
380
- `template.profile` in `docs/adr/.adr-kit.json`; choose `madr` (default),
381
- `nygard`, or `canonical`. A per-file `format` value is authoritative.
382
-
383
- ---
384
-
385
- ## ADR Categories
386
-
387
- Group ADRs by architectural domain for navigation. The category list is project-specific; below is a neutral starting set you can replace:
388
-
389
- - **Platform and Runtime**: language, framework, runtime, deployment target.
390
- - **Data and Storage**: database, schema, persistence, caching.
391
- - **Protocol and Integration**: sync vs async, REST/RPC/messaging, contracts.
392
- - **Memory and Resources**: when load-bearing for the project's constraints.
393
- - **Network and Security**: TLS posture, auth, trust boundaries, secrets.
394
- - **Build and Tooling**: build system, CI gates, packaging, testing.
395
- - **Observability**: logging, metrics, tracing, alerting.
396
- - **Cross-Cutting**: error handling, configuration, internationalization.
397
-
398
- In your `docs/adr/README.md`, replace these with categories that match your domain.
399
-
400
- ---
401
-
402
- ## ADR Workflow
403
-
404
- ### 1. Before making architectural changes
405
-
406
- - Run the local doctor to repair the generated index and surface ADR health issues before relying on the decision log: `bin/adr-doctor --fix-index docs/adr/`.
407
- - Review existing ADRs (`docs/adr/README.md` index).
408
- - Search for related decisions.
409
- - Check whether the change conflicts with any `Accepted` ADR.
410
- - Determine if a new ADR is needed (long-term impact? multiple components? alternatives exist? future context?).
411
-
412
- ### 2. During implementation
413
-
414
- - Create the ADR with `Status: Proposed`.
415
- - Run `python bin/adr new "Title" --adr-dir docs/adr`; it allocates the next
416
- number and honors `template.profile`.
417
- - Complete the selected profile without renaming its semantic headings.
418
- - Reference the ADR in code comments at non-obvious enforcement sites: `// See ADR-XXX for why we use this pattern.`
419
- - Implement according to the ADR's decision.
420
-
421
- ### 3. After implementation
422
-
423
- - Update Status: `Proposed` -> `Accepted`.
424
- - Add the implementation date in the Status line: `Accepted. Date: YYYY-MM-DD.`
425
- - Append the matching `Accepted` transition to `## Status History`; never rewrite an earlier entry.
426
- - **Decide which cross-references are warranted, then let the tool write both
427
- sides.** Read the existing set (`bin/adr-index --adr-dir docs/adr --format md`
428
- is the compact map) and ask, for each candidate, whether a reader arriving at
429
- the *other* ADR would need to know this one exists. That judgement is yours;
430
- no regex can make it. It is a real relationship when the two decisions
431
- constrain each other, when one is the reason the other is possible, or when
432
- changing one would force a rethink of the other. It is not a relationship
433
- merely because both mention the same file.
434
- - For each one you decide on: `bin/adr relate ADR-NEW --to ADR-OTHER`. It
435
- writes the `related` field on **both** ADRs in one transaction and
436
- regenerates the indexes, so neither side can end up carrying half a link.
437
- Wrong call? `--remove` unwinds both sides the same way.
438
- - Prose in `## Related Decisions` still counts and still reads well; keep
439
- writing it. What it cannot do is update the other ADR, which is why the
440
- reciprocal link goes in frontmatter. A backwards-only prose citation is
441
- normal and is never flagged.
442
- - Do not hand-edit the `related` field. `adr-lint` FAILs a one-sided one,
443
- because the only way to produce one is a hand edit or a half-applied write.
444
- - Refresh the generated README, compact Markdown index, and JSON graph with
445
- `bin/adr-index docs/adr/`.
446
- - Run `bin/adr-doctor --fix-index docs/adr/` or `bin/adr-lint --strict docs/adr/` before treating the ADR set as clean.
447
-
448
- ### 4. When superseding an ADR
449
-
450
- - Write the new ADR explaining the change.
451
- - Reference the original in `## Related Decisions`: "Supersedes ADR-XXX (Title)".
452
- - Update the old ADR's Status line to `Superseded by ADR-YYY` and append that transition to `## Status History`.
453
- - Do NOT modify the old ADR's decision text or reasoning. Immutability is the rule.
454
- - Refresh all generated index views through `bin/adr-index docs/adr/` so both
455
- sides appear in `README.md`, `ADR-INDEX.md`, and `ADR-INDEX.json`.
456
-
457
- ### 5. When amending an ADR (lighter alternative to supersession)
458
-
459
- - Write the amending ADR.
460
- - Reference the original in `## Related Decisions`: "Amends ADR-XXX (Title)".
461
- - Update the old ADR's Status line: `Amended by ADR-YYY` (or leave as `Accepted` if the amend is content-additive).
462
- - Do NOT modify the old ADR's decision text.
463
-
464
- ---
465
-
466
- ## Code Review Integration
467
-
468
- ### Automatic checks during review
469
-
470
- 1. Do changes violate any existing ADRs?
471
- 2. Do changes require a new ADR?
472
- 3. Are ADR references in code accurate?
473
- 4. Is the ADR Status up to date for any ADR being implemented in this PR?
474
-
475
- ### Example review comments
476
-
477
- ```
478
- NEGATIVE
479
- "This change violates ADR-NNN (Title).
480
- Please refactor or write a superseding ADR."
481
-
482
- POSITIVE
483
- "This change aligns with ADR-NNN (Title). Good use of the documented pattern."
484
-
485
- QUESTION
486
- "This introduces a new architectural pattern.
487
- Please create an ADR documenting the decision before merging."
488
-
489
- STATUS NUDGE
490
- "ADR-NNN is referenced but its Status is still 'Proposed'.
491
- Please flip it to 'Accepted' since this PR implements it."
492
- ```
493
-
494
- ### PR checklist
495
-
496
- ```markdown
497
- ## ADR Compliance Checklist
498
-
499
- - [ ] Changes reviewed against existing ADRs
500
- - [ ] No violations of architectural decisions (or a superseding ADR is included)
501
- - [ ] New ADR created if needed (Status: Proposed)
502
- - [ ] ADR Status updated if this PR implements an existing ADR
503
- - [ ] Code comments reference relevant ADRs at non-obvious enforcement sites
504
- - [ ] docs/adr/README.md updated if a new ADR was added
505
- - [ ] All four verification gates pass on any new or amended ADR
506
- ```
507
-
508
- ---
509
-
510
- ## Human Decision Documentation
511
-
512
- When a user explicitly makes an architectural choice, document it as a human decision so the attribution survives.
513
-
514
- ```markdown
515
- # ADR-XXX Title
516
-
517
- ## Status
518
-
519
- Accepted. Date: YYYY-MM-DD.
520
-
521
- **Decision Maker:** User: [Name or role] <- IMPORTANT: mark as human decision
522
-
523
- ## Context
524
-
525
- [User's problem or request]
526
-
527
- ## Decision
528
-
529
- **User Decision:** [What the user chose]
530
-
531
- The user explicitly chose [X] over [Y] because [reason given].
532
-
533
- ## Alternatives Considered
534
-
535
- [What was presented to the user]
536
-
537
- ### Alternative A: [Option presented]
538
-
539
- **User Feedback:** [User's reasoning for or against]
540
-
541
- ### Alternative B: [Option presented]
542
-
543
- **User Feedback:** [User's reasoning]
544
-
545
- ## Rationale
546
-
547
- **User's stated reasons:**
548
-
549
- - Reason 1
550
- - Reason 2
551
-
552
- **Technical context (from the agent):**
553
-
554
- [Agent's analysis of the decision's technical implications. Useful for future readers who want the technical lens alongside the user's intent.]
555
- ```
556
-
557
- The Decision Maker line is the load-bearing part: it tells future readers that the choice was a human one, not an agent-generated default.
558
-
559
- ---
560
-
561
- ## Code Examples in ADRs
562
-
563
- ### Show, don't just tell
564
-
565
- ```markdown
566
- WRONG (no example)
567
- Use idempotent retry logic.
568
-
569
- RIGHT (concrete example)
570
- Use idempotent retry logic. Each request includes an Idempotency-Key
571
- header derived from the client's request body hash, and the server
572
- deduplicates within a 24-hour window.
573
-
574
- Example client wrapper:
575
-
576
- ```python
577
- def submit(payload):
578
- key = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
579
- return http.post("/submit", json=payload, headers={"Idempotency-Key": key})
580
- ```
581
- ```
582
-
583
- ### Diagrams when helpful
584
-
585
- ```
586
- [Client] -- POST /submit (with Idempotency-Key) --> [Gateway]
587
- |
588
- v
589
- [Dedup Cache (24h)]
590
- |
591
- cache miss | cache hit
592
- v | v
593
- [Worker] | [Return cached response]
594
- | |
595
- v |
596
- [Response] |
597
- ```
598
-
599
- ASCII diagrams travel well across tools and reviewers.
600
-
601
- ---
602
-
603
- ## ADR Index Management
604
-
605
- Maintain `docs/adr/README.md` as the navigation hub. Required sections:
606
-
607
- 1. **What are ADRs?** Brief explanation for new readers.
608
- 2. **Quick Navigation** with category counts.
609
- 3. **ADR Index**: full categorized list with one-line summaries.
610
- 4. **ADR Template**: link to or embed the template.
611
- 5. **Key Architectural Themes**: cross-cutting concerns referenced by multiple ADRs.
612
- 6. **Architectural Dependencies**: which ADRs depend on which.
613
- 7. **When to Create an ADR**: guidance for new contributors.
614
- 8. **Superseding ADRs**: how to handle changes.
615
- 9. **Resources**: links to ADR best practices and external references.
616
-
617
- The ADR list inside the `<!-- adr-kit-index:begin -->` / `<!-- adr-kit-index:end -->` block, `ADR-INDEX.md`, and `ADR-INDEX.json` are generated from the same semantic records. Do not hand-edit them. Run `bin/adr-index docs/adr/` after ADR mutations, use `bin/adr-index --check docs/adr/` in CI, and use `bin/adr-doctor --fix-index docs/adr/` when an agent starts or finishes ADR work. Agents may explore the JSON graph to shortlist ADRs, but must read the linked Markdown record before applying a constraint.
618
-
619
- When adding a new ADR:
620
-
621
- 1. Add or update the ADR file.
622
- 2. Run `bin/adr-index docs/adr/`.
623
- 3. Update "Foundational ADRs" or human-written notes only if the new decision changes that prose.
624
- 4. Add cross-references in any older ADRs that relate.
625
- 5. Run `bin/adr-doctor --fix-index docs/adr/` before reporting completion.
626
-
627
- ---
628
-
629
- ## ADR Metrics and Maintenance
630
-
631
- ### Health indicators (healthy repository)
632
-
633
- - All ADRs have a clear Status.
634
- - Superseded ADRs reference their replacement.
635
- - Code references match existing ADRs.
636
- - README index is up to date.
637
- - Recent ADRs include implementation dates.
638
- - Each ADR has at least 2 alternatives documented.
639
-
640
- ### Needs attention
641
-
642
- - Multiple ADRs with `Proposed` status for >30 days (review and accept or deprecate).
643
- - ADR numbers with gaps (consolidate or document the gap).
644
- - Code comments referencing non-existent ADRs (broken links).
645
- - ADRs without an alternatives section (low quality).
646
- - README categories that do not match actual ADRs (drift).
647
-
648
- ### Periodic review (quarterly)
649
-
650
- ```
651
- 1. Are any 'Proposed' ADRs abandoned? (Mark deprecated.)
652
- 2. Are any 'Accepted' ADRs being violated? (Update enforcement.)
653
- 3. Do new patterns need ADRs? (Create them.)
654
- 4. Are superseded ADRs properly linked? (Verify.)
655
- 5. Is README accurately reflecting current state? (Update.)
656
- ```
657
-
658
- ---
659
-
660
- ## Quick Reference
661
-
662
- ### ADR creation checklist
663
-
664
- ```markdown
665
- Creating a new ADR? Check these:
666
-
667
- - [ ] Next sequential number assigned (check docs/adr/)
668
- - [ ] Filename follows convention
669
- - [ ] Status field present
670
- - [ ] Date field present (YYYY-MM-DD)
671
- - [ ] Decision Maker identified (Agent or User: Name)
672
- - [ ] Context section explains the problem clearly
673
- - [ ] At least 2 to 3 alternatives documented
674
- - [ ] Pros and cons listed for each alternative
675
- - [ ] "Why not chosen" for each rejected alternative
676
- - [ ] Consequences section complete (positive, negative, risks)
677
- - [ ] Code examples included (if applicable)
678
- - [ ] Related ADRs referenced
679
- - [ ] Implementation notes with affected files
680
- - [ ] Ran `bin/adr-index docs/adr/` and `bin/adr-doctor --fix-index docs/adr/`
681
- - [ ] Category assigned
682
- - [ ] References / external links included
683
- - [ ] Four verification gates pass
684
- ```
685
-
686
- ### Common mistakes
687
-
688
- ```
689
- - Writing "we should use X" without explaining why
690
- - Skipping alternatives ("this is the only way")
691
- - No code examples for technical decisions
692
- - Forgetting to update status after implementation
693
- - Not referencing related ADRs
694
- - Vague consequences ("it will be better")
695
- - No decision maker attribution
696
- - Missing constraints that drove the decision
697
- - Modifying accepted ADRs instead of superseding
698
- - Hand-editing a generated README, Markdown, or JSON index instead of running
699
- `bin/adr-index`
700
- - Using jargon without defining it
701
- - Being superficial: not digging into the "why" behind constraints
702
- - Hiding negative consequences
703
- - Writing marketing copy instead of honest technical analysis
704
- - Skipping measurements ("faster" vs "68% latency reduction")
705
- - Not explaining technical trade-offs in understandable terms
706
- ```
707
-
708
- ### When in doubt
709
-
710
- Ask these questions:
711
-
712
- 1. Will a developer in 6 months understand WHY we did this?
713
- 2. Have I explained what we REJECTED, not just what we chose?
714
- 3. Could this ADR help someone avoid making a wrong decision?
715
- 4. Have I included enough code examples?
716
- 5. Is the decision maker clearly identified?
717
- 6. Can someone unfamiliar with this technology understand the core trade-offs?
718
- 7. Have I been honest about negative consequences?
719
- 8. Have I quantified impacts with actual measurements?
720
-
721
- If you answered "No" to any of these, improve the ADR.
722
-
723
- ---
724
-
725
- ## Companion skills and runners (v0.12+)
726
-
727
- The full adr-kit toolset wraps this skill with three operational modes:
728
-
729
- - **`/adr-kit:init`** — one-shot bootstrap of the kit in an existing project: hooks `CLAUDE.md`, drops `.claude/adr-kit-guide.md`, runs `bin/adr-discover` to enumerate decision-shaped artefacts, walks the user through batched approval to generate Accepted ADRs, installs the pre-commit hook. Use this once per project.
730
- - **`/adr-kit:judge`** — in-session review of a staged git diff against existing ADRs. Runs the deterministic `bin/adr-judge` for declarative `Enforcement` rules, then evaluates `llm_judge: true` ADRs in the active Claude Code session. On violation, walks three resolution paths (new ADR / supersede / fix code).
731
- - **`/adr-kit:install-hooks`** — install or uninstall the pre-commit hook. Default-on after `/adr-kit:init` (or `/adr-kit:upgrade`).
732
- - **`/adr-kit:upgrade`** — for users on v0.11: migrate to the v0.12 footprint without re-running the heavy audit. Refreshes the CLAUDE.md stub + guide, installs the hook, walks Accepted ADRs offering Enforcement-block backfill.
733
- - **`/adr-kit:lint`** — validate ADR file content against the four verification gates (Completeness / Evidence / Clarity / Consistency). The deterministic CLI is `bin/adr-lint`; the skill drives the heuristic gates.
734
- - **`bin/adr-doctor`** — local health check for agent start and finish: strict lint, generated-index freshness, shipped-but-Proposed ADRs, old Proposed ADRs, changed evidence behind Accepted ADRs, and missing named gates. Material drift auto-triggers a local `bin/adr-discover --root ...` pass and includes the audit summary in the doctor output. Use `--fix-index` to regenerate the index before checking it.
735
- - **`/adr-kit:migrate`** — preview metadata changes or convert between MADR,
736
- Nygard, and canonical profiles; guided handling remains for legacy shapes.
737
-
738
- ### When to invoke this skill (`/adr-kit:adr`) vs the others
739
-
740
- - **Authoring a single new ADR mid-session**: `/adr-kit:adr` (or invoke the `adr-generator` subagent).
741
- - **Diagnosing a staged diff against existing ADRs**: `/adr-kit:judge`. The model can self-call this before requesting a commit on the user's behalf.
742
- - **First-time setup**: `/adr-kit:init`.
743
- - **Migration from v0.11**: `/adr-kit:upgrade`.
744
-
745
- The four verification gates and the supersession workflow defined in this file remain the source of truth — every other skill delegates to them, never duplicates them.
746
-
747
- ## Enforcement blocks (v0.12+)
748
-
749
- Every new `Accepted` ADR with a code surface SHOULD carry an `## Enforcement` section so `bin/adr-judge` (run by the pre-commit hook) can guard the boundary against future drift. The block is a fenced JSON object validated against `schemas/adr-enforcement.schema.json`. Three patterns:
750
-
751
- - Declarative regex / glob rules (`forbid_pattern`, `forbid_import`, `require_pattern`) — preferred when the rule is mechanically expressible. Fastest at hook time, no LLM round-trip.
752
- - `llm_judge` — for nuanced rules that need a model's judgement. It DEFAULTS TO TRUE: omit the key and this ADR is judged. Each opted-in ADR gets its own isolated call (never batched, so no sibling's Decision text can flip a verdict), resolved through `judge.backend` rather than a pinned model. A `VIOLATION` blocks the commit; a missing or unauthenticated backend degrades to advisory and never blocks on tooling drift. To opt out, write `"llm_judge": false` together with an `"llm_judge_reason"` — the reason is what makes the opt-out durable across upgrades. Cost is bounded by scope: an ADR is judged only when the diff touches a file matching its rules' `path_glob`, so a block with no glob is judged on every commit.
753
- - Section omitted with an in-body explanation — for governance / process ADRs with no code surface.
754
-
755
- Authoring is part of the agent's Step 3b (see `agents/adr-generator.md`). Code review applies Check 7 (see `instructions/adr.review.md`) to confirm the block is set appropriately.
756
-
757
- ---
758
-
759
- ## Resources
760
-
761
- ### Official ADR resources
762
-
763
- - ADR best practices: <https://adr.github.io/>
764
- - Michael Nygard's original post (2011): <https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>
765
- - MADR template: <https://github.com/adr/madr>
766
- - Joel Parker Henderson's ADR collection: <https://github.com/joelparkerhenderson/architecture-decision-record>
767
-
768
- ### Tooling
769
-
770
- - adr-tools (npryce): <https://github.com/npryce/adr-tools>
771
- - Log4brains: <https://github.com/thomvaill/log4brains>
772
-
773
- ### Related skill patterns
774
-
775
- - Anti-rationalization guards: <https://github.com/addyosmani/agent-skills>
776
- - Verification gates: <https://github.com/trailofbits/skills>
777
-
778
- ---
779
-
780
- **Remember:** ADRs are *living documentation* stored as docs-as-code in the same repository as the implementation. They should be consulted during development, referenced in code reviews, and evolved through supersession (not modification). Good ADRs make architectural decisions visible, understandable, and enforceable.
1
+ ---
2
+ name: adr
3
+ description: "Create or review Architecture Decision Records. Use for ADRs, architecture decisions, durable trade-offs, new dependencies, contracts, or patterns."
4
+ argument-hint: "[short title of the decision]"
5
+ license: MIT
6
+ ---
7
+
8
+ # ADR Skill: Architecture Decision Record Management
9
+
10
+ Use `$ARGUMENTS` as the decision title or review target. If it is empty, infer
11
+ the target only from the user's current request; otherwise ask one short question.
12
+
13
+ ## Overview
14
+
15
+ This skill enables systematic creation, maintenance, and enforcement of Architecture Decision Records. ADRs document significant architectural choices along with their context, alternatives considered, and consequences. They serve as living documentation so current and future developers (and AI agents) understand why the system is built the way it is.
16
+
17
+ ## Guided authoring contract
18
+
19
+ Treat `/adr-kit:adr <subject>` as the complete creation flow; do not add or
20
+ suggest a separate create command.
21
+
22
+ 1. First decide whether the subject is consequential and difficult to reverse.
23
+ End with no ADR for an ordinary implementation choice.
24
+ 2. For a qualifying subject, invoke `python <plugin-root>/bin/adr propose` so
25
+ the lifecycle command creates a `Proposed` record.
26
+ 3. Continue with `/adr-kit:grill ADR-NNN`. Cover context, decision,
27
+ alternatives, consequences, evidence, scope, ownership, conflicts, and Open
28
+ Questions. Also propose concise retrieval topics/components/symbols and a
29
+ Decision Contract from settled facts so future agents can query the record
30
+ selectively; the human reviews these candidates with the decision.
31
+ 4. Show an acceptance packet containing decision, rationale, alternatives,
32
+ consequences, evidence, scope, conflicts, and lifecycle effect. Require an
33
+ explicit `yes` in this active session.
34
+ 5. Only then invoke `python <plugin-root>/bin/adr accept ADR-NNN --confirm`.
35
+ The flag is refused-by-default for a reason: without it an acceptance can
36
+ happen by accident, and it writes a name into a history that is immutable
37
+ afterwards. Pass it only after the human has said yes in this session.
38
+ Missing
39
+ evidence, strict lint failures, conflicts, and unresolved Open Questions
40
+ remain authoritative blockers and become the next grill question.
41
+
42
+ The skill bundles three patterns that distinguish it from a basic ADR template:
43
+
44
+ 1. **Anti-Rationalization Guards**: a table of excuses agents and humans use to skip writing an ADR, paired with counter-arguments. Pre-flight discipline.
45
+ 2. **Verification Gates**: four named gates an ADR must pass before its Status flips from `Proposed` to `Accepted`. Reviewers can block on a single named gate.
46
+ 3. **Human Decision Documentation**: explicit `Decision Maker:` attribution so user-driven choices are visible in the record, distinct from agent-generated ADRs.
47
+
48
+ ---
49
+
50
+ ## When to Use
51
+
52
+ ### Automatic triggers
53
+
54
+ Use this skill automatically when:
55
+
56
+ - Reviewing a PR or analysing code changes for architectural impact.
57
+ - A change introduces a new pattern, dependency, or contract.
58
+ - Refactoring proposals affect system design.
59
+ - A user asks an architectural question ("why did we choose X?", "should we use Y or Z?").
60
+
61
+ ### Explicit triggers
62
+
63
+ Use this skill when the user mentions:
64
+
65
+ - "Create an ADR" / "Document this decision" / "Architecture decision".
66
+ - "Why did we choose...?" / "What alternatives did we consider?".
67
+ - "Document my choice" / "Capture this trade-off".
68
+
69
+ ### Decision triggers
70
+
71
+ Create a new ADR when making a decision that:
72
+
73
+ - Has long-term impact on architecture.
74
+ - Affects multiple components or modules.
75
+ - Involves trade-offs between alternatives.
76
+ - Constrains future development choices.
77
+ - Addresses a significant technical challenge.
78
+ - Changes existing architectural patterns.
79
+ - Requires a human decision that should be preserved.
80
+
81
+ ### Do NOT create an ADR for
82
+
83
+ - Bug fixes that do not change architecture.
84
+ - Refactors that maintain the same external behaviour.
85
+ - Configuration changes within an existing range.
86
+ - Documentation updates (unless the doc *is* an ADR).
87
+ - Minor feature additions within established patterns.
88
+ - Temporary workarounds or experiments.
89
+
90
+ ---
91
+
92
+ ## Anti-Rationalization Guards
93
+
94
+ ADRs fail not from lack of templates but from the agent (or human) talking themselves out of writing one. Below is a table of common excuses with their counter-arguments. When you hear yourself reaching for one of the left-column entries, stop and apply the right-column response.
95
+
96
+ | Excuse | Counter-argument |
97
+ |---|---|
98
+ | "This decision is obvious" | Obvious to you, today, with the context fresh in your head. Not obvious to a maintainer in six months, an open-source contributor, or an AI agent reviewing the PR. Document the *why*. |
99
+ | "I'll document it later" | You will not. The pattern goes in once and only comes out if a future bug forces it out. Cost of writing now: 15 to 30 minutes. Cost of re-deriving later: hours, sometimes a full incident. |
100
+ | "The code speaks for itself" | Code shows *what* and *how*. ADRs document *why*. The why is never derivable from source: it lives in the constraints, the alternatives that were rejected, and the trade-offs accepted. |
101
+ | "Everyone knows this pattern" | Everyone on the team *today*. Not the maintainer in three years. Not the contributor who shows up next week. Not the model running a future code review. |
102
+ | "This is just the framework default" | Then say so explicitly. "Status: Accepted. We took the framework default for X because Y." Defaults embed assumptions; an ADR makes those assumptions inspectable. |
103
+ | "It is too small to need an ADR" | Small *architecturally*? Then no ADR. Small *implementation* of a contract change? Still an ADR, because the contract is what future developers will trip over. |
104
+ | "We can always change it later" | Every architectural choice constrains the next one. Document the chosen path now so a future change is a *deliberate* supersede, not an accidental drift. |
105
+ | "I don't have time" | Pay 30 minutes now or pay hours when someone challenges the choice in code review six months from now and nobody can remember the rationale. |
106
+ | "There are no real alternatives" | Almost never true. If you cannot name one, the alternative is "do nothing" or "the framework default": that is an alternative. Document it and the reason it lost. |
107
+
108
+ This pattern was originally introduced by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) and was first combined with verification gates in a single ADR skill by [Jim van den Breemen's adr-skill](https://github.com/Jvdbreemen/adr-skill); `adr-kit` adapts that pairing.
109
+
110
+ ---
111
+
112
+ ## Initial Codebase Analysis
113
+
114
+ ### First-time use: discovering undocumented decisions
115
+
116
+ When introducing this skill to an existing codebase, perform a comprehensive architectural analysis to identify and document existing but undocumented decisions.
117
+
118
+ #### Workflow
119
+
120
+ **Step 1: identify architectural patterns.** Areas to analyse:
121
+
122
+ - Platform and runtime choices (language, framework, deployment target).
123
+ - Data and storage (database, schema, persistence patterns).
124
+ - Protocol and integration (sync vs async, REST vs RPC, message bus).
125
+ - Memory and resource management (when load-bearing).
126
+ - Network and security (TLS posture, auth model, trust boundaries).
127
+ - Build and tooling (build system, CI gates, test strategy).
128
+ - Cross-cutting concerns (logging, error handling, observability).
129
+
130
+ **Step 2: ask critical questions.** For each pattern discovered:
131
+
132
+ - WHY was this approach chosen? (context, constraints).
133
+ - WHAT alternatives exist? (at least 2 to 3 viable options).
134
+ - WHY were alternatives rejected? (specific technical reasons).
135
+ - WHAT are the consequences? (benefits, costs, risks).
136
+ - HOW is this implemented? (code references, key files).
137
+ - WHEN was this decided? (estimate from git log or release history if unknown).
138
+
139
+ **Step 3: generate ADRs systematically.** For each undocumented decision:
140
+
141
+ 1. Use a research subagent to understand the pattern.
142
+ 2. Review code, comments, git history for context.
143
+ 3. Identify constraints (memory, performance, compatibility, security).
144
+ 4. Research alternatives even if obvious.
145
+ 5. Document consequences: positive AND negative.
146
+ 6. Create the ADR with `Status: Proposed`, even when code already shipped.
147
+ 7. Link to actual implementation (files, commits), then grill the reconstructed
148
+ rationale and request independent acceptance for this ADR.
149
+
150
+ **Step 4: prioritize.** Start with foundational decisions that:
151
+
152
+ - Affect multiple components.
153
+ - Constrain future choices.
154
+ - Are non-obvious or counterintuitive.
155
+ - Have significant trade-offs.
156
+ - Are frequently questioned.
157
+
158
+ #### Trigger phrases
159
+
160
+ ```
161
+ "Analyze this codebase to identify undocumented architectural decisions"
162
+ "Generate ADRs for existing architectural patterns in this codebase"
163
+ "What architectural decisions should be documented in this project?"
164
+ ```
165
+
166
+ ---
167
+
168
+ ## ADR Principles
169
+
170
+ ### The golden rules
171
+
172
+ 1. **One decision per ADR.** Each ADR captures a single architectural choice.
173
+ 2. **Immutable history.** Never modify accepted ADRs; supersede with a new one instead.
174
+ 3. **Context is king.** Explain WHY the decision was made, not just WHAT.
175
+ 4. **Alternatives matter.** Document what was considered but rejected.
176
+ 5. **Human decisions marked.** Clearly indicate when the decision came from a user or stakeholder.
177
+ 6. **Critical analysis.** Be thorough, question assumptions, document trade-offs honestly.
178
+ 7. **Understandable language.** Write for a developer unfamiliar with the decision; avoid unexplained jargon.
179
+
180
+ ### Best practices
181
+
182
+ ```
183
+ GOOD AVOID
184
+ Write for future developers Use jargon without explanation
185
+ Include code examples Assume reader knows the context
186
+ Reference related ADRs Skip alternatives ("only way")
187
+ Use clear, simple language Make assumptions unstated
188
+ Document driving constraints Forget to update status when superseding
189
+ Explain consequences both ways Be vague ("better", "improves performance")
190
+ Link to implementation Skip negative consequences
191
+ Be critical, document risks Write marketing copy
192
+ Provide specific evidence Use jargon without defining it
193
+ ```
194
+
195
+ ---
196
+
197
+ ## Verification Gates
198
+
199
+ An ADR moves from `Status: Proposed` to `Status: Accepted` only after all four gates pass. The gates are intentionally *named* so a reviewer can cite a single gate when blocking acceptance: "This ADR fails the Evidence gate, please add measurements."
200
+
201
+ ### Gate 1: Completeness
202
+
203
+ The ADR has filled every load-bearing section.
204
+
205
+ - [ ] Problem statement is unambiguous; a reader knows what the decision is *about*
206
+ - [ ] Decision is stated as a single, declarative sentence (not a discussion)
207
+ - [ ] At least 2 alternatives considered, each with a "why not chosen" line
208
+ - [ ] Consequences are listed in *both* directions (positive and negative); a one-sided ADR fails this gate
209
+ - [ ] Risks are named explicitly, each with at least one mitigation
210
+
211
+ ### Gate 2: Evidence
212
+
213
+ Every claim that a reader could challenge is backed by something verifiable.
214
+
215
+ - [ ] No bare adjectives where numbers are achievable: "saves 5 to 8 KB RAM" beats "saves memory"; "reduces request latency from 120 ms to 40 ms" beats "faster"
216
+ - [ ] Constraint claims are anchored to a source: "the runtime allows 256 MB per worker" cites where (vendor doc, measured, ops policy)
217
+ - [ ] Code references include `file:line` so the reviewer can verify
218
+ - [ ] External claims (specs, RFCs, vendor docs) are linked, not paraphrased
219
+
220
+ ### Gate 3: Clarity
221
+
222
+ A reader who has never seen this codebase can follow the argument.
223
+
224
+ - [ ] Acronyms defined on first use: "TLS (Transport Layer Security)"
225
+ - [ ] Technical concepts explained when load-bearing: "back-pressure: a feedback signal from a slower consumer to a faster producer"
226
+ - [ ] Code examples are concrete and runnable, not pseudo-code
227
+ - [ ] The decision is explainable in one paragraph at the top, before the reader needs to read the alternatives
228
+
229
+ ### Gate 4: Consistency
230
+
231
+ The ADR fits the existing record without creating contradictions.
232
+
233
+ - [ ] No conflict with an `Accepted` ADR; if there is, this ADR is a supersede with explicit reference
234
+ - [ ] Cross-references to related ADRs are present and accurate
235
+ - [ ] Terminology matches the project glossary and other ADRs
236
+ - [ ] ADR number is the next sequential, no gap, no reuse
237
+
238
+ This pattern was originally introduced by [trailofbits/skills](https://github.com/trailofbits/skills) and was first combined with anti-rationalization guards in a single ADR skill by [Jim van den Breemen's adr-skill](https://github.com/Jvdbreemen/adr-skill); `adr-kit` adapts that pairing.
239
+
240
+ ---
241
+
242
+ ## ADR Template
243
+
244
+ MADR is the default profile. Create from the project configuration with:
245
+
246
+ ```text
247
+ python bin/adr profiles --format json
248
+ python bin/adr new "Short imperative title" --adr-dir docs/adr
249
+ ```
250
+
251
+ Use `--profile madr|nygard|canonical` for a one-record override. The bundled
252
+ templates are `templates/adr-template.{madr,nygard,canonical}.md`; the
253
+ unqualified `templates/adr-template.md` is the MADR default. All profiles keep
254
+ frontmatter, Status, Status History, Related Decisions, References, and
255
+ Enforcement invariant. The older example below is the `canonical` profile,
256
+ retained for backward-compatible projects.
257
+
258
+ When the user requests a non-default format, first read the JSON catalog.
259
+ Accept only a returned `id`, require `available: true`, and scaffold from that
260
+ entry's `template` path through `adr new --profile <id>`. Never invent a
261
+ profile name, infer one from an arbitrary filename, hand-map headings, or
262
+ generate a substitute for a missing shipped template.
263
+
264
+ ```markdown
265
+ ---
266
+ id: "ADR-XXX"
267
+ title: "Title in title case"
268
+ status: Proposed
269
+ date: "YYYY-MM-DD"
270
+ binding: false
271
+ gate: null
272
+ documents_shipped: false
273
+ verified_in: []
274
+ supersedes: []
275
+ superseded_by: null
276
+ format: canonical
277
+ ---
278
+
279
+ # ADR-XXX Title in title case
280
+
281
+ ## Status
282
+
283
+ Proposed, YYYY-MM-DD.
284
+
285
+ (Later: Accepted; Deprecated; Rejected; Superseded by ADR-YYY; or Amended by ADR-YYY.)
286
+
287
+ ## Status History
288
+
289
+ status_history:
290
+ - date: YYYY-MM-DD
291
+ status: Proposed
292
+ changed_by: Agent or User
293
+ reason: Initial proposal
294
+ changed_via: adr-kit
295
+
296
+ ## Context
297
+
298
+ One paragraph stating the problem clearly enough for a reader who has never seen this codebase. Include the constraints that drove the decision and the existing state that triggered the choice.
299
+
300
+ ## Decision
301
+
302
+ A single declarative sentence stating what was chosen. Optionally followed by 2 to 4 short paragraphs unpacking the choice.
303
+
304
+ ## Alternatives Considered
305
+
306
+ ### Alternative A: name
307
+
308
+ Description and rejection reasoning.
309
+
310
+ ### Alternative B: name
311
+
312
+ (repeat structure)
313
+
314
+ ### Alternative C: do nothing
315
+
316
+ If "do nothing" was rejected, document why. If it was the right choice, this ADR is probably not needed.
317
+
318
+ ## Consequences
319
+
320
+ **Benefits**
321
+
322
+ - Specific positive outcomes, with measurements when achievable.
323
+
324
+ **Trade-offs**
325
+
326
+ - The cost we accepted by making this choice.
327
+
328
+ **Risks and mitigations**
329
+
330
+ - *Risk*: what could go wrong. *Mitigation*: how we address it.
331
+
332
+ ## Related Decisions
333
+
334
+ - **ADR-YYY (Title)**: how it relates (supersedes, amends, depends on, complements).
335
+
336
+ ## References
337
+
338
+ - Implementation tasks or issue IDs.
339
+ - Source files affected (file:line).
340
+ - External specs, RFCs, vendor docs, or measurements.
341
+ ```
342
+
343
+ A clean copy is available at `examples/ADR-template.md`.
344
+
345
+ ---
346
+
347
+ ## Naming Convention
348
+
349
+ ### Default
350
+
351
+ ```
352
+ Format: ADR-XXX-short-descriptive-title.md
353
+
354
+ Where:
355
+ - XXX = zero-padded sequential number (001, 002, ..., 099, 100, etc.)
356
+ - short-descriptive-title = kebab-case description
357
+
358
+ Examples:
359
+ - ADR-001-postgresql-for-sensor-data.md
360
+ - ADR-014-rest-api-versioning.md
361
+ - ADR-042-grpc-internal-rpc.md
362
+ - ADR-099-deprecated-static-bundling.md
363
+
364
+ Wrong:
365
+ - ADR-1-postgresql.md (not zero-padded)
366
+ - adr-001-PostgreSQL.md (lowercase prefix, mixed case)
367
+ - ADR-001_PostgreSQL.md (underscore instead of hyphen)
368
+ ```
369
+
370
+ ### Number assignment
371
+
372
+ - Sequential numbering starting from 001.
373
+ - Check `docs/adr/` for the highest number and increment.
374
+ - Do not reuse numbers from deprecated or superseded ADRs.
375
+ - Do not leave gaps in numbering.
376
+
377
+ ### Project override
378
+
379
+ The filename contract remains fixed. Select the body profile with
380
+ `template.profile` in `docs/adr/.adr-kit.json`; choose `madr` (default),
381
+ `nygard`, or `canonical`. A per-file `format` value is authoritative.
382
+
383
+ ---
384
+
385
+ ## ADR Categories
386
+
387
+ Group ADRs by architectural domain for navigation. The category list is project-specific; below is a neutral starting set you can replace:
388
+
389
+ - **Platform and Runtime**: language, framework, runtime, deployment target.
390
+ - **Data and Storage**: database, schema, persistence, caching.
391
+ - **Protocol and Integration**: sync vs async, REST/RPC/messaging, contracts.
392
+ - **Memory and Resources**: when load-bearing for the project's constraints.
393
+ - **Network and Security**: TLS posture, auth, trust boundaries, secrets.
394
+ - **Build and Tooling**: build system, CI gates, packaging, testing.
395
+ - **Observability**: logging, metrics, tracing, alerting.
396
+ - **Cross-Cutting**: error handling, configuration, internationalization.
397
+
398
+ In your `docs/adr/README.md`, replace these with categories that match your domain.
399
+
400
+ ---
401
+
402
+ ## ADR Workflow
403
+
404
+ ### 1. Before making architectural changes
405
+
406
+ - Run the local doctor to repair the generated index and surface ADR health issues before relying on the decision log: `bin/adr-doctor --fix-index docs/adr/`.
407
+ - Review existing ADRs (`docs/adr/README.md` index).
408
+ - Search for related decisions.
409
+ - Check whether the change conflicts with any `Accepted` ADR.
410
+ - Determine if a new ADR is needed (long-term impact? multiple components? alternatives exist? future context?).
411
+
412
+ ### 2. During implementation
413
+
414
+ - Create the ADR with `Status: Proposed`.
415
+ - Run `python bin/adr new "Title" --adr-dir docs/adr`; it allocates the next
416
+ number and honors `template.profile`.
417
+ - Complete the selected profile without renaming its semantic headings.
418
+ - Reference the ADR in code comments at non-obvious enforcement sites: `// See ADR-XXX for why we use this pattern.`
419
+ - Implement according to the ADR's decision.
420
+
421
+ ### 3. After implementation
422
+
423
+ - Update Status: `Proposed` -> `Accepted`.
424
+ - Add the implementation date in the Status line: `Accepted. Date: YYYY-MM-DD.`
425
+ - Append the matching `Accepted` transition to `## Status History`; never rewrite an earlier entry.
426
+ - **Decide which cross-references are warranted, then let the tool write both
427
+ sides.** Read the existing set (`bin/adr-index --adr-dir docs/adr --format md`
428
+ is the compact map) and ask, for each candidate, whether a reader arriving at
429
+ the *other* ADR would need to know this one exists. That judgement is yours;
430
+ no regex can make it. It is a real relationship when the two decisions
431
+ constrain each other, when one is the reason the other is possible, or when
432
+ changing one would force a rethink of the other. It is not a relationship
433
+ merely because both mention the same file.
434
+ - For each one you decide on: `bin/adr relate ADR-NEW --to ADR-OTHER`. It
435
+ writes the `related` field on **both** ADRs in one transaction and
436
+ regenerates the indexes, so neither side can end up carrying half a link.
437
+ Wrong call? `--remove` unwinds both sides the same way.
438
+ - Prose in `## Related Decisions` still counts and still reads well; keep
439
+ writing it. What it cannot do is update the other ADR, which is why the
440
+ reciprocal link goes in frontmatter. A backwards-only prose citation is
441
+ normal and is never flagged.
442
+ - Do not hand-edit the `related` field. `adr-lint` FAILs a one-sided one,
443
+ because the only way to produce one is a hand edit or a half-applied write.
444
+ - Refresh the generated README, compact Markdown index, and JSON graph with
445
+ `bin/adr-index docs/adr/`.
446
+ - Run `bin/adr-doctor --fix-index docs/adr/` or `bin/adr-lint --strict docs/adr/` before treating the ADR set as clean.
447
+
448
+ ### 4. When superseding an ADR
449
+
450
+ - Write the new ADR explaining the change.
451
+ - Reference the original in `## Related Decisions`: "Supersedes ADR-XXX (Title)".
452
+ - Update the old ADR's Status line to `Superseded by ADR-YYY` and append that transition to `## Status History`.
453
+ - Do NOT modify the old ADR's decision text or reasoning. Immutability is the rule.
454
+ - Refresh all generated index views through `bin/adr-index docs/adr/` so both
455
+ sides appear in `README.md`, `ADR-INDEX.md`, and `ADR-INDEX.json`.
456
+
457
+ ### 5. When amending an ADR (lighter alternative to supersession)
458
+
459
+ - Write the amending ADR.
460
+ - Reference the original in `## Related Decisions`: "Amends ADR-XXX (Title)".
461
+ - Update the old ADR's Status line: `Amended by ADR-YYY` (or leave as `Accepted` if the amend is content-additive).
462
+ - Do NOT modify the old ADR's decision text.
463
+
464
+ ---
465
+
466
+ ## Code Review Integration
467
+
468
+ ### Automatic checks during review
469
+
470
+ 1. Do changes violate any existing ADRs?
471
+ 2. Do changes require a new ADR?
472
+ 3. Are ADR references in code accurate?
473
+ 4. Is the ADR Status up to date for any ADR being implemented in this PR?
474
+
475
+ ### Example review comments
476
+
477
+ ```
478
+ NEGATIVE
479
+ "This change violates ADR-NNN (Title).
480
+ Please refactor or write a superseding ADR."
481
+
482
+ POSITIVE
483
+ "This change aligns with ADR-NNN (Title). Good use of the documented pattern."
484
+
485
+ QUESTION
486
+ "This introduces a new architectural pattern.
487
+ Please create an ADR documenting the decision before merging."
488
+
489
+ STATUS NUDGE
490
+ "ADR-NNN is referenced but its Status is still 'Proposed'.
491
+ Please flip it to 'Accepted' since this PR implements it."
492
+ ```
493
+
494
+ ### PR checklist
495
+
496
+ ```markdown
497
+ ## ADR Compliance Checklist
498
+
499
+ - [ ] Changes reviewed against existing ADRs
500
+ - [ ] No violations of architectural decisions (or a superseding ADR is included)
501
+ - [ ] New ADR created if needed (Status: Proposed)
502
+ - [ ] ADR Status updated if this PR implements an existing ADR
503
+ - [ ] Code comments reference relevant ADRs at non-obvious enforcement sites
504
+ - [ ] docs/adr/README.md updated if a new ADR was added
505
+ - [ ] All four verification gates pass on any new or amended ADR
506
+ ```
507
+
508
+ ---
509
+
510
+ ## Human Decision Documentation
511
+
512
+ When a user explicitly makes an architectural choice, document it as a human decision so the attribution survives.
513
+
514
+ ```markdown
515
+ # ADR-XXX Title
516
+
517
+ ## Status
518
+
519
+ Accepted. Date: YYYY-MM-DD.
520
+
521
+ **Decision Maker:** User: [Name or role] <- IMPORTANT: mark as human decision
522
+
523
+ ## Context
524
+
525
+ [User's problem or request]
526
+
527
+ ## Decision
528
+
529
+ **User Decision:** [What the user chose]
530
+
531
+ The user explicitly chose [X] over [Y] because [reason given].
532
+
533
+ ## Alternatives Considered
534
+
535
+ [What was presented to the user]
536
+
537
+ ### Alternative A: [Option presented]
538
+
539
+ **User Feedback:** [User's reasoning for or against]
540
+
541
+ ### Alternative B: [Option presented]
542
+
543
+ **User Feedback:** [User's reasoning]
544
+
545
+ ## Rationale
546
+
547
+ **User's stated reasons:**
548
+
549
+ - Reason 1
550
+ - Reason 2
551
+
552
+ **Technical context (from the agent):**
553
+
554
+ [Agent's analysis of the decision's technical implications. Useful for future readers who want the technical lens alongside the user's intent.]
555
+ ```
556
+
557
+ The Decision Maker line is the load-bearing part: it tells future readers that the choice was a human one, not an agent-generated default.
558
+
559
+ ---
560
+
561
+ ## Code Examples in ADRs
562
+
563
+ ### Show, don't just tell
564
+
565
+ ```markdown
566
+ WRONG (no example)
567
+ Use idempotent retry logic.
568
+
569
+ RIGHT (concrete example)
570
+ Use idempotent retry logic. Each request includes an Idempotency-Key
571
+ header derived from the client's request body hash, and the server
572
+ deduplicates within a 24-hour window.
573
+
574
+ Example client wrapper:
575
+
576
+ ```python
577
+ def submit(payload):
578
+ key = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
579
+ return http.post("/submit", json=payload, headers={"Idempotency-Key": key})
580
+ ```
581
+ ```
582
+
583
+ ### Diagrams when helpful
584
+
585
+ ```
586
+ [Client] -- POST /submit (with Idempotency-Key) --> [Gateway]
587
+ |
588
+ v
589
+ [Dedup Cache (24h)]
590
+ |
591
+ cache miss | cache hit
592
+ v | v
593
+ [Worker] | [Return cached response]
594
+ | |
595
+ v |
596
+ [Response] |
597
+ ```
598
+
599
+ ASCII diagrams travel well across tools and reviewers.
600
+
601
+ ---
602
+
603
+ ## ADR Index Management
604
+
605
+ Maintain `docs/adr/README.md` as the navigation hub. Required sections:
606
+
607
+ 1. **What are ADRs?** Brief explanation for new readers.
608
+ 2. **Quick Navigation** with category counts.
609
+ 3. **ADR Index**: full categorized list with one-line summaries.
610
+ 4. **ADR Template**: link to or embed the template.
611
+ 5. **Key Architectural Themes**: cross-cutting concerns referenced by multiple ADRs.
612
+ 6. **Architectural Dependencies**: which ADRs depend on which.
613
+ 7. **When to Create an ADR**: guidance for new contributors.
614
+ 8. **Superseding ADRs**: how to handle changes.
615
+ 9. **Resources**: links to ADR best practices and external references.
616
+
617
+ The ADR list inside the `<!-- adr-kit-index:begin -->` / `<!-- adr-kit-index:end -->` block, `ADR-INDEX.md`, and `ADR-INDEX.json` are generated from the same semantic records. Do not hand-edit them. Run `bin/adr-index docs/adr/` after ADR mutations, use `bin/adr-index --check docs/adr/` in CI, and use `bin/adr-doctor --fix-index docs/adr/` when an agent starts or finishes ADR work. Agents may explore the JSON graph to shortlist ADRs, but must read the linked Markdown record before applying a constraint.
618
+
619
+ When adding a new ADR:
620
+
621
+ 1. Add or update the ADR file.
622
+ 2. Run `bin/adr-index docs/adr/`.
623
+ 3. Update "Foundational ADRs" or human-written notes only if the new decision changes that prose.
624
+ 4. Add cross-references in any older ADRs that relate.
625
+ 5. Run `bin/adr-doctor --fix-index docs/adr/` before reporting completion.
626
+
627
+ ---
628
+
629
+ ## ADR Metrics and Maintenance
630
+
631
+ ### Health indicators (healthy repository)
632
+
633
+ - All ADRs have a clear Status.
634
+ - Superseded ADRs reference their replacement.
635
+ - Code references match existing ADRs.
636
+ - README index is up to date.
637
+ - Recent ADRs include implementation dates.
638
+ - Each ADR has at least 2 alternatives documented.
639
+
640
+ ### Needs attention
641
+
642
+ - Multiple ADRs with `Proposed` status for >30 days (review and accept or deprecate).
643
+ - ADR numbers with gaps (consolidate or document the gap).
644
+ - Code comments referencing non-existent ADRs (broken links).
645
+ - ADRs without an alternatives section (low quality).
646
+ - README categories that do not match actual ADRs (drift).
647
+
648
+ ### Periodic review (quarterly)
649
+
650
+ ```
651
+ 1. Are any 'Proposed' ADRs abandoned? (Mark deprecated.)
652
+ 2. Are any 'Accepted' ADRs being violated? (Update enforcement.)
653
+ 3. Do new patterns need ADRs? (Create them.)
654
+ 4. Are superseded ADRs properly linked? (Verify.)
655
+ 5. Is README accurately reflecting current state? (Update.)
656
+ ```
657
+
658
+ ---
659
+
660
+ ## Quick Reference
661
+
662
+ ### ADR creation checklist
663
+
664
+ ```markdown
665
+ Creating a new ADR? Check these:
666
+
667
+ - [ ] Next sequential number assigned (check docs/adr/)
668
+ - [ ] Filename follows convention
669
+ - [ ] Status field present
670
+ - [ ] Date field present (YYYY-MM-DD)
671
+ - [ ] Decision Maker identified (Agent or User: Name)
672
+ - [ ] Context section explains the problem clearly
673
+ - [ ] At least 2 to 3 alternatives documented
674
+ - [ ] Pros and cons listed for each alternative
675
+ - [ ] "Why not chosen" for each rejected alternative
676
+ - [ ] Consequences section complete (positive, negative, risks)
677
+ - [ ] Code examples included (if applicable)
678
+ - [ ] Related ADRs referenced
679
+ - [ ] Implementation notes with affected files
680
+ - [ ] Ran `bin/adr-index docs/adr/` and `bin/adr-doctor --fix-index docs/adr/`
681
+ - [ ] Category assigned
682
+ - [ ] References / external links included
683
+ - [ ] Four verification gates pass
684
+ ```
685
+
686
+ ### Common mistakes
687
+
688
+ ```
689
+ - Writing "we should use X" without explaining why
690
+ - Skipping alternatives ("this is the only way")
691
+ - No code examples for technical decisions
692
+ - Forgetting to update status after implementation
693
+ - Not referencing related ADRs
694
+ - Vague consequences ("it will be better")
695
+ - No decision maker attribution
696
+ - Missing constraints that drove the decision
697
+ - Modifying accepted ADRs instead of superseding
698
+ - Hand-editing a generated README, Markdown, or JSON index instead of running
699
+ `bin/adr-index`
700
+ - Using jargon without defining it
701
+ - Being superficial: not digging into the "why" behind constraints
702
+ - Hiding negative consequences
703
+ - Writing marketing copy instead of honest technical analysis
704
+ - Skipping measurements ("faster" vs "68% latency reduction")
705
+ - Not explaining technical trade-offs in understandable terms
706
+ ```
707
+
708
+ ### When in doubt
709
+
710
+ Ask these questions:
711
+
712
+ 1. Will a developer in 6 months understand WHY we did this?
713
+ 2. Have I explained what we REJECTED, not just what we chose?
714
+ 3. Could this ADR help someone avoid making a wrong decision?
715
+ 4. Have I included enough code examples?
716
+ 5. Is the decision maker clearly identified?
717
+ 6. Can someone unfamiliar with this technology understand the core trade-offs?
718
+ 7. Have I been honest about negative consequences?
719
+ 8. Have I quantified impacts with actual measurements?
720
+
721
+ If you answered "No" to any of these, improve the ADR.
722
+
723
+ ---
724
+
725
+ ## Companion skills and runners (v0.12+)
726
+
727
+ The full adr-kit toolset wraps this skill with three operational modes:
728
+
729
+ - **`/adr-kit:init`** — one-shot bootstrap of the kit in an existing project: hooks `CLAUDE.md`, drops `.claude/adr-kit-guide.md`, runs `bin/adr-discover` to enumerate decision-shaped artefacts, walks the user through batched approval to generate Accepted ADRs, installs the pre-commit hook. Use this once per project.
730
+ - **`/adr-kit:judge`** — in-session review of a staged git diff against existing ADRs. Runs the deterministic `bin/adr-judge` for declarative `Enforcement` rules, then evaluates `llm_judge: true` ADRs in the active Claude Code session. On violation, walks three resolution paths (new ADR / supersede / fix code).
731
+ - **`/adr-kit:install-hooks`** — install or uninstall the pre-commit hook. Default-on after `/adr-kit:init` (or `/adr-kit:upgrade`).
732
+ - **`/adr-kit:upgrade`** — for users on v0.11: migrate to the v0.12 footprint without re-running the heavy audit. Refreshes the CLAUDE.md stub + guide, installs the hook, walks Accepted ADRs offering Enforcement-block backfill.
733
+ - **`/adr-kit:lint`** — validate ADR file content against the four verification gates (Completeness / Evidence / Clarity / Consistency). The deterministic CLI is `bin/adr-lint`; the skill drives the heuristic gates.
734
+ - **`bin/adr-doctor`** — local health check for agent start and finish: strict lint, generated-index freshness, shipped-but-Proposed ADRs, old Proposed ADRs, changed evidence behind Accepted ADRs, and missing named gates. Material drift auto-triggers a local `bin/adr-discover --root ...` pass and includes the audit summary in the doctor output. Use `--fix-index` to regenerate the index before checking it.
735
+ - **`/adr-kit:migrate`** — preview metadata changes or convert between MADR,
736
+ Nygard, and canonical profiles; guided handling remains for legacy shapes.
737
+
738
+ ### When to invoke this skill (`/adr-kit:adr`) vs the others
739
+
740
+ - **Authoring a single new ADR mid-session**: `/adr-kit:adr` (or invoke the `adr-generator` subagent).
741
+ - **Diagnosing a staged diff against existing ADRs**: `/adr-kit:judge`. The model can self-call this before requesting a commit on the user's behalf.
742
+ - **First-time setup**: `/adr-kit:init`.
743
+ - **Migration from v0.11**: `/adr-kit:upgrade`.
744
+
745
+ The four verification gates and the supersession workflow defined in this file remain the source of truth — every other skill delegates to them, never duplicates them.
746
+
747
+ ## Enforcement blocks (v0.12+)
748
+
749
+ Every new `Accepted` ADR with a code surface SHOULD carry an `## Enforcement` section so `bin/adr-judge` (run by the pre-commit hook) can guard the boundary against future drift. The block is a fenced JSON object validated against `schemas/adr-enforcement.schema.json`. Three patterns:
750
+
751
+ - Declarative regex / glob rules (`forbid_pattern`, `forbid_import`, `require_pattern`) — preferred when the rule is mechanically expressible. Fastest at hook time, no LLM round-trip.
752
+ - `llm_judge` — for nuanced rules that need a model's judgement. It DEFAULTS TO TRUE: omit the key and this ADR is judged. Each opted-in ADR gets its own isolated call (never batched, so no sibling's Decision text can flip a verdict), resolved through `judge.backend` rather than a pinned model. A `VIOLATION` blocks the commit; a missing or unauthenticated backend degrades to advisory and never blocks on tooling drift. To opt out, write `"llm_judge": false` together with an `"llm_judge_reason"` — the reason is what makes the opt-out durable across upgrades. Cost is bounded by scope: an ADR is judged only when the diff touches a file matching its rules' `path_glob`, so a block with no glob is judged on every commit.
753
+ - Section omitted with an in-body explanation — for governance / process ADRs with no code surface.
754
+
755
+ Authoring is part of the agent's Step 3b (see `agents/adr-generator.md`). Code review applies Check 7 (see `instructions/adr.review.md`) to confirm the block is set appropriately.
756
+
757
+ ---
758
+
759
+ ## Resources
760
+
761
+ ### Official ADR resources
762
+
763
+ - ADR best practices: <https://adr.github.io/>
764
+ - Michael Nygard's original post (2011): <https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>
765
+ - MADR template: <https://github.com/adr/madr>
766
+ - Joel Parker Henderson's ADR collection: <https://github.com/joelparkerhenderson/architecture-decision-record>
767
+
768
+ ### Tooling
769
+
770
+ - adr-tools (npryce): <https://github.com/npryce/adr-tools>
771
+ - Log4brains: <https://github.com/thomvaill/log4brains>
772
+
773
+ ### Related skill patterns
774
+
775
+ - Anti-rationalization guards: <https://github.com/addyosmani/agent-skills>
776
+ - Verification gates: <https://github.com/trailofbits/skills>
777
+
778
+ ---
779
+
780
+ **Remember:** ADRs are *living documentation* stored as docs-as-code in the same repository as the implementation. They should be consulted during development, referenced in code reviews, and evolved through supersession (not modification). Good ADRs make architectural decisions visible, understandable, and enforceable.