diff --git a/.changes/ai-slop/docs-config-locations-68a16396.md b/.changes/ai-slop/docs-config-locations-68a16396.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/ai-slop/docs-config-locations-68a16396.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/attribution/docs-config-locations-5b4128d9.md b/.changes/attribution/docs-config-locations-5b4128d9.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/attribution/docs-config-locations-5b4128d9.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/bugs/docs-config-locations-739d7f23.md b/.changes/bugs/docs-config-locations-739d7f23.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/bugs/docs-config-locations-739d7f23.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/code-metrics/docs-config-locations-92638a9f.md b/.changes/code-metrics/docs-config-locations-92638a9f.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/code-metrics/docs-config-locations-92638a9f.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/codebase-health/docs-config-locations-79f8d46b.md b/.changes/codebase-health/docs-config-locations-79f8d46b.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/codebase-health/docs-config-locations-79f8d46b.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/discovery/docs-config-locations-50746568.md b/.changes/discovery/docs-config-locations-50746568.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/discovery/docs-config-locations-50746568.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/disk-hygiene/docs-config-locations-f11d0f1b.md b/.changes/disk-hygiene/docs-config-locations-f11d0f1b.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/disk-hygiene/docs-config-locations-f11d0f1b.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/docs-naming/docs-config-locations-584b7616.md b/.changes/docs-naming/docs-config-locations-584b7616.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/docs-naming/docs-config-locations-584b7616.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/harness-config/docs-config-locations-b3320463.md b/.changes/harness-config/docs-config-locations-b3320463.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/harness-config/docs-config-locations-b3320463.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/improvement/docs-config-locations-65215255.md b/.changes/improvement/docs-config-locations-65215255.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/improvement/docs-config-locations-65215255.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/instruction-placement/docs-config-locations-a3849406.md b/.changes/instruction-placement/docs-config-locations-a3849406.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/instruction-placement/docs-config-locations-a3849406.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/multi-agent/docs-config-locations-74199461.md b/.changes/multi-agent/docs-config-locations-74199461.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/multi-agent/docs-config-locations-74199461.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/mutation-testing/docs-config-locations-9c5b0b10.md b/.changes/mutation-testing/docs-config-locations-9c5b0b10.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/mutation-testing/docs-config-locations-9c5b0b10.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/overengineering/docs-config-locations-2d5f4636.md b/.changes/overengineering/docs-config-locations-2d5f4636.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/overengineering/docs-config-locations-2d5f4636.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/plugin-quality/docs-config-locations-17f7b5a2.md b/.changes/plugin-quality/docs-config-locations-17f7b5a2.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/plugin-quality/docs-config-locations-17f7b5a2.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/source-control/docs-config-locations-e40b32a8.md b/.changes/source-control/docs-config-locations-e40b32a8.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/source-control/docs-config-locations-e40b32a8.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/.changes/testing/docs-config-locations-18626a62.md b/.changes/testing/docs-config-locations-18626a62.md new file mode 100644 index 00000000000..04248064d57 --- /dev/null +++ b/.changes/testing/docs-config-locations-18626a62.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives. diff --git a/docs/contracts/commit-convention/README.md b/docs/contracts/commit-convention/README.md index 4c1b7bb390f..af3ed6101d5 100644 --- a/docs/contracts/commit-convention/README.md +++ b/docs/contracts/commit-convention/README.md @@ -1,4 +1,4 @@ -# Commit-convention enforcement seam +# Commit-convention enforcement contract Owner doc for the machine-readable **enforcement** read of a consumer's commit-subject / PR-title convention. This concern is consumed by **more than one plugin**: `source-control` @@ -17,12 +17,12 @@ Enforcement reads a key that file lacks from the folder-form file below. Draftin the folder-form file: the model resolves the YAML and the personal markdown layers in [`source-control/reference/config-resolution.md`](../../../plugins/source-control/reference/config-resolution.md). That document owns **drafting** resolution: how `/source-control:commit` and `/source-control:pull-request` -compose a compliant subject/title. This seam owns the **enforcement** resolution: how a +compose a compliant subject/title. This contract owns the **enforcement** resolution: how a zero-dependency hook decides whether an *already-formed* subject/title is allowed. The two reads are deliberately not identical: -| | Drafting (config-resolution.md) | Enforcement (this seam) | +| | Drafting (config-resolution.md) | Enforcement (this contract) | |---|---|---| | Reader | the model | a POSIX sh hook (`[[ =~ ]]` / `grep -E`) | | Layers read | user-global, team, local, per-key merge | **team-tracked**: `docs/conventions/source-control.yaml`, then the folder-form `docs/conventions/source-control/commit-convention.yml`; for `subject_pattern` only, and only where those set none, the git-ignored personal `docs/conventions/source-control.local.yaml`, never merged | @@ -59,6 +59,8 @@ name the file to change. it: an operator who wants `/source-control:commit` to draft to the same pattern also sets `## subject_pattern` in the drafting personal override, `.claude/source-control.local.md`. + A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../config-cascade/locations.md) says. + The folder-form file, and its fail-closed checks, are read only for a key the YAML lacks: a broken folder-form file never disables a key the YAML supplies. Each key holds exactly one value, never a list. @@ -82,7 +84,7 @@ name the file to change. ## The folder-form convention file `docs/conventions/source-control/commit-convention.yml` is a flat-scalar YAML file, the -tool-agnostic file any consumer (this seam's resolver, a commit-msg hook, CI, another agent) reads +tool-agnostic file any consumer (the enforcement resolver, a commit-msg hook, CI, another agent) reads with one sed. It is the path the org standards sync writes. Enforcement reads it only for a key `docs/conventions/source-control.yaml` lacks. @@ -115,7 +117,7 @@ Contract points: - **`dialect:`** (optional, default `posix-ere`) declares the regex dialect for non-enforcement consumers (a JS CI runner, a PCRE hook) so they know what they are reading instead of silently misreading it. Enforcement itself stays POSIX-ERE-only: a declared non-`posix-ere` dialect - disables this seam's enforcement with a diagnostic, exactly like a PCRE-ism in the pattern. + disables enforcement with a diagnostic, exactly like a PCRE-ism in the pattern. - **Fail closed.** A tracked file that is unreadable, carries a key with an empty value, or is a symlink or sits under a symlinked path segment whose physical target leaves the repository root (the target must be a regular file physically under the repo) disables enforcement with a @@ -165,6 +167,6 @@ purposes without it. `scripts/shared-copies.txt`, the commit-msg entry installs both as assets, and a change to either canonical carries a guardrails release so consumers receive it. -Naming coincidence recorded per the seam rules: the convention file is `docs/conventions/source-control.yaml`, named +Naming coincidence recorded per the shared-concern naming rules: the convention file is `docs/conventions/source-control.yaml`, named after the concern (delivery workflow), not the plugin. The plugin-name collision is incidental; the file is not renamed. diff --git a/docs/contracts/config-cascade/CHANGELOG.md b/docs/contracts/config-cascade/CHANGELOG.md index eb342ae99f3..dc604c20cf0 100644 --- a/docs/contracts/config-cascade/CHANGELOG.md +++ b/docs/contracts/config-cascade/CHANGELOG.md @@ -11,6 +11,10 @@ adding an optional layer or relaxing a rule additively is a minor bump. No contract change. +- **`locations.md` lists where plugin config lives.** One editable page of the four layers, the + `.local` naming and the paths outside the contract, pointing at this README's sections. Plugins + that teach a config location carry a generated copy at `reference/config-locations.md`. The + layering axis is unchanged, so `contract_version` stays. - **`plugin-quality` gets a `standards_repo` row.** A team-only key in `/plugin-quality.yaml` beside `verification`, read by the auditor agent; unset resolves no standards repository. - **`improvement` and the `architecture` `improve` object get Implementers rows.** `improvement` diff --git a/docs/contracts/config-cascade/README.md b/docs/contracts/config-cascade/README.md index dc7c5fdd422..85e2efd3e8d 100644 --- a/docs/contracts/config-cascade/README.md +++ b/docs/contracts/config-cascade/README.md @@ -10,7 +10,9 @@ surface has learned all of them. This directory is the source of truth: `README.md` (the contract), `CHANGELOG.md` (version history), and topic siblings such as [`consumer-gotchas.md`](consumer-gotchas.md) (concatenating consumer gotchas -for participating skills, #3547). +for participating skills, #3547). [`locations.md`](locations.md) is the one editable list of config +file locations; each plugin that teaches one carries a generated copy at +`reference/config-locations.md`. ## Boundary: this contract owns the axis, never the keys diff --git a/docs/contracts/config-cascade/locations.md b/docs/contracts/config-cascade/locations.md new file mode 100644 index 00000000000..e89217f0484 --- /dev/null +++ b/docs/contracts/config-cascade/locations.md @@ -0,0 +1,48 @@ +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/docs/contracts/finding-suppression/README.md b/docs/contracts/finding-suppression/README.md index dddb5de2011..d172a40b9e6 100644 --- a/docs/contracts/finding-suppression/README.md +++ b/docs/contracts/finding-suppression/README.md @@ -33,6 +33,8 @@ The consuming plugin names its own surface. The first adopter, `harness-config`' | 2 | team (tracked) | `/harness-config.yaml` (`` from the convention-home pointer line, default `docs/conventions`) | | 3 | personal override (gitignored) | `.claude/audit-pass.local.md` | +A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../config-cascade/locations.md) says. + In a YAML concern file the `suppressions` mapping sits at the root with the entry shape below; a reader that uses the shared YAML-subset parser needs the `"anchor/v1":` key quoted. diff --git a/docs/contracts/rendered-views/README.md b/docs/contracts/rendered-views/README.md index ac4ed623507..b07da3270e6 100644 --- a/docs/contracts/rendered-views/README.md +++ b/docs/contracts/rendered-views/README.md @@ -830,8 +830,8 @@ validation answer set). Fleet audits check those surfaces against this section. copies the state the user built out as text they can paste into the session or commit. For the author's version of this rule, see S2, section "Custom editing interfaces" ([source list](../../finding-your-unknowns.md#sources-and-citation-shape)). The doctrine -recurs three times independently in the corpus; it is what keeps a throwaway editor inside -the agent loop instead of becoming a dead end. +recurs three times independently in the corpus; without the control, the state a user +builds in a throwaway editor stays in the browser, so the session never sees it. **Who is bound.** Skills that emit interactive HTML artifacts cite this section. @@ -928,6 +928,8 @@ lane. A skill runs its `resolve` command and never reads the files itself. chain). Each lane registers once in the medium registry with its view kinds, whether it is hosted-capable, and its default. + A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../config-cascade/locations.md) says. + ## Template vendoring posture **Decision.** Do not vendor the 31 html-effectiveness corpus templates (20 gallery + diff --git a/docs/conventions/review-digest.md b/docs/conventions/review-digest.md index 5b3f90dfe45..d97f89dbaae 100644 --- a/docs/conventions/review-digest.md +++ b/docs/conventions/review-digest.md @@ -55,6 +55,8 @@ an earlier one key by key: the layer below. 3. personal override `.claude/review-digest.local.json` + A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../contracts/config-cascade/locations.md) says. + The result names the layer that supplied each value (`team :`, `user-global `, `personal-override `, or `default`). Quote glob values in the YAML file (`"**/hooks/**"`), since a plain `*` opens an alias. diff --git a/plugins/ai-slop/reference/config-locations.md b/plugins/ai-slop/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/ai-slop/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/ai-slop/skills/audit/SKILL.md b/plugins/ai-slop/skills/audit/SKILL.md index 341d91f2a5d..157be2f50c8 100644 --- a/plugins/ai-slop/skills/audit/SKILL.md +++ b/plugins/ai-slop/skills/audit/SKILL.md @@ -214,7 +214,9 @@ the fix flow, under [Non-repository targets](#non-repository-targets). - `plugins/` is not in scope; plugin content is audited in its own repository. - The detector's user config layer is the JSON file `$HOME/.claude/ai-slop.json`, even when `CLAUDE_CONFIG_DIR` is set; the team and personal layers are YAML. Its project layers come from - the session's project directory. + the session's project directory. The plugin still reads that JSON file until it migrates + ([#18004](https://github.com/melodic-software/claude-code-plugins/issues/18004)); then it moves + where [config locations](../../reference/config-locations.md) says. - A path target such as `~/.claude` covers every `*.md` beneath it. ### Non-repository targets diff --git a/plugins/attribution/README.md b/plugins/attribution/README.md index 294ff901723..64484325d63 100644 --- a/plugins/attribution/README.md +++ b/plugins/attribution/README.md @@ -20,7 +20,7 @@ A copied paragraph starts accurate and silently stops being accurate the next ti page changes. Nothing in the repository records that it drifted. Citing the source and fetching it at read time removes the drift risk entirely; where a surface must act on a volatile specific without the source, a stamped record (the surface's own decision in its own words, a pointer, an -as-of date, a recheck trigger) keeps it honest and re-checkable without copying the source. +as-of date, a recheck trigger) lets a reader tell when to recheck it, without copying the source. ## Skills @@ -94,7 +94,9 @@ call and routes to its finding-suppression convention, not to a marker this plug The audit detectors read `/attribution.yaml` and `/attribution.local.yaml`, `` being the bound convention home, else `docs/conventions`, over the user-global -`~/.claude/attribution.json`. The old JSON files of the same names under `.claude/` are not read; +`~/.claude/attribution.json` ([config locations](reference/config-locations.md) lists where plugin +config belongs; this user-global read is a declared deviation until it migrates). The old JSON files +of the same names under `.claude/` are not read; `/attribution:setup` reports them and carries their keys into the YAML, which it writes. In YAML, quote a glob that starts with `*` (`- "**/vendor/**"`); a file that does not parse is named on stderr and not read. The keys, layered over the shipped defaults, with their schema in diff --git a/plugins/attribution/reference/config-locations.md b/plugins/attribution/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/attribution/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/attribution/skills/audit/SKILL.md b/plugins/attribution/skills/audit/SKILL.md index 9cf400c9691..a690d3ff836 100644 --- a/plugins/attribution/skills/audit/SKILL.md +++ b/plugins/attribution/skills/audit/SKILL.md @@ -313,6 +313,8 @@ layer supplying every effective value. The accuracy dials (`nomination_passes`, tunable per repo; the gates bind fix eligibility and release readiness only, and never filter what the report shows. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + When `deep_research_on_exhaustion` is on and a research-capable skill is enabled, a budget-exhausted candidate may escalate to `/discovery:research` (if that plugin is enabled). When it is not enabled, the run says so once and takes the ordinary neutral disposition diff --git a/plugins/attribution/skills/setup/SKILL.md b/plugins/attribution/skills/setup/SKILL.md index ac2f882555b..3e2e628041d 100644 --- a/plugins/attribution/skills/setup/SKILL.md +++ b/plugins/attribution/skills/setup/SKILL.md @@ -94,6 +94,8 @@ an earlier one: | 2 | team | `//attribution.yaml` | the repository, tracked | | 3 | personal override | `//attribution.local.yaml` | one operator in one repo, gitignored | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + `apply` writes only the team layer and the personal override, never the user-global file. Before it writes the personal override, `git check-ignore -q "//attribution.local.yaml"` must exit 0; when it does not, say the file would be tracked and get the operator's choice before writing. diff --git a/plugins/bugs/reference/config-locations.md b/plugins/bugs/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/bugs/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/bugs/reference/config.md b/plugins/bugs/reference/config.md index 96b401fec85..515f3eb4f1f 100644 --- a/plugins/bugs/reference/config.md +++ b/plugins/bugs/reference/config.md @@ -18,6 +18,8 @@ Three layers, resolved in this order, where a later layer refines an earlier one | 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/docs/conventions/bugs.yaml` for the keys; `${CLAUDE_PROJECT_DIR}/docs/conventions/bugs.md` for prose and `## Gotchas` | must be tracked, the only layer teammates receive | | 3 | personal override | `${CLAUDE_PROJECT_DIR}/.claude/bugs.local.md` | must be gitignored, never staged | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + The team files sit in `docs/conventions/` whatever convention home the repository binds; a repository that binds another home still keeps them there. @@ -122,7 +124,9 @@ one entry were absent. Do not discard the whole layer. ## Consumer `.gitignore` -One recursive line covers the personal override here and every other cascade surface: +This recursive line ignores the personal override this plugin reads today, `.claude/bugs.local.md`. +A personal override at `` needs `/**/*.local.*` instead; see +[config locations](config-locations.md). ```gitignore .claude/**/*.local.* diff --git a/plugins/bugs/skills/setup/SKILL.md b/plugins/bugs/skills/setup/SKILL.md index d2493c838ae..1650f70172d 100644 --- a/plugins/bugs/skills/setup/SKILL.md +++ b/plugins/bugs/skills/setup/SKILL.md @@ -124,6 +124,8 @@ never written. already covered. 7. **Remind them to stage it.** The team file reaches teammates only once committed. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + Re-running `apply` when everything already matches changes nothing and reports "already configured". ## Output diff --git a/plugins/code-metrics/README.md b/plugins/code-metrics/README.md index 1f97e8b2c22..ebb69d447ef 100644 --- a/plugins/code-metrics/README.md +++ b/plugins/code-metrics/README.md @@ -88,6 +88,8 @@ and `enabled`. References ship with their provenance: cyclomatic 20 cites ISO/IE a documented YAML subset (block style, flow sequences of scalars, no flow mappings). Every key: `reference/config.md`; `/code-metrics:setup` writes the team layer and probes the collectors. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + ## The report Every audit prints one `code-metrics/v2` JSON document (`--json`) or its markdown rendering. The diff --git a/plugins/code-metrics/reference/config-locations.md b/plugins/code-metrics/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/code-metrics/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/code-metrics/reference/config.md b/plugins/code-metrics/reference/config.md index b41464b1e64..de0efa843ea 100644 --- a/plugins/code-metrics/reference/config.md +++ b/plugins/code-metrics/reference/config.md @@ -1,6 +1,6 @@ # The code-metrics configuration -Every tunable value in this plugin resolves through one consumer surface. This document is its +Every tunable value in this plugin resolves through one set of config layers. This document is their contract: the layers, the merge form, the YAML subset, and every key with its default and provenance. `/code-metrics:setup` writes the team layer; every audit skill reads the resolved document at run time and prints the layer that supplied any value a personal layer changed. The @@ -17,6 +17,8 @@ resolved in this order over the bundled defaults (`scripts/config-defaults.json` | 2 | team | `/docs/conventions/code-metrics.yaml` | the repository, tracked | | 3 | personal override | `/.claude/code-metrics.local.yaml` | one operator in one repository, gitignored | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + The team layer is `docs/conventions/code-metrics.yaml` alone. The team file earlier releases read from the repository's `.claude/` directory is retired and never read. `/code-metrics:setup check` reports it, and `/code-metrics:setup apply`, run while the docs file is absent, carries every diff --git a/plugins/code-metrics/skills/principles/reference/thresholds.md b/plugins/code-metrics/skills/principles/reference/thresholds.md index 89bcda045d2..1fe989252bb 100644 --- a/plugins/code-metrics/skills/principles/reference/thresholds.md +++ b/plugins/code-metrics/skills/principles/reference/thresholds.md @@ -94,6 +94,8 @@ rest of the defaults intact. The full key list is [`reference/config.md`](../../ that supplied any value a personal layer changed, so a number that differs from a teammate's is traceable to the layer that changed it rather than to the code. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../../reference/config-locations.md) says. + Setting a reference to `null` is a legitimate choice and turns the count off while the measure keeps reporting. Setting one to a value you can defend for your codebase is a better choice than adopting one of these because a standard prints it. diff --git a/plugins/code-metrics/skills/setup/SKILL.md b/plugins/code-metrics/skills/setup/SKILL.md index 9f21d0bc1e8..23ccfeac7e2 100644 --- a/plugins/code-metrics/skills/setup/SKILL.md +++ b/plugins/code-metrics/skills/setup/SKILL.md @@ -20,6 +20,8 @@ surface and for the external collectors the audits probe: `check` inspects and v persists, and neither installs anything. Keys, defaults, and provenance: `${CLAUDE_PLUGIN_ROOT}/reference/config.md`. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + Action routing: no argument or `check` runs the check; `apply` runs the check first, then persists. `apply` is non-interactive when complete `=` arguments are supplied (automation and headless use pass them and are never prompted); with none, it interviews one key diff --git a/plugins/codebase-health/README.md b/plugins/codebase-health/README.md index d256fa6665f..d2af1f273f8 100644 --- a/plugins/codebase-health/README.md +++ b/plugins/codebase-health/README.md @@ -58,6 +58,8 @@ it>)`, and any notice. A `terminal` result drops the offer. The tracked team fil new home; a `terminal` or `file` value in one still keeps the view local when no other setting decides, and a publishing value there is ignored. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + ## Configurable audit dimensions What the audit reads and how it verifies claims is **not baked in**. It comes from the consuming @@ -102,7 +104,7 @@ verified non-issue. Nothing project-specific is baked into the plugin. One `userConfig` option, `medium`: your own default for the rendered-view offer (default `auto`), read by the shared medium resolver above. Audit targets flow through the tracked -`.claude/codebase-health.md` config seam above (written by `/codebase-health:setup apply`). No +`.claude/codebase-health.md` config file above (written by `/codebase-health:setup apply`). No hooks, no MCP servers, no bundled scripts beyond the shared `lib/` copies (medium resolver, prerequisites check, verification reader), no network calls of its own (Phase 2 may use whatever documentation-research tools your setup provides). State: the audit reads and writes only the consumer's own files under the scope you give it. diff --git a/plugins/codebase-health/reference/config-locations.md b/plugins/codebase-health/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/codebase-health/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/codebase-health/skills/audit/SKILL.md b/plugins/codebase-health/skills/audit/SKILL.md index f774cb5e7a0..02b866afc2c 100644 --- a/plugins/codebase-health/skills/audit/SKILL.md +++ b/plugins/codebase-health/skills/audit/SKILL.md @@ -113,6 +113,8 @@ pass). Come from the consuming repo's tracked config, resolved additively across 2. `.claude/codebase-health.md` (team, tracked) 3. `.claude/codebase-health.local.md` (personal override, gitignored) + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + The four bundled dimensions are `documentation`, `configuration`, `code-quality`, and `architecture`; the config may tune their globs, remove a dimension, or add custom ones. diff --git a/plugins/codebase-health/skills/setup/SKILL.md b/plugins/codebase-health/skills/setup/SKILL.md index dfb76f27985..d179f6a3c51 100644 --- a/plugins/codebase-health/skills/setup/SKILL.md +++ b/plugins/codebase-health/skills/setup/SKILL.md @@ -25,6 +25,8 @@ earlier layer's and example-claims concatenate, **except** that a later layer de with empty source lists is an explicit opt-out that *removes* that inherited dimension. This skill writes only the **team** file; changes to the user-global layer or the personal override are the user's to make. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + ## `check` (read-only) Inspect the effective merged config and report a PASS/FAIL/INFO table with one remediation line per diff --git a/plugins/discovery/README.md b/plugins/discovery/README.md index 1ebc3caea75..8afccac4960 100644 --- a/plugins/discovery/README.md +++ b/plugins/discovery/README.md @@ -160,6 +160,10 @@ because a spawn's `model` takes an alias only ([sub-agents: choose a model](https://code.claude.com/docs/en/sub-agents#choose-a-model)). With no such layer, or without `multi-agent`, the pins apply. The rule: `reference/parent-contract.md`, "The worker's model is the parent's call". +The multi-agent plugin still reads `.claude/multi-agent.local.yaml` until it migrates +([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the file +moves where [config locations](reference/config-locations.md) says. + ### Options reference diff --git a/plugins/discovery/reference/config-locations.md b/plugins/discovery/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/discovery/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/disk-hygiene/README.md b/plugins/disk-hygiene/README.md index 734563524c6..5e82075bd0d 100644 --- a/plugins/disk-hygiene/README.md +++ b/plugins/disk-hygiene/README.md @@ -387,6 +387,8 @@ Without `--policy`, standing policy files layer over the baseline when present: `.claude/disk-hygiene.json`. An explicit `--policy` file is the invocation-specific choice and replaces both standing layers. The scan output records which sources applied. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + Candidate hints can be disabled or extended. Consumer protection globs are additive. A relative glob matches a path relative to the scan target. A glob that starts with `/`, a drive letter, or `\\` (a UNC path such as `\\server\share\keep\**`) matches the absolute path, so a standing overlay can protect a tree no matter which parent is scanned. An object `{glob, reason}` is accepted. For every entry that matches a path, the scan entry, the preview candidate, the handoff-verify verdict, and a skipped apply path list it under `protection_matches`, sorted and deduplicated, as `{glob}` or `{glob, reason}`. That field sits beside the `consumer-protected-path` reason and is absent when no entry matched. Hard safety predicates and the baseline protected-name/root rules are non-overridable by any layer: a policy file can only add protections, add hints, or disable discovery hints (which can only cause junk to diff --git a/plugins/disk-hygiene/reference/config-locations.md b/plugins/disk-hygiene/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/disk-hygiene/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/disk-hygiene/skills/clean/SKILL.md b/plugins/disk-hygiene/skills/clean/SKILL.md index 80f5bd5c9ea..8313ad3194c 100644 --- a/plugins/disk-hygiene/skills/clean/SKILL.md +++ b/plugins/disk-hygiene/skills/clean/SKILL.md @@ -233,6 +233,8 @@ and `elevation`; none can weaken hard guards. The [overlay schema](reference/pol lists every field; version 1 files load unchanged. The scan output names its `policy_sources` and the effective `elevation`. Scan errors and unvisited protected roots are coverage gaps, not clean. A hint's `entry_types` and the snapshot's `empty_directory_paths` are in [scan-flags.md](reference/scan-flags.md#coverage-and-hint-fields). +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + The scan output may also carry an `os_autoclean` advisory when the target overlaps a zone an OS mechanism (Windows Storage Sense, systemd-tmpfiles) should own. Surface its recommendation in the report; prefer enabling the OS mechanism over hand-cleaning that zone, mirroring the managed-state diff --git a/plugins/docs-naming/README.md b/plugins/docs-naming/README.md index 900d3ad686e..d723c58fbd6 100644 --- a/plugins/docs-naming/README.md +++ b/plugins/docs-naming/README.md @@ -51,6 +51,8 @@ into it. A user-global file still at the retired `docs-hygiene` name (`~/.claude/docs-hygiene.json`) is read, with a warning from the resolver; rename it to retire the warning. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + ## Renames are gated per file `realign-file-names` accepts one file at a time. The findings artifact does not diff --git a/plugins/docs-naming/reference/config-locations.md b/plugins/docs-naming/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/docs-naming/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/docs-naming/reference/config.md b/plugins/docs-naming/reference/config.md index 968cc1a88f9..0f6e4feaa0a 100644 --- a/plugins/docs-naming/reference/config.md +++ b/plugins/docs-naming/reference/config.md @@ -53,6 +53,8 @@ A user-global file absent under `docs-naming.json` but present under the retired stderr warning from `resolve` and a WARN row from `/docs-naming:setup check`. The new name wins when both exist. Rename the file to retire the warning. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + All three absent is a valid state: every key has a bundled default, and the defaults are this marketplace's own values, except `generated`, which is empty. The recommended gitignore line for the personal override is `/*.local.*`; `/docs-naming:setup check` reports a diff --git a/plugins/docs-naming/skills/setup/SKILL.md b/plugins/docs-naming/skills/setup/SKILL.md index 8f103d2ac6e..d8301ffe510 100644 --- a/plugins/docs-naming/skills/setup/SKILL.md +++ b/plugins/docs-naming/skills/setup/SKILL.md @@ -85,6 +85,8 @@ no cleanup, since neither file is read; the old-file rows name the next step. Th layer row reports it as WARN with the same remedy: rename it to `docs-naming.json` in the same directory. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + ## `apply` (idempotent) 1. Run `check` and read its table. diff --git a/plugins/harness-config/reference/config-locations.md b/plugins/harness-config/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/harness-config/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/harness-config/skills/setup/SKILL.md b/plugins/harness-config/skills/setup/SKILL.md index 96494ce0239..c574fda5d3a 100644 --- a/plugins/harness-config/skills/setup/SKILL.md +++ b/plugins/harness-config/skills/setup/SKILL.md @@ -127,6 +127,8 @@ tracked/ignored question has opposite correct answers per layer, so verify each - **personal override** `.claude/audit-pass.local.md`: must be gitignored and never staged. Staged or tracked is a FAIL: a personal deviation can reach team history. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + Parse each present layer and report as malformed any entry missing **any** of its five required keys: `check`, `claim`, `sites`, `reason`, `date`. Checking only `reason` and `date` would pass an entry that `audit-pass` itself rejects, so readiness would report green on configuration that cannot diff --git a/plugins/improvement/README.md b/plugins/improvement/README.md index 2736d33e7d1..777ca4d400b 100644 --- a/plugins/improvement/README.md +++ b/plugins/improvement/README.md @@ -45,13 +45,15 @@ churn analysis or declare Tier 2 MCP telemetry sources, run `/improvement:setup` the team `.claude/improvement.md`, then the gitignored `.claude/improvement.local.md` personal override. The key contract lives in [reference/config.md](reference/config.md). +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + ## Running it as a standing routine `/improvement:find`'s unattended mode implements the tech-debt-sweep routine shape: a scheduled run persists a ranked report and files top candidates as work items, with prioritization always human-gated. The recommended wrapper is a **weekly [Routine](https://code.claude.com/docs/en/routines)**. Each firing gets a fresh session, and the -routine's saved prompt is the tuning surface. Consult that docs page for current Routine +routine's saved prompt is where you tune it. Consult that docs page for current Routine capabilities and limits rather than relying on numbers written here. ### Prerequisite: the plugin must be loaded in the fired session diff --git a/plugins/improvement/reference/config-locations.md b/plugins/improvement/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/improvement/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/improvement/reference/config.md b/plugins/improvement/reference/config.md index 6b99d8c7442..aa1290b82f3 100644 --- a/plugins/improvement/reference/config.md +++ b/plugins/improvement/reference/config.md @@ -17,6 +17,8 @@ Three layers, resolved in this order, where a later layer refines an earlier one | 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/improvement.md` | must be tracked, the only layer teammates receive | | 3 | personal override | `${CLAUDE_PROJECT_DIR}/.claude/improvement.local.md` | must be gitignored, never staged | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + Resolution anchors at the repo root, `${CLAUDE_PROJECT_DIR}` when set and otherwise `git rev-parse --show-toplevel`, never at the CWD. Every layer that exists is read and merged; reading one layer and stopping is not resolution. A malformed layer degrades soft: surface the @@ -109,7 +111,9 @@ hard error and never a fabricated reading. ## Consumer `.gitignore` -One recursive line covers the personal override here and every other cascade surface: +This recursive line ignores the personal override this plugin reads today, +`.claude/improvement.local.md`. A personal override at `` needs `/**/*.local.*` +instead; see [config locations](config-locations.md). ```gitignore .claude/**/*.local.* diff --git a/plugins/improvement/skills/find/context/hotspots.md b/plugins/improvement/skills/find/context/hotspots.md index 6dca32fc186..8ffe89788f0 100644 --- a/plugins/improvement/skills/find/context/hotspots.md +++ b/plugins/improvement/skills/find/context/hotspots.md @@ -83,6 +83,8 @@ Step 1's `excludes` as one ERE, alternatives joined with `|`, from two sources: The scan asks nothing and writes no record; `/improvement:setup apply` offers to persist them as `churn_exclude` entries. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../../reference/config-locations.md) says. + All layers absent is a valid state. When item 2 resolves nothing while `churn_exclude_defaults` is on, record an evidence-gap line (format: unattended.md), e.g. `gap: churn exclusions — no mechanical files resolved from the repository — declare churn_exclude or run /improvement:setup apply`. diff --git a/plugins/improvement/skills/setup/SKILL.md b/plugins/improvement/skills/setup/SKILL.md index 2eb7935263d..286362416d6 100644 --- a/plugins/improvement/skills/setup/SKILL.md +++ b/plugins/improvement/skills/setup/SKILL.md @@ -34,6 +34,8 @@ skill writes only the **team** file; changes to the user-global layer or the per user's to make. Anchor every repo-relative read at the repo root (`${CLAUDE_PROJECT_DIR}` when set, otherwise `git rev-parse --show-toplevel`), never at the CWD. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + ## `check` (read-only) Inspect the effective merged config and report a PASS/FAIL/WARN/INFO table with one remediation line diff --git a/plugins/instruction-placement/reference/config-locations.md b/plugins/instruction-placement/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/instruction-placement/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/instruction-placement/reference/consumer-config.md b/plugins/instruction-placement/reference/consumer-config.md index abc646516ff..30a191965d8 100644 --- a/plugins/instruction-placement/reference/consumer-config.md +++ b/plugins/instruction-placement/reference/consumer-config.md @@ -35,6 +35,8 @@ Three layers, resolved in this order: | 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.md` | | 3 | personal override (gitignored) | `${CLAUDE_PROJECT_DIR}/.claude/instruction-placement.local.md` | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + **Merge form: per-key override**, declared here as the cascade convention requires. Entries merge per `finding_id`: a later layer's entry for one id wins for that id only, and every id it does not mention keeps the earlier layer's entry. Wholesale replacement is forbidden, because a layer @@ -116,7 +118,7 @@ Three obligations this plugin takes on top of the convention: writes it only on the operator's explicit yes, the same per-item gate that authorizes a move, reused for the decision to stop being asked. A skill that wrote one unprompted would record an acceptance nobody made. `instruction-placement:delta` and `instruction-placement:audit` never write - this surface at all; they only read it. + this file at all; they only read it. - **Visible, never silent.** Every run reports each suppressed finding with its reason, date, and contributing layer, and every entry that did *not* suppress: each `personal-only, not applied` and each malformed one. A scoped run reports what it examined: it evaluates only entries with a site in diff --git a/plugins/multi-agent/README.md b/plugins/multi-agent/README.md index 7b856721847..9b527f5792c 100644 --- a/plugins/multi-agent/README.md +++ b/plugins/multi-agent/README.md @@ -130,6 +130,10 @@ One configuration, layered user-global (`~/.claude/multi-agent.yaml`), team key. `/multi-agent:setup` writes any of the three. Keys, values and layering: [`reference/config.md`](reference/config.md). +This plugin still reads `~/.claude/multi-agent.yaml` and `.claude/multi-agent.local.yaml` until it +migrates ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the +files move where [config locations](reference/config-locations.md) says. + ## Requirements - **Bash 3.2 or later, awk and git.** The resolver parses the YAML subset with awk, so no diff --git a/plugins/multi-agent/reference/config-locations.md b/plugins/multi-agent/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/multi-agent/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/multi-agent/reference/config.md b/plugins/multi-agent/reference/config.md index ec63b234a9e..e684b0bb58d 100644 --- a/plugins/multi-agent/reference/config.md +++ b/plugins/multi-agent/reference/config.md @@ -15,6 +15,10 @@ this page owns the keys. | Team | `/multi-agent.yaml`, `` being the convention home the repository binds, else `docs/conventions` | | Personal override | `.claude/multi-agent.local.yaml` (gitignored) | +The resolver still reads the user-global and personal override paths above until it migrates +([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the files +move where [config locations](config-locations.md) says. + Later layers win per key. Team and personal override are read only when the root is a repository that is neither `$HOME` nor an ancestor of it (`lib/config-root.sh`). The team file is validated by diff --git a/plugins/multi-agent/skills/setup/SKILL.md b/plugins/multi-agent/skills/setup/SKILL.md index 9e1ad618ae1..2c32cde9004 100644 --- a/plugins/multi-agent/skills/setup/SKILL.md +++ b/plugins/multi-agent/skills/setup/SKILL.md @@ -17,6 +17,10 @@ bundled defaults apply. Keys, values, layer paths and the fan-out guard are defined in [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](${CLAUDE_PLUGIN_ROOT}/reference/config.md). +This plugin still reads `~/.claude/multi-agent.yaml` and `.claude/multi-agent.local.yaml` until it +migrates ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the +files move where [config locations](../../reference/config-locations.md) says. + No argument means `check`. It installs nothing; the resolver needs only Bash, awk and git. diff --git a/plugins/mutation-testing/reference/config-locations.md b/plugins/mutation-testing/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/mutation-testing/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/mutation-testing/skills/audit/context/suppression.md b/plugins/mutation-testing/skills/audit/context/suppression.md index f555bb5c0a4..87dab032d69 100644 --- a/plugins/mutation-testing/skills/audit/context/suppression.md +++ b/plugins/mutation-testing/skills/audit/context/suppression.md @@ -80,6 +80,8 @@ So `.claude/mutation-testing-arid.local.md` is a **draft** file. Describing it a the config" is wrong in exactly the direction that matters. The config's later layers do take effect, and this record's do not. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../../reference/config-locations.md) says. + ## Obligations this skill must meet 1. **Resolve layers per the cascade**: anchor at the repo root, read every layer that exists, merge diff --git a/plugins/mutation-testing/skills/setup/SKILL.md b/plugins/mutation-testing/skills/setup/SKILL.md index e641ae9a619..e8b98cb12db 100644 --- a/plugins/mutation-testing/skills/setup/SKILL.md +++ b/plugins/mutation-testing/skills/setup/SKILL.md @@ -28,6 +28,8 @@ The config resolves across three layers, lowest first: the user layer (`userConf `${CLAUDE_PLUGIN_ROOT}/schemas/mutation-testing.schema.json`) → personal override (`.claude/mutation-testing.local.md`), later layers overriding scalars and unioning lists. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + The team file of earlier releases, .claude/mutation-testing.md, is retired and never read as a layer. While it exists, `check` probe 6 reports it as INFO, which gates nothing, naming `apply` as the move, or, once the YAML file exists, deleting it; `apply` step 7 carries its keys over. diff --git a/plugins/overengineering/reference/config-locations.md b/plugins/overengineering/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/overengineering/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/overengineering/reference/consumer-config.md b/plugins/overengineering/reference/consumer-config.md index f4b96ecf770..56982dbce87 100644 --- a/plugins/overengineering/reference/consumer-config.md +++ b/plugins/overengineering/reference/consumer-config.md @@ -31,6 +31,8 @@ Three layers, resolved in this order: | 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/overengineering.md` | | 3 | personal override (gitignored) | `${CLAUDE_PROJECT_DIR}/.claude/overengineering.local.md` | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + **Merge form: per-key override**, declared here as the cascade convention requires. The values are scalars and closed mappings, where concatenation is meaningless: a later layer replaces an earlier layer's value key by key, a key absent from a later layer keeps the earlier value, and wholesale diff --git a/plugins/plugin-quality/reference/config-locations.md b/plugins/plugin-quality/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/plugin-quality/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/plugin-quality/reference/config.md b/plugins/plugin-quality/reference/config.md index aacf7a7d0c4..7c5c83849c8 100644 --- a/plugins/plugin-quality/reference/config.md +++ b/plugins/plugin-quality/reference/config.md @@ -30,6 +30,8 @@ layer and **no personal override channel**; the old layers are retired, each wit | personal override | `.claude/plugin-quality.local.md` | record `plugin-quality-r002` (delete). Never read; setup `check` WARNs while it exists rather than silently ignoring it. | | user-global | `~/.claude/plugin-quality.md` | machine scope, outside the retirement manifest by contract. Never read; setup `check` WARNs in prose when it exists. | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + ## Resolution order 1. The convention home resolves (resolver exit 0) and `/plugin-quality/README.md` exists → @@ -79,7 +81,7 @@ Two keys live outside the topic doc, in `/plugin-quality.yaml`, checked ag | Key | Values | Default | Meaning | |---|---|---|---| -| `verification`, `verification_skills.` | `off`, `light`, `standard`, `strict` | `light` | Whether `/plugin-quality:audit` runs its adversarial re-examination seam. `standard` keeps the `high`-effort gate; `strict` runs it at every effort; `light` and `off` skip it at every effort and label the findings `unverified`. A skill entry beats the plugin value ([verification level](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)). | +| `verification`, `verification_skills.` | `off`, `light`, `standard`, `strict` | `light` | Whether `/plugin-quality:audit` runs its adversarial re-examination step. `standard` keeps the `high`-effort gate; `strict` runs it at every effort; `light` and `off` skip it at every effort and label the findings `unverified`. A skill entry beats the plugin value ([verification level](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)). | ## Sink resolution ladder (step 6 of the audit) diff --git a/plugins/plugin-quality/skills/setup/SKILL.md b/plugins/plugin-quality/skills/setup/SKILL.md index 9944f16053c..5befaa1c650 100644 --- a/plugins/plugin-quality/skills/setup/SKILL.md +++ b/plugins/plugin-quality/skills/setup/SKILL.md @@ -79,6 +79,8 @@ against that contract rather than restating it. 6. **Sink reachability**. For the effective sink: `gh-issues` → covered by step 1; `markdown-dir` → the directory exists and is writable; `local-fallback` → nothing to check. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + ## `apply` (writes the pointer region + topic doc, on explicit request) Converge, in order, each write individually gated on operator confirmation: diff --git a/plugins/source-control/README.md b/plugins/source-control/README.md index 9a8d4484067..00a2b970814 100644 --- a/plugins/source-control/README.md +++ b/plugins/source-control/README.md @@ -376,6 +376,8 @@ see [hooks: WorktreeRemove](https://code.claude.com/docs/en/hooks#worktreeremove rules. Defaults (Conventional Commits, squash merge) apply only when the project declares nothing. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + ## Requirements - **shfmt v3.14.1 or later**, which the PR-linkage and worktree gates read commands through. diff --git a/plugins/source-control/reference/config-locations.md b/plugins/source-control/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/source-control/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/source-control/reference/config-resolution.md b/plugins/source-control/reference/config-resolution.md index aa959fcc77d..fe10e683c94 100644 --- a/plugins/source-control/reference/config-resolution.md +++ b/plugins/source-control/reference/config-resolution.md @@ -744,6 +744,8 @@ Layers, in resolution order, where a later layer refines an earlier one: 3. **`${REPO_ROOT}/.claude/source-control.local.md`**: personal override, gitignored. A per-machine or per-operator deviation from team policy, never committed. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says. + Each layer is optional, and **fall-through is per key, not per file**. A key absent from every layer is unresolved even when some layer exists: a user-global file contributing only `trailer_policy` leaves `subject_pattern` as unresolved as no file at all. Each unresolved key falls through diff --git a/plugins/source-control/skills/commit/SKILL.md b/plugins/source-control/skills/commit/SKILL.md index 004a75ab7cc..1f6909aeaac 100644 --- a/plugins/source-control/skills/commit/SKILL.md +++ b/plugins/source-control/skills/commit/SKILL.md @@ -14,6 +14,8 @@ metadata: Exec-bit backstop: !`bash "${CLAUDE_PLUGIN_ROOT}/skills/commit/scripts/exec-bit-check.sh" --probe 2>/dev/null || echo "unavailable — run the check manually"` Config layer (user-global): !`test -f "$HOME/.claude/source-control.md" && echo present || echo absent` +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + ## Repository context. Gather first Collect these with **individual** Bash calls, one command per call, never combined into a single diff --git a/plugins/source-control/skills/commit/reference/config-probes.md b/plugins/source-control/skills/commit/reference/config-probes.md index f3ef8ba62da..55d83a0116c 100644 --- a/plugins/source-control/skills/commit/reference/config-probes.md +++ b/plugins/source-control/skills/commit/reference/config-probes.md @@ -53,3 +53,5 @@ substitutes the root at all. This matches the root-resolution requirement [`config-resolution.md`](../../../reference/config-resolution.md) already states for resolution itself; the probes must not disagree with it. `exec-bit-check.sh` anchors itself the same way. + +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../../reference/config-locations.md) says. diff --git a/plugins/source-control/skills/setup/SKILL.md b/plugins/source-control/skills/setup/SKILL.md index 0a70f80e987..5745108e9e4 100644 --- a/plugins/source-control/skills/setup/SKILL.md +++ b/plugins/source-control/skills/setup/SKILL.md @@ -128,6 +128,8 @@ Per-layer verdicts: remediations, so probe them separately. See the two-probe form under `apply`. Absent file is OK once the ignore rule itself is present. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + **FAIL** when the *effective* `subject_pattern` is not machine-checkable. It must be either the literal keyword `Conventional Commits` or an anchored regex (`^…`-style); a plain-language description cannot be evaluated by `/source-control:commit` or `/source-control:pull-request`. Name the layer that supplied the diff --git a/plugins/source-control/skills/setup/reference/apply-convention.md b/plugins/source-control/skills/setup/reference/apply-convention.md index d2ee7250e8b..de8bb19ea94 100644 --- a/plugins/source-control/skills/setup/reference/apply-convention.md +++ b/plugins/source-control/skills/setup/reference/apply-convention.md @@ -39,6 +39,8 @@ absent, since a convention is a team artifact until someone says otherwise. | `team` (default) | `REPO_ROOT/docs/conventions/source-control.yaml` | the shared, tracked convention | | `local` | `REPO_ROOT/.claude/source-control.local.md` | a personal deviation from team policy here | +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../../reference/config-locations.md) says. + The team layer is YAML, validated by `plugins/source-control/schemas/source-control.schema.json` ([config-resolution.md](../../../reference/config-resolution.md), "The config files"). The user and local layers stay markdown, one `## ` section per key. The retired team file diff --git a/plugins/testing/README.md b/plugins/testing/README.md index 834fbe29aff..710b0f7e9f2 100644 --- a/plugins/testing/README.md +++ b/plugins/testing/README.md @@ -98,7 +98,9 @@ installed and enabled, and otherwise reports `judge pass not run: testing plugin not installed or not enabled`. The calibration cases and raters are in `skills/audit/evals/judge-calibration/`. `/testing:run-e2e` reads these optional keys only when it drives the app itself; a run through `/app-control:drive` takes its tools from the control skill. `recording` (`video | gif | off`, default `off`) and -`browser_mode` (`headed | headless`, default `headless`) live on `.claude/testing/e2e.md`. +`browser_mode` (`headed | headless`, default `headless`) live on `.claude/testing/e2e.md`, which +this plugin reads until it migrates; then the file moves where +[config locations](reference/config-locations.md) says. `e2e_driver` (`auto | harness | run | playwright | chrome`) and `reuse_running_instance` (`auto | true | false`), both default `auto`, live in `docs/conventions/testing.yaml`, its personal layers, or the `userConfig` options below; `scripts/resolve-config.sh e2e` resolves them and names @@ -139,6 +141,8 @@ lower it: the lowest valid value wins, a raise is reported as ignored, and an in named and dropped. A testing release without this key stops its test scan on `pixel_tolerance` in `testing.yaml`, so add the map once every member runs this release. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says. + `verification` (`off | light | standard | strict`, default `light`) and `verification_skills` (per-skill levels; an entry beats `verification`) set whether `/testing:cleanup`'s Cannot-fail-only mode dispatches its fresh-context skeptic: under `light` and `off` it dispatches none and deletes nothing. @@ -166,7 +170,8 @@ machine that runs this release. Its `worst-case` action also reads an optional `.claude/testing/worst-case.md`, after the bundled catalog in `run-e2e/context/worst-case.md`: the project's own worst-case values, field limits and -data formats, read as data. The action renders a target with that data, reverts what it injected +data formats, read as data. It reads that path until the plugin migrates; then the file moves where +[config locations](reference/config-locations.md) says. The action renders a target with that data, reverts what it injected (proven with `cmp` snapshots), and reports what breaks without editing component code. `/testing:audit` and the `test-weaken` hook read the testing config through the same cascade @@ -179,8 +184,8 @@ The team layer is `docs/conventions/testing.yaml`, validated by takes, plus the two run-e2e keys above. Without it, the team layer is the `yaml config` block in `docs/conventions/testing.md` (read for one more release), else `/.claude/testing.yaml`. The first of the three present wins, and the resolver prints one warning for each other one present. -The prose testing rules stay in `docs/conventions/testing.md`. The user-global and -`.claude/testing.local.yaml` layers do not change. +The prose testing rules stay in `docs/conventions/testing.md`. This release still reads the +user-global and `.claude/testing.local.yaml` layers at those paths. #### Move the team layer to `docs/conventions/testing.yaml` @@ -191,8 +196,10 @@ The prose testing rules stay in `docs/conventions/testing.md`. The user-global a 3. Once every member runs this release, delete the old block or file. Until then every run prints a warning naming both; an older release keeps reading the old one. -`~/.claude/testing.yaml` and `.claude/testing.local.yaml` stay where they are; only the team layer -moves. Reading the block costs the same as reading the file; the measured p50 and p95 are in the +This release moves only the team layer. It still reads `~/.claude/testing.yaml` and +`.claude/testing.local.yaml`; keep them there until the plugin migrates +([#17999](https://github.com/melodic-software/claude-code-plugins/issues/17999)), then move them +where [config locations](reference/config-locations.md) says. Reading the block costs the same as reading the file; the measured p50 and p95 are in the [latency probes](https://github.com/melodic-software/claude-code-plugins/blob/927a5305d238874ce006eaad6b3fa5c3cb07ebc1/docs/specs/tautological-tests/probes.md#team-layer-location-docs-block-or-claudetestingyaml-wsl2), and `plugins/testing/scripts/time-config.sh` reproduces them. diff --git a/plugins/testing/reference/config-locations.md b/plugins/testing/reference/config-locations.md new file mode 100644 index 00000000000..0d0e2a16653 --- /dev/null +++ b/plugins/testing/reference/config-locations.md @@ -0,0 +1,51 @@ + + +# Where plugin config lives + +The one editable list of config file locations for this marketplace's plugins. Each plugin that +teaches a location carries a generated copy at `reference/config-locations.md`; edit +`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md) +owns the rules; this page points at them. + +## The four layers + +Lowest first, a higher layer refining a lower one key by key +([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)): + +1. **Plugin default**: bundled in the plugin. +2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person, + across repositories. +3. **Team**: `/.yaml` for keyed values, `/.md` for prose, tracked + ([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). +4. **Personal override**: `/.local.`, gitignored by one + `/**/*.local.*` line + ([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)). + +`` is the repository's convention home, bound by the pointer region in `AGENTS.md` or +`CLAUDE.md`, default `docs/conventions` +([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). +`` is the plugin's name, or a cross-plugin convention's name. + +## Not a plugin config location + +- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/`. +- **No new `.claude/` file for plugin config.** Write new team and personal files at ``. +- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`, + `.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`. +- **Machine-scope plugin state** under `~/.claude/` is outside it too + ([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)). + +## A plugin that still reads an old path + +Some plugins still read `~/.claude/` or `.claude/.local.`. Those reads keep +working until each plugin migrates in its own change; they are not locations to copy. + +A tracked `.claude/` team file is still a supported team-layer location, read only when no +`` file supplies the layer +([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)). + +A plugin's own docs name what it reads today; the contract's +[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers) +table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations) +section list each one. diff --git a/plugins/testing/skills/check-visual-parity/SKILL.md b/plugins/testing/skills/check-visual-parity/SKILL.md index 5ec61638fd3..e0012ff06d4 100644 --- a/plugins/testing/skills/check-visual-parity/SKILL.md +++ b/plugins/testing/skills/check-visual-parity/SKILL.md @@ -92,6 +92,8 @@ The user-global `~/.claude/testing.yaml`, the personal override `.claude/testing (`source=personal-override`) and the plugin option can only lower the team value. The script reports a raise as ignored, and names an invalid layer and drops it. Quote a `reason` that holds a colon followed by a space. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + A tolerance above 0 is used only with its recorded reason; never pass a higher `--tolerance` than this line gives. To keep a known baseline mismatch under tolerance, the team records a `pixel_tolerance` map with the pixel count and a reason in `docs/conventions/testing.yaml`; this diff --git a/plugins/testing/skills/run-e2e/SKILL.md b/plugins/testing/skills/run-e2e/SKILL.md index 4c799619d2f..a1099504748 100644 --- a/plugins/testing/skills/run-e2e/SKILL.md +++ b/plugins/testing/skills/run-e2e/SKILL.md @@ -142,6 +142,11 @@ A legacy testing-format map (`.claude/skills/feature-map/SKILL.md`, or the direc not read. Warn that it is present and name `/app-control:map refresh `, which converts it; the run continues. +This plugin still reads `.claude/testing.local.yaml` and reports `.claude/skills/feature-map/SKILL.md` +as retired; until the plugin migrates, keep config where this page says it is read, then move it +where [config locations](../../reference/config-locations.md) says. The control skill's +`.claude/skills/control-/` is a Claude Code project skill, not plugin config. + ### Entry points The touched features are the `features` list of `affected.json`. Drive every entry point each one @@ -348,7 +353,9 @@ zoom, dark and right-to-left environments, and report. Before injecting a file a it, save `git diff HEAD` and `git status --porcelain --untracked-files=all --ignored` outside the tree and compare each pair with `cmp`; a difference ends the run degraded. Outside a git checkout, or with no mockable boundary, nothing is injected and every finding is labeled inferred. The -consumer file `.claude/testing/worst-case.md` extends the catalog and is read as data. The action +consumer file `.claude/testing/worst-case.md` extends the catalog and is read as data; this plugin +reads it there until it migrates, then it moves where +[config locations](../../reference/config-locations.md) says. The action edits no component code; fixes go to the user. It always takes own driving and skips Step 1: `/app-control:drive` injects no data. diff --git a/plugins/testing/skills/run-e2e/context/e2e-config.md b/plugins/testing/skills/run-e2e/context/e2e-config.md index 8baab98e108..976aeb2a942 100644 --- a/plugins/testing/skills/run-e2e/context/e2e-config.md +++ b/plugins/testing/skills/run-e2e/context/e2e-config.md @@ -13,6 +13,8 @@ visible, who drives, and whether it drives an app already running. The keys live `~/.claude/testing.yaml`, and personal override `.claude/testing.local.yaml`; per user, the plugin `userConfig` options of the same names. `scripts/resolve-config.sh e2e` resolves them. + This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../../reference/config-locations.md) says. + All five keys govern only this skill's own driving ([own-driving.md](own-driving.md)). When a run goes through `/app-control:drive` (SKILL.md Step 1), the app's control skill, which `/app-control:map create` writes, supplies the driver, the reuse of a running instance and the diff --git a/plugins/testing/skills/setup/SKILL.md b/plugins/testing/skills/setup/SKILL.md index f95b75c63bb..23efb5439c0 100644 --- a/plugins/testing/skills/setup/SKILL.md +++ b/plugins/testing/skills/setup/SKILL.md @@ -28,6 +28,8 @@ with `*` must be single-quoted. `docs/conventions/testing.yaml` also holds `/tes `map_report_order`, `file_findings` and `file_findings_floor`, and `/testing:write`'s `tdd_refactor_step` and `first_test`, which the scan ignores. +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + The keys: ```yaml diff --git a/plugins/testing/skills/write/SKILL.md b/plugins/testing/skills/write/SKILL.md index 17a2f4fdbbe..29a744e39ce 100644 --- a/plugins/testing/skills/write/SKILL.md +++ b/plugins/testing/skills/write/SKILL.md @@ -59,6 +59,8 @@ and again in the final summary: Settings: tdd_refactor_step=on (default), first_test=user-flow (docs/conventions/testing.yaml) ``` +This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../../reference/config-locations.md) says. + [context/write.md](context/write.md) says what each value changes: the Refactor step and its `Refactor checkpoint:` lines, and which test comes first. diff --git a/scripts/cross-plugin-source-registry.txt b/scripts/cross-plugin-source-registry.txt index 1579bea67f5..42188a786de 100644 --- a/scripts/cross-plugin-source-registry.txt +++ b/scripts/cross-plugin-source-registry.txt @@ -875,3 +875,11 @@ lib/cli-version-check.mjs # Dedicated check: scripts/sync-shared-copies.sh --check. Cluster line for the # duplication audit: the root canonical and the copies. lib/cli-version-check.mjs -> plugins/*/lib/cli-version-check.mjs + +# Dedicated check: scripts/sync-shared-copies.sh --check. Canonical: +# docs/contracts/config-cascade/locations.md. +reference/config-locations.md + +# Dedicated check: scripts/sync-shared-copies.sh --check. Cluster line for the +# duplication audit: the canonical contract and the copies. +docs/contracts/config-cascade/locations.md -> plugins/*/reference/config-locations.md diff --git a/scripts/shared-copies.txt b/scripts/shared-copies.txt index 304adb3b1c8..795c6fd8d40 100644 --- a/scripts/shared-copies.txt +++ b/scripts/shared-copies.txt @@ -1008,3 +1008,20 @@ lib/lane-instance-collision-check.md plugins/work-items/skills/work-loop/referen lib/cli-version-check.mjs plugins/context7/lib/cli-version-check.mjs lib/cli-version-check.mjs plugins/firecrawl/lib/cli-version-check.mjs lib/cli-version-check.mjs plugins/playwright/lib/cli-version-check.mjs +docs/contracts/config-cascade/locations.md plugins/ai-slop/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/attribution/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/bugs/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/code-metrics/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/codebase-health/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/discovery/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/disk-hygiene/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/docs-naming/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/harness-config/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/improvement/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/instruction-placement/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/multi-agent/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/mutation-testing/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/overengineering/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/plugin-quality/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/source-control/reference/config-locations.md +docs/contracts/config-cascade/locations.md plugins/testing/reference/config-locations.md