Skip to content

docs(conventions): amend ADR 0075 for evidence-gated plugin trigger lines and add the setup-lifecycle owner doc #9801

Closed

Description

@kyle-sexton

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

  1. 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 in docs/adr/0062-*.md:3 and its ## Amendment (2026-10-16) heading). The amendment allows one trigger line per plugin inside the shared GENERATED: plugin-conventions block of the root AGENTS.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.md Instruction economy). It keeps the developer-experience block as the shipped form.
  2. Write docs/conventions/setup-lifecycle/README.md as the owner doc: the managed block and its one-line-per-plugin ownership rule (from pointer-line.sh), the evidence gate, the check/apply verb set (pointing at docs/plugin-philosophy.md setup section, not restating it), and placeholders that name slices 2 to 4 (provenance, converge-by-state apply, current-facts check) as the sections they fill. No user-level ~/.config/<plugin>/ layer: ADR 0075 fix 9 retired the user-global file layer into userConfig.
  3. Add a row for it to the Convention registry in docs/plugin-philosophy.md (line 822 onward), and amend docs/conventions/config-cascade/README.md:297 to 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.md exits 0
  • grep -c 'GENERATED: plugin-conventions' docs/conventions/setup-lifecycle/README.md prints 1 or more
  • grep -c '^## Amendment (2026-10-24)' docs/adr/0075-*.md prints 1
  • grep -c 'nothing is always-loaded' docs/conventions/config-cascade/README.md prints 0
  • sed -n 3p docs/adr/0075-*.md contains amended 2026-10-24
  • grep -c 'setup-lifecycle/README.md' docs/plugin-philosophy.md prints 1 or more
  • bash scripts/check-conformance-registry.sh --check and bash scripts/check-adr-numbers.sh --check exit 0
  • ci-status is green on the PR head

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Oct 24, 2026
  2. github-actions commented on Oct 24, 2026

    @github-actions
    Contributor

    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.

  3. added
    priority: lowNice-to-have, cosmetic, or speculative; opportunistic.
    and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Oct 24, 2026
  4. added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    work-class: scopedA briefed fix or small feature; blast radius bounded by the brief, tests exist.
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.priority: lowNice-to-have, cosmetic, or speculative; opportunistic.status: readyTriaged, unblocked, and fully specified; eligible to pick up.work-class: scopedA briefed fix or small feature; blast radius bounded by the brief, tests exist.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions