@rvdbreemen/adr-kit-opencode 0.52.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +29 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- package/templates/validate_adr_template.sh +74 -0
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: setup
|
|
3
|
+
description: "The one entry point for installing ADR Kit in a project (R19). Modes: register (default), adopt (audit + propose ADRs, /adr-kit:init), hooks (/adr-kit:install-hooks), upgrade (/adr-kit:upgrade)."
|
|
4
|
+
argument-hint: "[adopt|hooks|upgrade]"
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
allowed-tools: [Read, Write, Edit, Bash]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# adr-kit setup
|
|
10
|
+
|
|
11
|
+
Setting up ADR Kit is one deterministic act (spec R19) with four modes. An
|
|
12
|
+
empty `$ARGUMENTS` runs the default **register** mode below. A mode name
|
|
13
|
+
routes to the procedure that owns it -- follow that skill file and nothing
|
|
14
|
+
else; each is a mode of this entry point, not a separate product:
|
|
15
|
+
|
|
16
|
+
| `$ARGUMENTS` | Mode | Procedure |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| *(empty)* | **register** -- write the managed guidance layout | this file, below |
|
|
19
|
+
| `adopt` | audit the codebase and propose ADRs, then register | `skills/init/SKILL.md` (`/adr-kit:init`) |
|
|
20
|
+
| `hooks` | install or remove the pre-commit gate only | `skills/install-hooks/SKILL.md` (`/adr-kit:install-hooks`) |
|
|
21
|
+
| `upgrade` | refresh copied artifacts, migrate a v0.11 footprint | `skills/upgrade/SKILL.md` (`/adr-kit:upgrade`) |
|
|
22
|
+
|
|
23
|
+
Reject any other argument instead of guessing a mode.
|
|
24
|
+
|
|
25
|
+
You are running the one-time project setup for the adr-kit plugin (register
|
|
26
|
+
mode). Your job is to:
|
|
27
|
+
|
|
28
|
+
1. Write the project's instruction layout with `scripts/setup-project.py`, which owns every file in it.
|
|
29
|
+
2. Leave everything outside its managed markers byte-exact.
|
|
30
|
+
|
|
31
|
+
This is the lightweight counterpart to `/adr-kit:init`. Use `setup` when the user has an existing project, already understands their architecture, and just wants the kit registered. Use `init` when the user wants the kit to also audit the codebase and propose ADRs.
|
|
32
|
+
|
|
33
|
+
## Backwards compatibility (v0.11 footprint)
|
|
34
|
+
|
|
35
|
+
A project that ran v0.11 `/adr-kit:setup` has an inline `## ADR Kit Rules` section in `CLAUDE.md`. This skill detects that footprint and leaves it untouched — telling the user to run `/adr-kit:upgrade` to migrate to the v0.12 marker-bracketed stub + external guide layout. **Do not silently rewrite a v0.11 footprint.** The upgrade skill exists for that explicit migration.
|
|
36
|
+
|
|
37
|
+
## Steps
|
|
38
|
+
|
|
39
|
+
1. **Resolve the plugin path.**
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
If empty, abort: the plugin install is broken; tell the user to reinstall via `/plugin install adr-kit@rvdbreemen-adr-kit`.
|
|
46
|
+
|
|
47
|
+
2. **Check for a v0.11 footprint first.** Read `CLAUDE.md` if it exists. If it
|
|
48
|
+
carries an inline `## ADR Kit Rules` section, stop and tell the user:
|
|
49
|
+
`Detected v0.11 ADR Kit Rules section in CLAUDE.md at line <N>. Run
|
|
50
|
+
/adr-kit:upgrade to migrate. /adr-kit:setup is leaving the v0.11 footprint
|
|
51
|
+
untouched.` Exit without changes. A v0.11 footprint requires an explicit
|
|
52
|
+
migration; this command never performs one silently.
|
|
53
|
+
|
|
54
|
+
3. **Run the writer.** Do not hand-write the instruction block or the guide.
|
|
55
|
+
`scripts/setup-project.py` owns the layout, and it is the only thing that
|
|
56
|
+
knows all of it: `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
|
|
57
|
+
and `.adr-kit/ADR-guide.md`. Prose in this skill describing an older layout is
|
|
58
|
+
how the three clients drifted apart in the first place -- Codex and Copilot
|
|
59
|
+
delegated here while this file still wrote a guide under `.claude/` and a
|
|
60
|
+
stub block that `scripts/project_setup.py` classifies as legacy.
|
|
61
|
+
|
|
62
|
+
Preview first, then apply:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root . --dry-run
|
|
66
|
+
python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root .
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The command is idempotent: re-running it on a current project changes
|
|
70
|
+
nothing. It writes only inside its managed markers, so user content around
|
|
71
|
+
them stays byte-exact, and it never touches `.adr-kit/ADR-guide.local.md`.
|
|
72
|
+
|
|
73
|
+
`--client` also accepts `codex-cli` and `github-copilot-cli`, and `--clients`
|
|
74
|
+
takes a comma-separated list when a project uses more than one.
|
|
75
|
+
|
|
76
|
+
4. **Report what it did.** The command prints one line per change. Relay them,
|
|
77
|
+
and say plainly when there was nothing to do -- a no-op is the expected
|
|
78
|
+
outcome of a second run, not a failure.
|
|
79
|
+
|
|
80
|
+
## Constraints
|
|
81
|
+
|
|
82
|
+
- **Two coordinated writes.** v0.12 setup writes both the stub AND the guide file. Either-or is incomplete.
|
|
83
|
+
- **Never silently migrate v0.11.** A v0.11 footprint requires explicit `/adr-kit:upgrade`. Leave v0.11 alone here.
|
|
84
|
+
- **Idempotent.** Re-running on a v0.12 project where everything is current is a no-op.
|
|
85
|
+
- **Read before write.** Preview with `--dry-run` before applying; the writer reads every file it touches.
|
|
86
|
+
- **Preserve surrounding content.** Only the marker-bracketed stub and the guide file may be touched. Everything else stays byte-exact.
|
|
87
|
+
- **No em dashes** in any text the skill writes (per adr-kit style).
|
|
88
|
+
|
|
89
|
+
## When the user is in the wrong directory
|
|
90
|
+
|
|
91
|
+
If `pwd` lacks all of `CLAUDE.md`, `.git/`, and a recognisable project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `platformio.ini`, etc.), stop and ask: `I do not see a project root here (no CLAUDE.md, no .git, no manifest). Confirm you want to set up adr-kit in <pwd>?` Do not silently create files in unexpected locations.
|
|
92
|
+
|
|
93
|
+
## Cross-references
|
|
94
|
+
|
|
95
|
+
- `/adr-kit:setup adopt` (alias `/adr-kit:init`) — full bootstrap including audit and hook installation.
|
|
96
|
+
- `/adr-kit:setup upgrade` (alias `/adr-kit:upgrade`) — migrate v0.11 → v0.12 footprint without re-auditing.
|
|
97
|
+
- `/adr-kit:setup hooks` (alias `/adr-kit:install-hooks`) — install the pre-commit hook independently.
|
|
98
|
+
|
|
99
|
+
## Step 4c — The signer: propose, never assume
|
|
100
|
+
|
|
101
|
+
Every lifecycle command writes a Status History entry naming who decided, and it
|
|
102
|
+
refuses to sign on the user's behalf. That refusal is right, and it should not be
|
|
103
|
+
the user's first experience of the tool.
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
python3 "$ADR_KIT/bin/adr" signer --suggest --adr-dir docs/adr
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Read-only: it finds candidates and writes nothing. It looks at the signed-in
|
|
110
|
+
GitHub account (`gh api user`, when the CLI is available) and at
|
|
111
|
+
`git config user.name`, ranks them, and shows each with its source — a proposal
|
|
112
|
+
the user cannot trace is one they cannot judge, and this value lands in an
|
|
113
|
+
immutable history.
|
|
114
|
+
|
|
115
|
+
- **Candidates found** — show them and ask which to adopt, or let the user type a
|
|
116
|
+
different name. Then write it:
|
|
117
|
+
`python3 "$ADR_KIT/bin/adr" signer --set "User: <chosen>"`.
|
|
118
|
+
- **Already configured** — say so and move on. Do not overwrite it.
|
|
119
|
+
- **Nothing found** — the GitHub CLI is absent or signed out and git names nobody
|
|
120
|
+
usable. Ask for the name outright rather than guessing.
|
|
121
|
+
|
|
122
|
+
**Bot and CI identities are deliberately not offered.** `github-actions[bot]`,
|
|
123
|
+
`runner`, a bare `user`: those are configured values that name a machine, and
|
|
124
|
+
R8 asks for evidence of which *human* accepted a decision.
|
|
125
|
+
|
|
126
|
+
The value is machine-local by design (`docs/adr/.adr-kit.local.json`, gitignored)
|
|
127
|
+
because writing one person's name into the tracked config would sign every
|
|
128
|
+
teammate's acceptances. Each machine, container and CI runner needs its own.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: supersede
|
|
3
|
+
description: "Supersede an Accepted ADR while preserving history and links. Use for replacing a decision, successor ADRs, or changed architecture."
|
|
4
|
+
argument-hint: "[ADR id to supersede; e.g. \"ADR-007\"]"
|
|
5
|
+
license: MIT
|
|
6
|
+
disable-model-invocation: true
|
|
7
|
+
allowed-tools: [Read, Bash, Edit, Write, Task]
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# adr-kit supersede
|
|
11
|
+
|
|
12
|
+
Use `$ARGUMENTS` as the required ADR id. Ask for the id when it is empty and
|
|
13
|
+
never infer a destructive target.
|
|
14
|
+
|
|
15
|
+
You are running `/adr-kit:supersede`. Purpose: replace an existing decision
|
|
16
|
+
with a new one without rewriting history. The old ADR's reasoning stays
|
|
17
|
+
immutable; only its Status line changes and its Status History grows by one
|
|
18
|
+
entry. Everything else lands in the new ADR.
|
|
19
|
+
|
|
20
|
+
Resolve the plugin path once and reuse it:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Step 1 - Identify the target and show its graph
|
|
27
|
+
|
|
28
|
+
1. Take the ADR id from the argument; if absent, ask which ADR to supersede.
|
|
29
|
+
2. Run the graph tool on it and show the user the result:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
python "$ADR_KIT/bin/adr-related" ADR-OLD --format json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Present inbound edges explicitly: these are the ADRs that point at the
|
|
36
|
+
target and may need their Related Decisions updated after supersession.
|
|
37
|
+
Flag any dangling references already present.
|
|
38
|
+
|
|
39
|
+
3. **Conflict guard (hard stop).** Read the old ADR. If its Status line
|
|
40
|
+
already says `Superseded by ADR-X` where X is NOT the ADR you are about to
|
|
41
|
+
create, stop and surface the conflict to the user verbatim. Never
|
|
42
|
+
overwrite an existing supersession pointer; the user must resolve the
|
|
43
|
+
chain (perhaps the right move is superseding ADR-X instead).
|
|
44
|
+
|
|
45
|
+
4. Confirm with the user: "Supersede ADR-OLD (<title>) with a new ADR about
|
|
46
|
+
<reason>?" Do not proceed without a yes.
|
|
47
|
+
|
|
48
|
+
## Step 2 - Draft the superseding ADR (Proposed)
|
|
49
|
+
|
|
50
|
+
Before drafting, run `/adr-kit:grill --revalidate ADR-OLD`. Revalidation covers
|
|
51
|
+
changed forces, alternatives, migration, consequences, new evidence, and impact
|
|
52
|
+
on related ADRs. It supports unchanged, Proposed successor, reject-candidate,
|
|
53
|
+
and explicit defer outcomes. Never rewrite Accepted prose.
|
|
54
|
+
|
|
55
|
+
Determine the next free ADR number (highest existing + 1, no gaps, no reuse).
|
|
56
|
+
Invoke the `adr-generator` subagent with:
|
|
57
|
+
|
|
58
|
+
- The user's stated reason for the change as Context input.
|
|
59
|
+
- The old ADR's Decision text as background (what is being replaced and why
|
|
60
|
+
it no longer holds).
|
|
61
|
+
- An explicit instruction to include in `## Related Decisions`:
|
|
62
|
+
`- **ADR-OLD (<old title>)**: Supersedes ADR-OLD.`
|
|
63
|
+
- `Status: Proposed` with today's date, and a `status_history` entry:
|
|
64
|
+
|
|
65
|
+
```yaml
|
|
66
|
+
status_history:
|
|
67
|
+
- date: YYYY-MM-DD
|
|
68
|
+
status: Proposed
|
|
69
|
+
changed_by: <user>
|
|
70
|
+
reason: Drafted to supersede ADR-OLD
|
|
71
|
+
changed_via: adr-kit /adr-kit:supersede
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Show the draft to the user. **Never auto-accept it.** The user reviews and
|
|
75
|
+
may iterate; the new ADR is only flipped to `Accepted` (by the user or on
|
|
76
|
+
their explicit instruction) before the old one is touched.
|
|
77
|
+
|
|
78
|
+
Show the complete acceptance packet and require an explicit `yes` in this
|
|
79
|
+
active session before invoking `adr accept ... --confirm`. A failure or
|
|
80
|
+
interruption stops
|
|
81
|
+
before `adr supersede`, leaving the old ADR and reciprocal links unchanged.
|
|
82
|
+
|
|
83
|
+
## Step 3 - Supersede transactionally (only after approval)
|
|
84
|
+
|
|
85
|
+
Only after the user has approved the new ADR-NEW:
|
|
86
|
+
|
|
87
|
+
1. Ensure ADR-NEW is Accepted through `python "$ADR_KIT/bin/adr" accept
|
|
88
|
+
ADR-NEW --adr-dir docs/adr`. Acceptance is blocked unless all verification
|
|
89
|
+
gates pass.
|
|
90
|
+
2. Run the only supported reciprocal mutation:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
python "$ADR_KIT/bin/adr" supersede ADR-OLD --by ADR-NEW \
|
|
94
|
+
--adr-dir docs/adr --changed-by "<user>" \
|
|
95
|
+
--reason "Superseded by ADR-NEW (<new title>)"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The command rejects illegal or conflicting chains before mutation. It
|
|
99
|
+
atomically updates both ADRs and all generated index views, and restores
|
|
100
|
+
their original bytes if any write or index refresh fails. Never reproduce
|
|
101
|
+
these edits manually.
|
|
102
|
+
3. If inbound ADRs from Step 1 reference the old decision, list them and offer
|
|
103
|
+
a note pointing at ADR-NEW. Apply only entries the user approves.
|
|
104
|
+
|
|
105
|
+
## Step 4 - Verify the chain
|
|
106
|
+
|
|
107
|
+
Run all three and show the results:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
python "$ADR_KIT/bin/adr-related" ADR-OLD --format json
|
|
111
|
+
python "$ADR_KIT/bin/adr-related" ADR-NEW --format json
|
|
112
|
+
python "$ADR_KIT/bin/adr-lint" docs/adr/
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The chain is clean when:
|
|
116
|
+
|
|
117
|
+
- ADR-OLD shows outbound `superseded-by -> ADR-NEW` and ADR-NEW shows
|
|
118
|
+
outbound `supersedes -> ADR-OLD` (and inbound mirrors of each other).
|
|
119
|
+
- Neither graph reports dangling references.
|
|
120
|
+
- adr-lint reports no FAIL on either file.
|
|
121
|
+
|
|
122
|
+
If any check fails, fix the link wiring (not the old ADR's prose) and re-run
|
|
123
|
+
until clean. Report the final state to the user.
|
|
124
|
+
|
|
125
|
+
## Boundaries
|
|
126
|
+
|
|
127
|
+
- **Immutability.** The only allowed edits to the old ADR are the Status line
|
|
128
|
+
flip and appended status history performed by the lifecycle command.
|
|
129
|
+
- **Conflict guard.** An existing `Superseded by` pointing at a different ADR
|
|
130
|
+
is a stop-the-line conflict. Surface it; never overwrite.
|
|
131
|
+
- **No auto-accept.** The new ADR starts as Proposed and a human approves it.
|
|
132
|
+
Do not flip it to Accepted on your own initiative.
|
|
133
|
+
- **No silent edits to third ADRs.** Updating inbound referencers happens
|
|
134
|
+
only per-entry with user approval.
|
|
135
|
+
- **Verification is part of the job.** Do not declare the supersession done
|
|
136
|
+
before Step 4 is clean.
|
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: upgrade
|
|
3
|
+
description: "Upgrade ADR Kit project artifacts and legacy layouts. Use after a plugin update, for stale wrappers, guide refresh, or migration."
|
|
4
|
+
argument-hint: "[no arguments]"
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
allowed-tools: [Read, Write, Edit, Bash, Task]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# adr-kit upgrade
|
|
10
|
+
|
|
11
|
+
This is the **upgrade** mode of `/adr-kit:setup` (spec R19: one entry point,
|
|
12
|
+
four modes). Invoked directly or via `/adr-kit:setup upgrade`, the procedure
|
|
13
|
+
is identical -- this file owns it.
|
|
14
|
+
|
|
15
|
+
`$ARGUMENTS` should be empty. Stop for confirmation before any breaking
|
|
16
|
+
migration or backup-backed rewrite.
|
|
17
|
+
|
|
18
|
+
You bring a project's **installed adr-kit artifacts** in line with the **installed plugin version**. Two jobs, run in order:
|
|
19
|
+
|
|
20
|
+
1. **Artifact refresh (any version, the common case).** Plugin-level hooks refresh automatically when the plugin updates, but artifacts copied into the project freeze at install time: the git pre-commit wrapper, the project-scoped guardian entry in `.claude/settings.json`, and `.claude/adr-kit-guide.md`. Step 0 detects and refreshes them.
|
|
21
|
+
2. **Legacy footprint migration (v0.11 to v0.12, one-time).** Steps 1-4 below. Skip them when the project is already on the v0.12 footprint.
|
|
22
|
+
|
|
23
|
+
If the project has no ADRs yet, point the user to `/adr-kit:init` instead.
|
|
24
|
+
|
|
25
|
+
After resolving `ADR_KIT` in Step 0 and before refreshing artifacts, run
|
|
26
|
+
format discovery:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
python3 "$ADR_KIT/bin/adr-migrate" --plan docs/adr/
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Report every migration notice. Do not apply any migration during upgrade.
|
|
33
|
+
Supported legacy records receive a deterministic dry-run command; external,
|
|
34
|
+
hybrid, or ambiguous formats receive `/adr-kit:migrate <path>` guidance.
|
|
35
|
+
Continue the artifact upgrade regardless of whether notices exist.
|
|
36
|
+
|
|
37
|
+
## Step 0 — Artifact freshness check and refresh
|
|
38
|
+
|
|
39
|
+
Resolve the plugin path and run the detector:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
43
|
+
python3 "$ADR_KIT/bin/adr-guardian" artifacts --format json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The report lists each copied artifact with its embedded version stamp and a `stale` flag (the guardian SessionStart nudge uses the same detection, so this is the same signal that brought most users here). For each stale artifact:
|
|
47
|
+
|
|
48
|
+
- **`git-pre-commit-wrapper`** (`.githooks/pre-commit` or `.git/hooks/pre-commit`): overwrite it with the current `$ADR_KIT/templates/githooks/pre-commit` (same target path it already occupies). Show a unified diff first when the installed wrapper differs from any shipped template version (the user may have local edits); ask `replace | keep | merge by hand` only in that case, otherwise replace silently. Preserve the executable bit.
|
|
49
|
+
- **`settings-guardian-entry`** (`.claude/settings.json`): replace the guardian hook entry with the current `$ADR_KIT/templates/cc-settings/guardian-hook-entry.json` content using JSON-structural editing (never clobber sibling hooks; same posture as `/adr-kit:install-hooks`).
|
|
50
|
+
- **`.claude/adr-kit-guide.md`**: if its version line (first line, `<!-- adr-kit-guide vX.Y.Z -->`) lags the plugin, refresh it from `$ADR_KIT/templates/adr-kit-guide.md` (diff-and-ask when the project copy has local edits, like Step 2 below).
|
|
51
|
+
|
|
52
|
+
When the report shows no stale artifacts AND the project is already on the v0.12 footprint, exit with `everything up to date; nothing to do`.
|
|
53
|
+
|
|
54
|
+
Artifacts the plugin cannot refresh from here (report them, do not edit): GitHub Action pins (`uses: ...adr-judge@vX` in workflows; suggest a Dependabot/Renovate rule or a manual bump) and a `pre-commit` framework `rev:` (suggest `pre-commit autoupdate`).
|
|
55
|
+
|
|
56
|
+
## Step 1 — Detect the installed footprint
|
|
57
|
+
|
|
58
|
+
Inspect the current state:
|
|
59
|
+
|
|
60
|
+
- `CLAUDE.md` exists? Read it. Look for a v0.11-style `## ADR Kit Rules` section (free-form heading, no markers) OR a v0.12 `<!-- ADR-KIT STUB START -->` block (markers).
|
|
61
|
+
- `docs/adr/` exists? Count `ADR-*.md` files. Scan for any existing `## Enforcement` blocks and tally them.
|
|
62
|
+
- `.githooks/pre-commit` exists?
|
|
63
|
+
- `.claude/adr-kit-guide.md` exists? If yes, check the version line (first line of the plugin template is `<!-- adr-kit-guide vX.Y.Z -->`).
|
|
64
|
+
|
|
65
|
+
Report the detected state to the user in a 4–6 line summary before changing anything.
|
|
66
|
+
|
|
67
|
+
If all of the following are true, the project is already on v0.12:
|
|
68
|
+
- CLAUDE.md has the marker-bracketed stub
|
|
69
|
+
- `.claude/adr-kit-guide.md` matches the plugin's current version
|
|
70
|
+
- `.githooks/pre-commit` is the adr-kit hook
|
|
71
|
+
- All Accepted ADRs either have `## Enforcement` blocks or have been explicitly skipped
|
|
72
|
+
|
|
73
|
+
If so, exit with `already on v0.12; nothing to do`.
|
|
74
|
+
|
|
75
|
+
## Step 2 — Refresh CLAUDE.md stub + guide file
|
|
76
|
+
|
|
77
|
+
Resolve the plugin path:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Three migration paths for `CLAUDE.md`:
|
|
84
|
+
|
|
85
|
+
- **v0.11 inline `## ADR Kit Rules` section present.** Replace the entire section (heading through the next `## ` heading, or EOF) with the v0.12 stub:
|
|
86
|
+
```markdown
|
|
87
|
+
<!-- ADR-KIT STUB START -->
|
|
88
|
+
<!-- DO NOT regenerate manually. Updated by `/adr-kit:init`, `/adr-kit:upgrade`, `/adr-kit:setup`. -->
|
|
89
|
+
## ADR Kit
|
|
90
|
+
|
|
91
|
+
This project uses [adr-kit](https://github.com/rvdbreemen/adr-kit). All architectural decisions live as ADRs in `docs/adr/`. Full guide: @.claude/adr-kit-guide.md
|
|
92
|
+
|
|
93
|
+
Authoring: `/adr-kit:adr` (or the `adr-generator` subagent).
|
|
94
|
+
Pre-commit verification: `bin/adr-judge` runs declarative `Enforcement` rules at commit time. ADRs with `llm_judge: true` are reviewed in-session via `/adr-kit:judge`.
|
|
95
|
+
<!-- ADR-KIT STUB END -->
|
|
96
|
+
```
|
|
97
|
+
Surrounding content (everything outside the section) stays byte-exact. Verify by diff after the edit.
|
|
98
|
+
|
|
99
|
+
- **v0.12 stub already present.** Replace just the contents between the markers with the current stub text. Idempotent.
|
|
100
|
+
|
|
101
|
+
- **No ADR-kit footprint.** Append the v0.12 stub at the end of `CLAUDE.md`, with one blank line of separation.
|
|
102
|
+
|
|
103
|
+
For `.claude/adr-kit-guide.md`:
|
|
104
|
+
|
|
105
|
+
- If absent: create it from `$ADR_KIT/templates/adr-kit-guide.md`.
|
|
106
|
+
- If present and byte-identical to the plugin template: no-op.
|
|
107
|
+
- If present and differs: read both, show a unified diff (3 context lines), ask the user `keep project version | replace with plugin version | merge by hand`. Apply.
|
|
108
|
+
|
|
109
|
+
## Step 3 — Install the pre-commit hook (default-on)
|
|
110
|
+
|
|
111
|
+
Delegate to `/adr-kit:install-hooks` (or do its work inline if delegation is awkward). Same logic as that skill — detect existing hook, prepend / replace / abort, set `core.hooksPath`. **Do not prompt for installation itself; the hook is default-on as of v0.12.** If the user wants to opt out, they can disable per-commit with `ADR_KIT_HOOK_DISABLE=1` or remove via `/adr-kit:install-hooks --uninstall`.
|
|
112
|
+
|
|
113
|
+
## Step 4 — Enforcement-block backfill (the only slow step)
|
|
114
|
+
|
|
115
|
+
For every `Status: Accepted` ADR in `docs/adr/` that does NOT already have a `## Enforcement` section, propose one. Walk them one at a time (not batched) — each proposal needs the ADR's full Decision/Context to make a judgement, and the user's input is per-ADR.
|
|
116
|
+
|
|
117
|
+
For each ADR:
|
|
118
|
+
|
|
119
|
+
1. Read the ADR. Summarise its Decision in one line.
|
|
120
|
+
2. Decide which of three categories it falls into:
|
|
121
|
+
- **Declarative.** The rule is mechanically expressible. Examples: "no String class in hot paths" → `forbid_pattern: \\bString\\b ... in src/**`; "use addOTWGcmdtoqueue() for OTGW commands" → `require_pattern: addOTWGcmdtoqueue\\(`.
|
|
122
|
+
- **LLM-judgeable.** The rule is too nuanced for regex but a model can read the diff and decide. Set `llm_judge: true`.
|
|
123
|
+
- **Manual review only.** No code surface (e.g., a process or governance ADR). Suggest the user add `<!-- adr-kit-judge: skip -->` near the heading, or simply omit the Enforcement block (the judge skips ADRs without one).
|
|
124
|
+
3. Print: `[ADR-NNN] <one-line title> → proposed category: <declarative | llm-judge | manual>; proposed block:` and show the JSON.
|
|
125
|
+
4. Ask the user: `accept | edit | skip this ADR | skip rest`.
|
|
126
|
+
- `accept`: Edit the ADR file, append the `## Enforcement` section.
|
|
127
|
+
- `edit`: Show the user the proposal, let them edit it inline; apply when satisfied.
|
|
128
|
+
- `skip this ADR`: leave it alone.
|
|
129
|
+
- `skip rest`: stop the backfill loop entirely.
|
|
130
|
+
|
|
131
|
+
Do NOT modify any other section of the ADR. Only append the new `## Enforcement` section. Accepted ADRs are otherwise immutable.
|
|
132
|
+
|
|
133
|
+
## Step 4b — LLM judge: opt-out migration (ask before writing)
|
|
134
|
+
|
|
135
|
+
`llm_judge` defaults to **true** as of TASK-74. ADRs written before that carry an explicit `"llm_judge": false` that is indistinguishable from a deliberate refusal, so the upgrade proposes turning them on — and the user gets the chance to decline.
|
|
136
|
+
|
|
137
|
+
Run the deterministic scan first. It writes nothing:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
python3 "$ADR_KIT/bin/adr-migrate" docs/adr/ --enable-llm-judge --dry-run --format json
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The result has three lists — `enabled` (what would be turned on), `opted_out` (rule-less blocks the scan proposes to mark as having no code surface), and `unchanged` — plus a `summary` carrying the two numbers that decide this step: `judged_after` (how many ADRs the LLM pass evaluates once the migration lands) and `unbounded_after` (how many of those declare no `path_glob`).
|
|
144
|
+
|
|
145
|
+
**Then ask the user, once, with the whole picture in front of them.** Show:
|
|
146
|
+
|
|
147
|
+
- **the `summary` totals first.** The `enabled` list is only this run's delta; on an upgraded repository the dominant cost sits in ADRs that are already on. A dry-run reading "6 enabled, 0 unbounded" has been accepted on a set that ended at 64 unscoped of 68 judged, which at the measured 20–28 s per isolated call is ~25 minutes of blocking per commit;
|
|
148
|
+
- how many ADRs would be enabled, and for each one its id, its one-line Decision and its rule count;
|
|
149
|
+
- which ADRs carry `unbounded_scope: true` — those have no `path_glob` to narrow with, so enabling them costs a model call on **every** commit, not only on commits that touch their area;
|
|
150
|
+
- which ADRs the scan proposes to mark as no-code-surface, and why.
|
|
151
|
+
|
|
152
|
+
Offer these answers:
|
|
153
|
+
|
|
154
|
+
- **accept all** (the default) — apply as proposed.
|
|
155
|
+
- **opt out of specific ADRs** — name them; each needs a reason, which is written into the ADR as `llm_judge_reason` so no later upgrade re-proposes it.
|
|
156
|
+
- **enable a rule-less ADR anyway** — name it under `--force-enable`; say plainly that this means one call per commit until the ADR declares a scope.
|
|
157
|
+
- **skip entirely** — change nothing; the next upgrade will ask again.
|
|
158
|
+
|
|
159
|
+
Apply the answer:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
python3 "$ADR_KIT/bin/adr-migrate" docs/adr/ --enable-llm-judge \
|
|
163
|
+
--except ADR-006,ADR-011 --reason "reviewed manually in the release checklist" \
|
|
164
|
+
--force-enable ADR-014
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Report exactly which ADRs were enabled and which were left off. State the cost shape in the same breath, and state it for the whole set: a commit makes one isolated call per scoped ADR whose `path_glob` the diff touches, **plus one call for every unscoped ADR regardless of the diff**. "A commit outside every scope makes none" holds only when `unbounded_after` is zero.
|
|
168
|
+
|
|
169
|
+
Re-running the command after this is a no-op and says so.
|
|
170
|
+
|
|
171
|
+
## Step 4b² — Make the pass runnable, and decide where it runs
|
|
172
|
+
|
|
173
|
+
Enabling `llm_judge` on ADRs configures what SHOULD be judged; it does not make the judge able to run, and it does not decide where the cost lands. An upgrade that stops here can leave a project whose pass degrades silently on every commit, or one whose commits block for half an hour. Finish both halves:
|
|
174
|
+
|
|
175
|
+
**1. The host client.** Read the effective configuration:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
python3 "$ADR_KIT/bin/adr-judge" --show-config
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
- Retired keys present (`judge.llm_cmd`, `judge.llm_model`, `judge.openrouter_model`, `judge.ollama_model`, `judge.openai_model`) → config validation refuses each by name and says what replaced it (ADR-036). Have the user delete the keys from `.adr-kit.json`; no command edits a file that carries them.
|
|
182
|
+
- No recorded client → record it now rather than leaving it to the first degraded commit:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
python3 "$ADR_KIT/bin/adr-judge" --set-backend host --host-client claude-code-cli
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The host model is the only backend (ADR-036); operators can override one run with `ADR_KIT_LLM_CMD` / `--llm-cmd`.
|
|
189
|
+
|
|
190
|
+
**2. The cadence.** Take `unbounded_after` from Step 4b's summary and put the multiplication in front of the user: `unbounded_after × ~20 s` is what every commit will block, sequentially, because the pass makes one isolated call per ADR. Two honest configurations exist:
|
|
191
|
+
|
|
192
|
+
- `unbounded_after` is small (a handful): per-commit judging is affordable; leave `judge.llm_enabled` on.
|
|
193
|
+
- `unbounded_after` is large: per-commit judging is not viable, and no faster model fixes a per-ADR multiplier. Offer `judge.llm_enabled: false` (the declarative pass keeps blocking, at milliseconds) with the **guardian llm tier** as the semantic cadence — `guardian.llm_stale_days` in `docs/adr/.adr-kit.json` (default 14; 7 for a weekly pass) makes the SessionStart nudge raise it when due, cost-gated by `guardian.llm_autorun: false`.
|
|
194
|
+
|
|
195
|
+
Record the choice in the wrap-up so the next reader of `.adr-kit.json` sees a decision, not an accident.
|
|
196
|
+
|
|
197
|
+
## Step 4c — The signer: propose, never assume
|
|
198
|
+
|
|
199
|
+
Every lifecycle command writes a Status History entry naming who decided, and it
|
|
200
|
+
refuses to sign on the user's behalf. That refusal is right, and it should not be
|
|
201
|
+
the user's first experience of the tool.
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
python3 "$ADR_KIT/bin/adr" signer --suggest --adr-dir docs/adr
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Read-only: it finds candidates and writes nothing. It looks at the signed-in
|
|
208
|
+
GitHub account (`gh api user`, when the CLI is available) and at
|
|
209
|
+
`git config user.name`, ranks them, and shows each with its source — a proposal
|
|
210
|
+
the user cannot trace is one they cannot judge, and this value lands in an
|
|
211
|
+
immutable history.
|
|
212
|
+
|
|
213
|
+
- **Candidates found** — show them and ask which to adopt, or let the user type a
|
|
214
|
+
different name. Then write it:
|
|
215
|
+
`python3 "$ADR_KIT/bin/adr" signer --set "User: <chosen>"`.
|
|
216
|
+
- **Already configured** — say so and move on. Do not overwrite it.
|
|
217
|
+
- **Nothing found** — the GitHub CLI is absent or signed out and git names nobody
|
|
218
|
+
usable. Ask for the name outright rather than guessing.
|
|
219
|
+
|
|
220
|
+
**Bot and CI identities are deliberately not offered.** `github-actions[bot]`,
|
|
221
|
+
`runner`, a bare `user`: those are configured values that name a machine, and
|
|
222
|
+
R8 asks for evidence of which *human* accepted a decision.
|
|
223
|
+
|
|
224
|
+
The value is machine-local by design (`docs/adr/.adr-kit.local.json`, gitignored)
|
|
225
|
+
because writing one person's name into the tracked config would sign every
|
|
226
|
+
teammate's acceptances. Each machine, container and CI runner needs its own.
|
|
227
|
+
|
|
228
|
+
## Step 5 — Final lint
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
"$ADR_KIT/bin/adr-lint" docs/adr/
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Report the result. Then optionally run a no-op judge to confirm hook plumbing:
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
echo "" | "$ADR_KIT/bin/adr-judge" --diff - --adr-dir docs/adr/
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Should exit 0 with `OK — 0 violations, 0 advisory`.
|
|
241
|
+
|
|
242
|
+
## Wrap-up
|
|
243
|
+
|
|
244
|
+
Print the final summary:
|
|
245
|
+
|
|
246
|
+
```
|
|
247
|
+
adr-kit upgrade complete:
|
|
248
|
+
- CLAUDE.md: <unchanged | refreshed | migrated from v0.11>
|
|
249
|
+
- guide: .claude/adr-kit-guide.md (created | refreshed | unchanged)
|
|
250
|
+
- hook: <installed | already present>
|
|
251
|
+
- backfill: <N> ADRs got declarative rules, <M> got llm_judge:true, <K> skipped, <Q> already had Enforcement
|
|
252
|
+
- lint: <P> PASS, <A> ADVISORY, <F> FAIL
|
|
253
|
+
- formats: <N> deterministic migration notices, <M> guided notices; 0 auto-migrated
|
|
254
|
+
- judge: backend <name | none>, <judged_after> ADRs judged, <unbounded_after> unscoped;
|
|
255
|
+
cadence <per-commit | guardian llm tier every <D>d | declarative-only>
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Suggest a commit:
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
git add CLAUDE.md .claude/adr-kit-guide.md .githooks/pre-commit docs/adr/
|
|
262
|
+
git commit -m "chore(adr-kit): upgrade to v0.12"
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Do not run the commit yourself.
|
|
266
|
+
|
|
267
|
+
## Constraints
|
|
268
|
+
|
|
269
|
+
- **Per-ADR backfill is opt-in.** Never silently rewrite ADR contents. Each proposal is shown, the user accepts/edits/skips.
|
|
270
|
+
- **Surrounding CLAUDE.md content stays byte-exact.** Only the marked stub block (or v0.11 `## ADR Kit Rules` section being replaced) may change.
|
|
271
|
+
- **Re-runnable.** A second invocation should detect "already on v0.12" and exit cleanly.
|
|
272
|
+
- **No new ADRs.** This skill never invokes `adr-generator`. New ADRs come from `/adr-kit:init` (first-time bootstrap) or `/adr-kit:adr` (on-demand authoring).
|
|
273
|
+
- **Default-on hook.** Don't prompt for hook installation as if it were optional. The opt-out path is `--uninstall`, not pre-install consent.
|