@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.
- package/.claude-plugin/plugin.json +29 -29
- package/README.md +861 -850
- package/bin/adr +0 -0
- package/bin/adr-audit +0 -0
- package/bin/adr-context +0 -0
- package/bin/adr-discover +0 -0
- package/bin/adr-doctor +0 -0
- package/bin/adr-generate-scripts +0 -0
- package/bin/adr-grill-signal +0 -0
- package/bin/adr-guardian +0 -0
- package/bin/adr-index +0 -0
- package/bin/adr-judge +0 -0
- package/bin/adr-judge-precommit +0 -0
- package/bin/adr-lint +0 -0
- package/bin/adr-mcp +0 -0
- package/bin/adr-migrate +0 -0
- package/bin/adr-quality +0 -0
- package/bin/adr-readiness +0 -0
- package/bin/adr-readiness-ci +0 -0
- package/bin/adr-related +0 -0
- package/bin/adr-renumber +254 -254
- package/bin/adr-retire +0 -0
- package/bin/adr-settings +0 -0
- package/bin/adr-status +0 -0
- package/bin/adr-suggest +0 -0
- package/bin/adr-watch +0 -0
- package/bin/bump-version +0 -0
- package/clients/workflows.json +229 -229
- package/hooks/__init__.py +1 -1
- package/hooks/adapters/__init__.py +13 -13
- package/hooks/adapters/claude.py +27 -27
- package/hooks/adapters/codex.py +26 -26
- package/hooks/adapters/copilot.py +11 -11
- package/hooks/adr-hook.py +128 -128
- package/hooks/adr_hook_core.py +843 -843
- package/hooks/adr_pr_guard.py +367 -367
- package/instructions/ADR-guide.md +48 -48
- package/instructions/adr.coding.md +82 -82
- package/instructions/adr.review.md +182 -182
- package/opencode/plugin.ts +1 -4
- package/package.json +5 -2
- package/schemas/adr-context-probes.schema.json +56 -56
- package/schemas/adr-enforcement.schema.json +57 -57
- package/schemas/adr-frontmatter.schema.json +144 -144
- package/schemas/adr-index.schema.json +276 -276
- package/schemas/adr-kit-config.schema.json +371 -371
- package/schemas/adr-readiness.schema.json +41 -41
- package/schemas/client-capabilities.schema.json +503 -503
- package/schemas/client-certification.schema.json +101 -101
- package/schemas/doctor-output.schema.json +92 -92
- package/skills/adr/SKILL.md +780 -780
- package/skills/audit/SKILL.md +103 -103
- package/skills/context/SKILL.md +77 -77
- package/skills/grill/SKILL.md +84 -84
- package/skills/grill/agents/openai.yaml +4 -4
- package/skills/guardian/SKILL.md +316 -316
- package/skills/init/SKILL.md +499 -499
- package/skills/install-hooks/SKILL.md +154 -154
- package/skills/judge/SKILL.md +168 -168
- package/skills/lint/SKILL.md +321 -321
- package/skills/migrate/SKILL.md +313 -313
- package/skills/related/SKILL.md +62 -62
- package/skills/retire/SKILL.md +41 -41
- package/skills/review/SKILL.md +167 -167
- package/skills/settings/SKILL.md +73 -73
- package/skills/setup/SKILL.md +128 -128
- package/skills/supersede/SKILL.md +136 -136
- package/skills/upgrade/SKILL.md +273 -273
- package/templates/adr-kit-guide.md +354 -354
- package/templates/adr-template.canonical.md +115 -115
- package/templates/adr-template.madr.md +131 -131
- package/templates/adr-template.md +131 -131
- package/templates/adr-template.nygard.md +111 -111
- package/templates/cc-settings/guardian-hook-entry.json +9 -9
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-audit.yml +58 -58
- package/templates/github-workflows/adr-guardian-audit.yml +133 -133
- package/templates/github-workflows/adr-index-check.yml +30 -30
- package/templates/github-workflows/adr-judge.yml +31 -31
- package/templates/github-workflows/adr-readiness.yml +18 -18
- package/templates/validate_adr_template.py +38 -38
- package/templates/validate_adr_template.sh +74 -74
package/skills/settings/SKILL.md
CHANGED
|
@@ -1,73 +1,73 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: settings
|
|
3
|
-
description: "Show and change adr-kit settings: LLM backend, judge-by-default, hooks, the status-history signer, guardian cadence. Use to inspect where a value comes from or to change one."
|
|
4
|
-
argument-hint: "[key] [value]"
|
|
5
|
-
disable-model-invocation: true
|
|
6
|
-
allowed-tools: [Read, Bash]
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# adr-kit settings
|
|
10
|
-
|
|
11
|
-
`$ARGUMENTS` may name a key to show, or a `key=value` to set. Empty shows
|
|
12
|
-
everything with its provenance.
|
|
13
|
-
|
|
14
|
-
One place for every knob. Before this existed a user changed settings in three
|
|
15
|
-
disjoint places and one text editor, and two things were simply unreachable:
|
|
16
|
-
`judge.llm_enabled` could be switched on by a shipped writer but never off, and
|
|
17
|
-
the status-history signer had nowhere to live that anyone would find.
|
|
18
|
-
|
|
19
|
-
## Show
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Every row carries its **provenance** — project, machine-local, default, or an
|
|
26
|
-
environment override. That is the column that answers the question a settings
|
|
27
|
-
screen exists for: not "what is this set to" but "why is it set to that".
|
|
28
|
-
|
|
29
|
-
Add `--all` for every key the schema knows, `--format json` for a machine
|
|
30
|
-
reading, `--list` for just the key names.
|
|
31
|
-
|
|
32
|
-
## Change
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --set judge.llm_enabled=false
|
|
36
|
-
python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --unset guardian.enabled
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Values are typed against the schema before they land: `--set guardian.enabled=maybe`
|
|
40
|
-
is refused rather than stored as a truthy string, and a refused write leaves no
|
|
41
|
-
file behind.
|
|
42
|
-
|
|
43
|
-
## Which file a setting lands in, and why it matters
|
|
44
|
-
|
|
45
|
-
| Scope | File | Contains |
|
|
46
|
-
|---|---|---|
|
|
47
|
-
| project | `docs/adr/.adr-kit.json` (tracked) | team decisions: judge behaviour, guardian cadence, retrieval limits |
|
|
48
|
-
| machine-local | `docs/adr/.adr-kit.local.json` (gitignored) | personal or machine facts: `lifecycle.signer`, `judge.host_client` |
|
|
49
|
-
|
|
50
|
-
The command routes each write itself and says where it landed. The split is not
|
|
51
|
-
bookkeeping: a signer written to the tracked file would put one person's name on
|
|
52
|
-
every teammate's acceptance, which is a false attribution rather than a missing
|
|
53
|
-
one. And a host client is a fact about one machine, not a decision about the
|
|
54
|
-
project.
|
|
55
|
-
|
|
56
|
-
## Settings that live elsewhere on purpose
|
|
57
|
-
|
|
58
|
-
- **The signer** can also be set through `bin/adr signer --set "User: <name>"`,
|
|
59
|
-
which additionally offers `git config user.name` as a proposal and can audit
|
|
60
|
-
existing history for entries with no human actor.
|
|
61
|
-
- **Hook installation** is `/adr-kit:install-hooks`, because installing a hook
|
|
62
|
-
writes files outside the config and needs its own consent.
|
|
63
|
-
- **The LLM backend** can also be set through `adr-judge --set-backend`, which
|
|
64
|
-
validates the choice against the live registry.
|
|
65
|
-
|
|
66
|
-
This command shows all of them; where another surface does more than write a
|
|
67
|
-
value, it says so rather than duplicating the work.
|
|
68
|
-
|
|
69
|
-
## What is never shown
|
|
70
|
-
|
|
71
|
-
A credential is reported as a boolean about the environment — whether a key is
|
|
72
|
-
present, never the key. A settings screen needs to know that the environment is
|
|
73
|
-
configured; it does not need the secret to say so.
|
|
1
|
+
---
|
|
2
|
+
name: settings
|
|
3
|
+
description: "Show and change adr-kit settings: LLM backend, judge-by-default, hooks, the status-history signer, guardian cadence. Use to inspect where a value comes from or to change one."
|
|
4
|
+
argument-hint: "[key] [value]"
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
allowed-tools: [Read, Bash]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# adr-kit settings
|
|
10
|
+
|
|
11
|
+
`$ARGUMENTS` may name a key to show, or a `key=value` to set. Empty shows
|
|
12
|
+
everything with its provenance.
|
|
13
|
+
|
|
14
|
+
One place for every knob. Before this existed a user changed settings in three
|
|
15
|
+
disjoint places and one text editor, and two things were simply unreachable:
|
|
16
|
+
`judge.llm_enabled` could be switched on by a shipped writer but never off, and
|
|
17
|
+
the status-history signer had nowhere to live that anyone would find.
|
|
18
|
+
|
|
19
|
+
## Show
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Every row carries its **provenance** — project, machine-local, default, or an
|
|
26
|
+
environment override. That is the column that answers the question a settings
|
|
27
|
+
screen exists for: not "what is this set to" but "why is it set to that".
|
|
28
|
+
|
|
29
|
+
Add `--all` for every key the schema knows, `--format json` for a machine
|
|
30
|
+
reading, `--list` for just the key names.
|
|
31
|
+
|
|
32
|
+
## Change
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --set judge.llm_enabled=false
|
|
36
|
+
python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --unset guardian.enabled
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Values are typed against the schema before they land: `--set guardian.enabled=maybe`
|
|
40
|
+
is refused rather than stored as a truthy string, and a refused write leaves no
|
|
41
|
+
file behind.
|
|
42
|
+
|
|
43
|
+
## Which file a setting lands in, and why it matters
|
|
44
|
+
|
|
45
|
+
| Scope | File | Contains |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| project | `docs/adr/.adr-kit.json` (tracked) | team decisions: judge behaviour, guardian cadence, retrieval limits |
|
|
48
|
+
| machine-local | `docs/adr/.adr-kit.local.json` (gitignored) | personal or machine facts: `lifecycle.signer`, `judge.host_client` |
|
|
49
|
+
|
|
50
|
+
The command routes each write itself and says where it landed. The split is not
|
|
51
|
+
bookkeeping: a signer written to the tracked file would put one person's name on
|
|
52
|
+
every teammate's acceptance, which is a false attribution rather than a missing
|
|
53
|
+
one. And a host client is a fact about one machine, not a decision about the
|
|
54
|
+
project.
|
|
55
|
+
|
|
56
|
+
## Settings that live elsewhere on purpose
|
|
57
|
+
|
|
58
|
+
- **The signer** can also be set through `bin/adr signer --set "User: <name>"`,
|
|
59
|
+
which additionally offers `git config user.name` as a proposal and can audit
|
|
60
|
+
existing history for entries with no human actor.
|
|
61
|
+
- **Hook installation** is `/adr-kit:install-hooks`, because installing a hook
|
|
62
|
+
writes files outside the config and needs its own consent.
|
|
63
|
+
- **The LLM backend** can also be set through `adr-judge --set-backend`, which
|
|
64
|
+
validates the choice against the live registry.
|
|
65
|
+
|
|
66
|
+
This command shows all of them; where another surface does more than write a
|
|
67
|
+
value, it says so rather than duplicating the work.
|
|
68
|
+
|
|
69
|
+
## What is never shown
|
|
70
|
+
|
|
71
|
+
A credential is reported as a boolean about the environment — whether a key is
|
|
72
|
+
present, never the key. A settings screen needs to know that the environment is
|
|
73
|
+
configured; it does not need the secret to say so.
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -1,128 +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.
|
|
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.
|