@rvdbreemen/adr-kit-opencode 0.52.0 → 0.53.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 -29
- package/README.md +865 -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 +96 -4
- 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/adr_doctor_probes.py +2 -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 +101 -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
|
@@ -1,48 +1,101 @@
|
|
|
1
|
-
<!-- adr-kit-guide v0.35.0 -->
|
|
2
|
-
<!-- Generated ADR Kit guidance. Local additions belong in .adr-kit/ADR-guide.local.md. -->
|
|
3
|
-
|
|
4
|
-
# ADR Kit agent guide
|
|
5
|
-
|
|
6
|
-
Architecture decisions live in `docs/adr/`. Read the source ADR before treating
|
|
7
|
-
a generated summary as binding.
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
##
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
1
|
+
<!-- adr-kit-guide v0.35.0 -->
|
|
2
|
+
<!-- Generated ADR Kit guidance. Local additions belong in .adr-kit/ADR-guide.local.md. -->
|
|
3
|
+
|
|
4
|
+
# ADR Kit agent guide
|
|
5
|
+
|
|
6
|
+
Architecture decisions live in `docs/adr/`. Read the source ADR before treating
|
|
7
|
+
a generated summary as binding. This guide is written so an agent can operate
|
|
8
|
+
adr-kit autonomously: every step names the tool to call, what comes back, and
|
|
9
|
+
how to react. Steps marked **human-gated** must never be performed without an
|
|
10
|
+
explicit human decision.
|
|
11
|
+
|
|
12
|
+
## Tool surface
|
|
13
|
+
|
|
14
|
+
Every step below is callable two ways. Shell-less clients use the MCP tools;
|
|
15
|
+
clients with a shell may use the CLI directly. Both delegate to the same
|
|
16
|
+
deterministic engines, so results are identical.
|
|
17
|
+
|
|
18
|
+
| Phase | MCP tool | CLI equivalent | Mutates? |
|
|
19
|
+
| --- | --- | --- | --- |
|
|
20
|
+
| Find governing ADRs | `adr_context` | `bin/adr-context --format json` | no |
|
|
21
|
+
| Follow ADR graph links | `adr_related` | `bin/adr-related --format json` | no |
|
|
22
|
+
| Judge a diff | `adr_judge` | `bin/adr-judge --json` | no |
|
|
23
|
+
| Lint the ADR set | `adr_lint` | `bin/adr-lint --format json` | no |
|
|
24
|
+
| Score ADR quality | `adr_quality` | `bin/adr-quality --format json` | no |
|
|
25
|
+
| Check lifecycle readiness | `adr_readiness` | `bin/adr-readiness --format json` | no |
|
|
26
|
+
| Repository health | `adr_status` | `bin/adr-status --format json` | no |
|
|
27
|
+
| Create / edit / accept ADRs | — (deliberately absent) | `bin/adr new`, `answer`, `relate`, ... | yes |
|
|
28
|
+
|
|
29
|
+
The MCP server is read-only by design (ADR-011, ADR-040): no MCP tool can
|
|
30
|
+
create, edit, accept, or index an ADR. Lifecycle mutation always goes through
|
|
31
|
+
the CLI, and acceptance always goes through a human.
|
|
32
|
+
|
|
33
|
+
## Before implementation
|
|
34
|
+
|
|
35
|
+
1. Query the task with `adr_context` (MCP) or `bin/adr-context`. Pass the task
|
|
36
|
+
description as `query`; add `paths` for the files you expect to touch.
|
|
37
|
+
2. Read every returned Accepted ADR at the source, and call `adr_related` on
|
|
38
|
+
each id you rely on to see supersession, related decisions, and dangling
|
|
39
|
+
links. A superseded ADR is history, not guidance: follow the successor.
|
|
40
|
+
3. If the work introduces or changes a long-lived decision, create a Proposed
|
|
41
|
+
record with `bin/adr new` (or `adr-kit:adr`) before writing the code.
|
|
42
|
+
**Human-gated:** the record stays Proposed until a human accepts it; never
|
|
43
|
+
run `bin/adr accept` on your own initiative.
|
|
44
|
+
|
|
45
|
+
## During implementation
|
|
46
|
+
|
|
47
|
+
- Treat hook-provided ADR context as advisory steering. Hooks fail open.
|
|
48
|
+
- Treat deterministic pre-commit enforcement as the blocking floor.
|
|
49
|
+
- Never rewrite an Accepted ADR. Create a Proposed successor and use the
|
|
50
|
+
supersession lifecycle (`bin/adr supersede`, human-gated like acceptance).
|
|
51
|
+
- Keep generated indexes and client artifacts deterministic; edit their
|
|
52
|
+
canonical sources instead.
|
|
53
|
+
|
|
54
|
+
## Before completion
|
|
55
|
+
|
|
56
|
+
1. Run `adr_lint` with `strict: true` (MCP) or `bin/adr-lint --strict`.
|
|
57
|
+
React: `verdict: ok` proceeds; `verdict: findings` lists failing files and
|
|
58
|
+
findings — fix the ADR content, never weaken the gate. Exit 2 is a config
|
|
59
|
+
error: report it, do not work around it.
|
|
60
|
+
2. After ADR changes, regenerate `docs/adr/ADR-INDEX.md`,
|
|
61
|
+
`docs/adr/ADR-INDEX.json`, and the generated README block with
|
|
62
|
+
`bin/adr-index docs/adr` (CLI only; index generation mutates).
|
|
63
|
+
3. Judge the staged diff with `adr_judge` (MCP, pass the unified diff) or
|
|
64
|
+
`bin/adr-judge`. React: `verdict: ok` proceeds; `verdict: violation` names
|
|
65
|
+
the ADR and rule per finding — change the code to comply, or propose a
|
|
66
|
+
successor ADR if the decision itself is wrong. Never commit past a
|
|
67
|
+
violation.
|
|
68
|
+
4. For a Proposed ADR, check `adr_readiness`. React: `classification` tells
|
|
69
|
+
you what is missing (open questions, implementation links, quality). Fix
|
|
70
|
+
what is mechanical; leave acceptance to a human.
|
|
71
|
+
5. Record the decision, evidence, and verification in the project task.
|
|
72
|
+
|
|
73
|
+
## Human-gated actions
|
|
74
|
+
|
|
75
|
+
These require an explicit human decision, every time:
|
|
76
|
+
|
|
77
|
+
- `bin/adr accept` (and `--confirm`): acceptance writes a person's name into
|
|
78
|
+
an immutable status history (ADR-011, ADR-027).
|
|
79
|
+
- `bin/adr supersede`, `bin/adr reject`: same lifecycle authority.
|
|
80
|
+
- Choosing or changing the lifecycle signer (`bin/adr signer --set`).
|
|
81
|
+
|
|
82
|
+
Everything else in the tables above is safe for autonomous use: the read-only
|
|
83
|
+
tools always, and the mutating authoring commands (`new`, `answer`, `relate`,
|
|
84
|
+
`adr-index`) when the task itself calls for them.
|
|
85
|
+
|
|
86
|
+
## Ownership
|
|
87
|
+
|
|
88
|
+
`.adr-kit/ADR-guide.md` is generated and may be replaced after backup.
|
|
89
|
+
Put project-specific guidance in `.adr-kit/ADR-guide.local.md` or outside ADR
|
|
90
|
+
Kit marker blocks in `AGENTS.md`, `CLAUDE.md`, and Copilot instructions.
|
|
91
|
+
|
|
92
|
+
If `.adr-kit/ADR-guide.local.md` exists, read it after this file. It is
|
|
93
|
+
user-owned and ADR Kit never overwrites or removes it.
|
|
94
|
+
|
|
95
|
+
## Judgment
|
|
96
|
+
|
|
97
|
+
Deterministic ADR checks remain available without a model. Paid or cloud model
|
|
98
|
+
judgment is opt-in. Local judgment is active only when a configured or
|
|
99
|
+
unambiguously discovered provider/model identity has been verified. Missing,
|
|
100
|
+
ambiguous, or unreachable models are degraded optional judgment, never a
|
|
101
|
+
successful judgment result.
|
|
@@ -1,82 +1,82 @@
|
|
|
1
|
-
# ADR Rules for Coding Work
|
|
2
|
-
|
|
3
|
-
When you are about to implement or change code, run through these rules **before** writing.
|
|
4
|
-
|
|
5
|
-
## Before implementing
|
|
6
|
-
|
|
7
|
-
- **Check for existing ADRs**: scan `docs/adr/` for an ADR that governs the area you are about to touch. The fastest path: read `docs/adr/README.md` index, then open the relevant ADRs.
|
|
8
|
-
- **Assess architectural significance**: does the change affect any of the following?
|
|
9
|
-
- Architecture: service or module boundaries, deployment topology, integration patterns
|
|
10
|
-
- Non-functional requirements: security, availability, performance, privacy, resilience
|
|
11
|
-
- Interfaces and contracts: public APIs, message topics, RPC contracts, breaking changes
|
|
12
|
-
- Dependencies: new framework, new library, swap-out with broad impact
|
|
13
|
-
- Build and tooling: build system, CI gates, development workflow
|
|
14
|
-
|
|
15
|
-
If yes, an ADR is in scope. If clearly no (bug fix, refactor that preserves contract, doc fix), skip the ADR work.
|
|
16
|
-
- **Use the canonical guide**: `docs/adr/README.md` is the source of truth for the project's ADR conventions. The ADR `SKILL.md` installed by Claude Code, Codex, or GitHub Copilot CLI is the comprehensive how-to.
|
|
17
|
-
|
|
18
|
-
## Creating a new ADR
|
|
19
|
-
|
|
20
|
-
If no ADR exists and the change is architecturally significant:
|
|
21
|
-
|
|
22
|
-
1. **Hand the work to the ADR generator subagent** (`adr-generator`). Provide it with the title, decision, alternatives, constraints, and any related ADRs. The agent writes a fully-formed ADR file at `docs/adr/ADR-XXX-title.md`.
|
|
23
|
-
2. **Review the generated ADR yourself** before linking from code: confirm it passes the four verification gates (Completeness, Evidence, Clarity, Consistency) defined in the skill.
|
|
24
|
-
3. **Reference the ADR** in your commit message and (if relevant) the PR description: `ADR: docs/adr/ADR-XXX-title.md`.
|
|
25
|
-
4. **Add code comments** that point to the ADR at non-obvious enforcement sites: `// See ADR-XXX for why we use this pattern.`
|
|
26
|
-
5. **Add an Enforcement block (v0.12+) when the rule has any code surface.** Accepted ADRs SHOULD carry an `## Enforcement` section. Three patterns:
|
|
27
|
-
- **Declarative** (`forbid_pattern` / `forbid_import` / `require_pattern`) — regex/glob rules that `bin/adr-judge` runs at commit time. Preferred when expressible; fast, no LLM round-trip.
|
|
28
|
-
- **`"llm_judge": true`** — for rules that need a model's judgement (semantic compliance, intent reading). The pre-commit hook batches all `llm_judge: true` ADRs into ONE Claude Sonnet call (`claude -p --model claude-sonnet-4-6`) and blocks the commit on `VIOLATION` when the LLM pass is active. As of v0.17.0 the LLM pass is opt-in: enable via `judge.llm_enabled:true` in `.adr-kit.json`, or `ADR_KIT_LLM=1` for a single commit. Falls back to declarative-only when the `claude` CLI is missing — never blocks on tooling drift. The same engine drives `/adr-kit:judge` (which always fires the LLM pass regardless of config) so verdicts are consistent across hook and skill.
|
|
29
|
-
- **Section omitted** — for governance / process ADRs with no code surface. Add a one-line explanation in the body so reviewers (Check 7) know it's intentional.
|
|
30
|
-
|
|
31
|
-
Schema: `schemas/adr-enforcement.schema.json`. Canonical guide: `.claude/adr-kit-guide.md` after `/adr-kit:init`.
|
|
32
|
-
|
|
33
|
-
## Superseding an existing ADR
|
|
34
|
-
|
|
35
|
-
If your change reverses or replaces an `Accepted` ADR:
|
|
36
|
-
|
|
37
|
-
1. **Do not modify the accepted ADR's decision text or reasoning.** ADRs are immutable once `Accepted`, except for the Status line and an appended `## Status History` transition.
|
|
38
|
-
2. **Write a new superseding ADR** that explains: (a) what is changing, (b) why the original choice no longer fits, (c) what the new choice is, (d) the migration path if consumers are affected.
|
|
39
|
-
3. **Update status without rewriting history**: set the old ADR's Status line to `Superseded by ADR-YYY` and append the matching `status_history` entry. Rationale lives in the new ADR.
|
|
40
|
-
4. **Cross-link** in both ADRs' `## Related Decisions` sections.
|
|
41
|
-
|
|
42
|
-
## Amending (vs superseding)
|
|
43
|
-
|
|
44
|
-
Some ADRs have a stable contract but a narrow scope-change. The toolkit distinguishes:
|
|
45
|
-
|
|
46
|
-
- **Supersede**: the old decision is no longer in force. Status line of old ADR: `Superseded by ADR-YYY`.
|
|
47
|
-
- **Amend**: the old decision still stands, but a specific aspect is narrowed or extended. Status line of old ADR: `Amended by ADR-YYY` (optional: leave `Accepted` if amend is content-additive only).
|
|
48
|
-
|
|
49
|
-
Use amend when the existing ADR's other consumers should not have to change. Use supersede when the contract itself is replaced.
|
|
50
|
-
|
|
51
|
-
## Implementation checklist
|
|
52
|
-
|
|
53
|
-
For every commit that lands an architecturally significant change:
|
|
54
|
-
|
|
55
|
-
- [ ] An ADR exists or has been created via the adr-generator agent
|
|
56
|
-
- [ ] The ADR follows the project structure in `docs/adr/README.md`
|
|
57
|
-
- [ ] At least 2 alternatives are documented with rejection reasoning
|
|
58
|
-
- [ ] Consequences include both positive and negative impacts; risks have mitigations
|
|
59
|
-
- [ ] The four verification gates from the skill all pass
|
|
60
|
-
- [ ] Commit message and PR description link to the ADR
|
|
61
|
-
- [ ] If superseding, the old ADR's Status line and appended Status History entry are updated and cross-references are in place
|
|
62
|
-
- [ ] Code comments point at the ADR at non-obvious enforcement sites
|
|
63
|
-
|
|
64
|
-
## Definition of Done
|
|
65
|
-
|
|
66
|
-
- ADR exists, is readable, and is reachable from `docs/adr/README.md`
|
|
67
|
-
- ADR focuses on rationale ("why"), not implementation detail ("how")
|
|
68
|
-
- The PR or commit links to the ADR by path
|
|
69
|
-
- Supersession or amendment chain is correct (if applicable)
|
|
70
|
-
- ADR has no placeholders, no `TODO:` markers, no em dashes
|
|
71
|
-
|
|
72
|
-
## When the ADR rule does not apply
|
|
73
|
-
|
|
74
|
-
Skip the ADR work for:
|
|
75
|
-
|
|
76
|
-
- Bug fixes that do not change a contract
|
|
77
|
-
- Refactors that preserve external behaviour
|
|
78
|
-
- Documentation updates (unless the doc *is* an ADR)
|
|
79
|
-
- Configuration tweaks within an existing range
|
|
80
|
-
- Minor feature additions that fit an established pattern
|
|
81
|
-
|
|
82
|
-
If you are unsure, default to creating an ADR. The cost of writing one is 15 to 30 minutes; the cost of re-deriving the rationale 6 months from now is hours. (See the Anti-Rationalization Guards table in `SKILL.md`.)
|
|
1
|
+
# ADR Rules for Coding Work
|
|
2
|
+
|
|
3
|
+
When you are about to implement or change code, run through these rules **before** writing.
|
|
4
|
+
|
|
5
|
+
## Before implementing
|
|
6
|
+
|
|
7
|
+
- **Check for existing ADRs**: scan `docs/adr/` for an ADR that governs the area you are about to touch. The fastest path: read `docs/adr/README.md` index, then open the relevant ADRs.
|
|
8
|
+
- **Assess architectural significance**: does the change affect any of the following?
|
|
9
|
+
- Architecture: service or module boundaries, deployment topology, integration patterns
|
|
10
|
+
- Non-functional requirements: security, availability, performance, privacy, resilience
|
|
11
|
+
- Interfaces and contracts: public APIs, message topics, RPC contracts, breaking changes
|
|
12
|
+
- Dependencies: new framework, new library, swap-out with broad impact
|
|
13
|
+
- Build and tooling: build system, CI gates, development workflow
|
|
14
|
+
|
|
15
|
+
If yes, an ADR is in scope. If clearly no (bug fix, refactor that preserves contract, doc fix), skip the ADR work.
|
|
16
|
+
- **Use the canonical guide**: `docs/adr/README.md` is the source of truth for the project's ADR conventions. The ADR `SKILL.md` installed by Claude Code, Codex, or GitHub Copilot CLI is the comprehensive how-to.
|
|
17
|
+
|
|
18
|
+
## Creating a new ADR
|
|
19
|
+
|
|
20
|
+
If no ADR exists and the change is architecturally significant:
|
|
21
|
+
|
|
22
|
+
1. **Hand the work to the ADR generator subagent** (`adr-generator`). Provide it with the title, decision, alternatives, constraints, and any related ADRs. The agent writes a fully-formed ADR file at `docs/adr/ADR-XXX-title.md`.
|
|
23
|
+
2. **Review the generated ADR yourself** before linking from code: confirm it passes the four verification gates (Completeness, Evidence, Clarity, Consistency) defined in the skill.
|
|
24
|
+
3. **Reference the ADR** in your commit message and (if relevant) the PR description: `ADR: docs/adr/ADR-XXX-title.md`.
|
|
25
|
+
4. **Add code comments** that point to the ADR at non-obvious enforcement sites: `// See ADR-XXX for why we use this pattern.`
|
|
26
|
+
5. **Add an Enforcement block (v0.12+) when the rule has any code surface.** Accepted ADRs SHOULD carry an `## Enforcement` section. Three patterns:
|
|
27
|
+
- **Declarative** (`forbid_pattern` / `forbid_import` / `require_pattern`) — regex/glob rules that `bin/adr-judge` runs at commit time. Preferred when expressible; fast, no LLM round-trip.
|
|
28
|
+
- **`"llm_judge": true`** — for rules that need a model's judgement (semantic compliance, intent reading). The pre-commit hook batches all `llm_judge: true` ADRs into ONE Claude Sonnet call (`claude -p --model claude-sonnet-4-6`) and blocks the commit on `VIOLATION` when the LLM pass is active. As of v0.17.0 the LLM pass is opt-in: enable via `judge.llm_enabled:true` in `.adr-kit.json`, or `ADR_KIT_LLM=1` for a single commit. Falls back to declarative-only when the `claude` CLI is missing — never blocks on tooling drift. The same engine drives `/adr-kit:judge` (which always fires the LLM pass regardless of config) so verdicts are consistent across hook and skill.
|
|
29
|
+
- **Section omitted** — for governance / process ADRs with no code surface. Add a one-line explanation in the body so reviewers (Check 7) know it's intentional.
|
|
30
|
+
|
|
31
|
+
Schema: `schemas/adr-enforcement.schema.json`. Canonical guide: `.claude/adr-kit-guide.md` after `/adr-kit:init`.
|
|
32
|
+
|
|
33
|
+
## Superseding an existing ADR
|
|
34
|
+
|
|
35
|
+
If your change reverses or replaces an `Accepted` ADR:
|
|
36
|
+
|
|
37
|
+
1. **Do not modify the accepted ADR's decision text or reasoning.** ADRs are immutable once `Accepted`, except for the Status line and an appended `## Status History` transition.
|
|
38
|
+
2. **Write a new superseding ADR** that explains: (a) what is changing, (b) why the original choice no longer fits, (c) what the new choice is, (d) the migration path if consumers are affected.
|
|
39
|
+
3. **Update status without rewriting history**: set the old ADR's Status line to `Superseded by ADR-YYY` and append the matching `status_history` entry. Rationale lives in the new ADR.
|
|
40
|
+
4. **Cross-link** in both ADRs' `## Related Decisions` sections.
|
|
41
|
+
|
|
42
|
+
## Amending (vs superseding)
|
|
43
|
+
|
|
44
|
+
Some ADRs have a stable contract but a narrow scope-change. The toolkit distinguishes:
|
|
45
|
+
|
|
46
|
+
- **Supersede**: the old decision is no longer in force. Status line of old ADR: `Superseded by ADR-YYY`.
|
|
47
|
+
- **Amend**: the old decision still stands, but a specific aspect is narrowed or extended. Status line of old ADR: `Amended by ADR-YYY` (optional: leave `Accepted` if amend is content-additive only).
|
|
48
|
+
|
|
49
|
+
Use amend when the existing ADR's other consumers should not have to change. Use supersede when the contract itself is replaced.
|
|
50
|
+
|
|
51
|
+
## Implementation checklist
|
|
52
|
+
|
|
53
|
+
For every commit that lands an architecturally significant change:
|
|
54
|
+
|
|
55
|
+
- [ ] An ADR exists or has been created via the adr-generator agent
|
|
56
|
+
- [ ] The ADR follows the project structure in `docs/adr/README.md`
|
|
57
|
+
- [ ] At least 2 alternatives are documented with rejection reasoning
|
|
58
|
+
- [ ] Consequences include both positive and negative impacts; risks have mitigations
|
|
59
|
+
- [ ] The four verification gates from the skill all pass
|
|
60
|
+
- [ ] Commit message and PR description link to the ADR
|
|
61
|
+
- [ ] If superseding, the old ADR's Status line and appended Status History entry are updated and cross-references are in place
|
|
62
|
+
- [ ] Code comments point at the ADR at non-obvious enforcement sites
|
|
63
|
+
|
|
64
|
+
## Definition of Done
|
|
65
|
+
|
|
66
|
+
- ADR exists, is readable, and is reachable from `docs/adr/README.md`
|
|
67
|
+
- ADR focuses on rationale ("why"), not implementation detail ("how")
|
|
68
|
+
- The PR or commit links to the ADR by path
|
|
69
|
+
- Supersession or amendment chain is correct (if applicable)
|
|
70
|
+
- ADR has no placeholders, no `TODO:` markers, no em dashes
|
|
71
|
+
|
|
72
|
+
## When the ADR rule does not apply
|
|
73
|
+
|
|
74
|
+
Skip the ADR work for:
|
|
75
|
+
|
|
76
|
+
- Bug fixes that do not change a contract
|
|
77
|
+
- Refactors that preserve external behaviour
|
|
78
|
+
- Documentation updates (unless the doc *is* an ADR)
|
|
79
|
+
- Configuration tweaks within an existing range
|
|
80
|
+
- Minor feature additions that fit an established pattern
|
|
81
|
+
|
|
82
|
+
If you are unsure, default to creating an ADR. The cost of writing one is 15 to 30 minutes; the cost of re-deriving the rationale 6 months from now is hours. (See the Anti-Rationalization Guards table in `SKILL.md`.)
|