@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,154 +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.
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.