Repository navigation
docs(conventions): amend ADR 0075 for evidence-gated plugin trigger lines and add the setup-lifecycle owner doc #9801
Description
Refs #6594. Slice 1 of 4. Runs first; slices 2 and 4 wait on it.
Problem
The owner decided on 2026-10-24 (Q98, comment on #6594) that a plugin's setup may add one trigger line to the always-loaded root AGENTS.md, but only with stumble evidence that the plugin needs it. On origin/main two records still forbid it:
docs/adr/0075-resolve-plugin-settings-through-one-four-layer-cascade-and-a-bound-convention-home.md:96-97: "A setup action offers to write the convention files, and nothing is always-loaded."docs/conventions/config-cascade/README.md:297: "nothing is always-loaded".
developer-experience already ships such a line inside a <!-- BEGIN GENERATED: plugin-conventions --> block (plugins/developer-experience/skills/setup/scripts/pointer-line.sh:23-26), so the shipped behavior is undocumented. No owner doc for the setup lifecycle exists: docs/conventions/setup-lifecycle/ is absent on origin/main.
Fix
- Amend ADR 0075 in place, following the repository's amendment precedent (status line
accepted; amended 2026-10-24 (...)plus an## Amendment (2026-10-24): ...section, as indocs/adr/0062-*.md:3and its## Amendment (2026-10-16)heading). The amendment allows one trigger line per plugin inside the sharedGENERATED: plugin-conventionsblock of the rootAGENTS.md, written by that plugin's setup after confirmation, naming only model-invokable skills, and allowed only with that plugin's own stumble evidence (docs/plugin-philosophy.mdInstruction economy). It keeps thedeveloper-experienceblock as the shipped form. - Write
docs/conventions/setup-lifecycle/README.mdas the owner doc: the managed block and its one-line-per-plugin ownership rule (frompointer-line.sh), the evidence gate, thecheck/applyverb set (pointing atdocs/plugin-philosophy.mdsetup section, not restating it), and placeholders that name slices 2 to 4 (provenance, converge-by-stateapply, current-facts check) as the sections they fill. No user-level~/.config/<plugin>/layer: ADR 0075 fix 9 retired the user-global file layer intouserConfig. - Add a row for it to the Convention registry in
docs/plugin-philosophy.md(line 822 onward), and amenddocs/conventions/config-cascade/README.md:297to point at the new rule.
Out of scope: migrating existing .claude/* surfaces (#5906), the resolver and setup writer already delivered under ADR 0064 and #7934, #7938, #7939, and editing this repository's own AGENTS.md.
Done when
-
test -f docs/conventions/setup-lifecycle/README.mdexits 0 -
grep -c 'GENERATED: plugin-conventions' docs/conventions/setup-lifecycle/README.mdprints 1 or more -
grep -c '^## Amendment (2026-10-24)' docs/adr/0075-*.mdprints 1 -
grep -c 'nothing is always-loaded' docs/conventions/config-cascade/README.mdprints 0 -
sed -n 3p docs/adr/0075-*.mdcontainsamended 2026-10-24 -
grep -c 'setup-lifecycle/README.md' docs/plugin-philosophy.mdprints 1 or more -
bash scripts/check-conformance-registry.sh --checkandbash scripts/check-adr-numbers.sh --checkexit 0 -
ci-statusis green on the PR head
Activity
github-actions commentedon Oct 24, 2026
Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Low
Uncertainty: Known
Flags: none
Understood: this is slice 1 of 4 under #6594. It amends ADR 0075 so a plugin's setup may add one evidence-gated trigger line to the shared plugin-conventions block. It also adds the setup-lifecycle owner doc, a registry row in plugin-philosophy.md, and a pointer in the config-cascade README. The scope, the owner decision and the done-when checks are all clear. I found no likely duplicates among the open issues.
Automated triage, applied by the lanes App.