Skip to content

docs(config-cascade): one editable list of config locations, cited where docs teach them - #18015

Merged
kyle-sexton merged 10 commits into
mainfrom
docs/config-locations
Nov 21, 2026
Merged

kyle-sexton merged 10 commits into
mainfrom
docs/config-locations

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

No related issue: config-location docs cleanup from the external-agents plan; the follow-up resolver issues are listed under Related.

Summary

Problem: docs across the marketplace taught ~/.claude/<name> and .claude/*.local as places for plugin config, which the config-cascade contract does not define. Intent: "I don't want you or future agents to be confused by that"

  • Adds docs/contracts/config-cascade/locations.md, the one editable list of config locations.
  • The 17 plugins whose docs teach a config location (multi-agent and ai-slop included) now carry a generated reference/config-locations.md copy, checked by the shared-copies sync gate.
  • Old-path teaching in docs is replaced with a pointer: keep config where the plugin reads it today until that plugin migrates, then move it where the list says.

Fix

  • New locations.md (layers, homes, .local naming) that points to the contract README's sections, and says a tracked .claude/<name> team file is still a supported fallback.
  • scripts/shared-copies.txt registers one copy per citing plugin; no copy is uncited.
  • Docs that described old paths now say which paths the plugin still reads and cite that plugin's resolver issue. The resolvers themselves are not changed here.
  • scripts/cross-plugin-source-registry.txt gets the block the pre-push cross-plugin-source-drift check requires.

Verification

  • bash scripts/sync-shared-copies.sh --check exits 0 on the branch (1022 copies).
  • The old-path docs grep returns only classified hits: Claude Code's own config, evals, code, historical records, data files, deviation records, or accurate current-behavior docs that carry the pointer.
  • Pre-push hooks passed on each push.
  • Left out: the resolver code changes (tracked by the issues below).

Acceptance criteria

  • AC11: docs/contracts/config-cascade/locations.md is the one editable source of config locations; every plugin that teaches config locations carries a generated reference/config-locations.md checked by the sync gate; no doc in claude-code-plugins teaches ~/.claude/<name> or .claude/*.local for non-Claude config; one issue exists per resolver still reading old paths.

Related

Resolver issues (search gh issue list -R melodic-software/claude-code-plugins --search "config path in:title" --state open returned no existing match before filing). Each requires a dual-read window, so no setting in an old file is dropped:

Not in scope: ~/.claude/ecosystems/<ecosystem>.yaml (plugins/review/agents/ecosystem-specialist.md) and ~/.claude/standards/ (plugins/review/reference/standards-contract.md) belong to the ecosystem-commands and standards contracts, not the config cascade, so they get no pointer here. The review-digest paths (#18006) appear in no review-plugin doc.

Sibling plugin work: external-agents plugin, #17954.

🤖 Generated with Claude Code

https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak

kyle-sexton and others added 4 commits November 21, 2026 12:04
docs/contracts/config-cascade/locations.md lists the four layers, the
.local naming and the paths outside the contract, pointing at the README
sections. Every plugin the old-path docs grep hit carries a generated
copy at reference/config-locations.md through the sync gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak
Each doc that names a ~/.claude/<name> or .claude/<name>.local.* path
for plugin config keeps the fact (its resolver still reads or retires
that path) and gains one pointer to the plugin's
reference/config-locations.md, or to the canonical page from docs/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak
…fig belongs

The pointer now states that the plugin still reads, or reports as
retired, the .claude/ paths beside it, and that new config goes where
the config locations page says, so a skill-text resolver keeps reading
its current path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak
…ites them

The 39 plugins whose docs cite no reference/config-locations.md lose
the generated copy, its registry line and its changelog fragment. The
15 remaining copies are registered as one cross-plugin cluster.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 21, 2026 19:01
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-21T19:03:23.846429Z 1d043e0 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1d043e02a4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

… migrates

The pointer sentence told readers to put new config where config
locations says, but the resolvers still read their old paths (for
example code-metrics' personal override), so following it silently
dropped the setting. Say to keep config where the page says it is read
until the plugin migrates, then move it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs

Run 44938718351, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44938718351

Failed GitHub API calls

No failed call recorded by the run job's scripts.

Lane-Activity: pr-refine/fix-docs
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/apply-patch

Run 44938718351, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed 8a47bad
Run 44938718351

Failed GitHub API calls

No failed call recorded by the run job's scripts.

…ware/claude-code-plugins into docs/config-locations
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 41cba8878fc82675cf32c37873efeeb56271477a: read 88 of 88 changed file(s); 0 finding(s), 0 as inline comments.

Chunk 1 of 2 (40 files)

Security review, chunk 1 of 2 (PR #18015)

I found no security issues in this chunk. This lane already reviewed an earlier head (blocking only: yes), so this review reports only CRITICAL and IMPORTANT findings.

Scope. I read every hunk of the 40 files in .claude-lane/chunks/chunk-1.patch. identical.txt lists two groups of copies, and I read the first file of each:

  • .changes/ai-slop/docs-config-locations-68a16396.md
  • plugins/ai-slop/reference/config-locations.md

The copies sit at changelog-fragment paths (.changes/<plugin>/…) and plugin docs paths (plugins/<name>/reference/config-locations.md). Neither is a hook, workflow, settings or manifest path, so a copy's location doesn't change what its content does.

What changed. Every change in this chunk is Markdown about where plugin config lives:

  • New page: docs/contracts/config-cascade/locations.md and its generated copy.
  • Pointer sentences: each one says a plugin still reads its old .claude/ or ~/.claude/ paths until it migrates, and links to the new page.
  • Wording changes: "seam" becomes "contract" or "file" in commit-convention/README.md, codebase-health/README.md and instruction-placement/reference/consumer-config.md.
  • .gitignore notes: the notes in bugs and improvement reference/config.md are now scoped to the plugin's own .claude/<name>.local.md.

No code, resolver, hook, workflow, manifest or permission changes.

Instruction-surface lens. Several changed files are skill bodies (*/skills/*/SKILL.md, skills/*/context/*.md) or contract docs. I checked each for removed or softened rules:

  • Every change adds a pointer sentence or rewords prose. None removes or narrows a rule.
  • The fail-closed rules for commit-convention enforcement are unchanged. So are the gitignore and check-ignore requirements in attribution/skills/setup and harness-config/skills/setup, and the guards in disk-hygiene/skills/clean.
  • The .gitignore wording in bugs and improvement is now more accurate: it no longer claims that one line protects personal overrides kept at <home>. The gitignore block itself is unchanged.

No protected-class rule is removed, so I didn't need the instruction exception register.

Trust controls and manifests. No file in this chunk is a trust control, merge-hold path, workflow, action or plugin manifest. There are no userConfig, hooks, mcpServers or dependencies changes, so there are no manifest lines.

Settled threads and prior findings. Every settled thread is marked lines changed since resolution: no, and I re-raise none of them. The lane's only prior post is an unanchored summary with 0 findings, so there is nothing to repeat.

Embedded text. I found no directives aimed at the review lane in the diff or the PR context.

Spend. None. This chunk changes no lane, schedule, model or billing setting.

Chunk 2 of 2 (16 files)

Security review: chunk 2 of 2 (PR #18015, head 41cba88)

I found no security issues in this chunk. This lane already reviewed an earlier head (blocking only: yes), so the review was blocking only: it would have reported only CRITICAL and IMPORTANT findings.

Scope. I read every hunk of the 16 files in .claude-lane/chunks/chunk-2.patch:

  • plugin-quality: reference/config.md and skills/setup/SKILL.md
  • six source-control docs and skill bodies
  • seven testing README, skill and context files
  • scripts/cross-plugin-source-registry.txt and scripts/shared-copies.txt

Every change is Markdown or a text registry line about where plugin config lives. The diff touches no script, workflow, hook, manifest or trust control.

What changed.

  • Pointer sentence. Each doc gains the same sentence: the plugin still reads, or reports as retired, the named .claude/ paths, so keep config there until the plugin migrates, then move it to the place the config-locations list names.
  • Testing docs. The testing README and run-e2e SKILL.md now name the exact .claude/ files the plugin still reads, with tracking issue testing: read config from the config-cascade layers, not ~/.claude #17999. They also say that .claude/skills/control-<app>/ is a Claude Code project skill, not plugin config.
  • Shared-copies registry. scripts/shared-copies.txt registers 17 copies of docs/contracts/config-cascade/locations.md under plugins/*/reference/config-locations.md.
  • Cross-plugin registry. scripts/cross-plugin-source-registry.txt adds the matching drift-check block.

These registries feed only the sync and drift checks. They gate no trust decision.

Instruction-surface lens. I read the skill-body changes for removed or softened rules before applying the skip gate:

  • testing README. The line "the user-global and .claude/testing.local.yaml layers do not change" became "this release still reads … at those paths". That restates current resolver behavior and removes no check.
  • run-e2e worst-case consumer file. It is still "read as data", and the cmp snapshot and no-component-edit rules are unchanged.
  • source-control and plugin-quality docs. These only add a pointer. No gating, confirmation or write-gate text is removed, and apply writes stay "individually gated on operator confirmation".

No protected-class rule is removed or narrowed, so I did not need the instruction exception register.

Identical copies. The generated plugins/*/reference/config-locations.md copies sit at docs paths, and the .changes/<plugin>/docs-config-locations-*.md fragments are changelog entries. Neither path type changes what the content does.

Trust controls and manifests. No file in this chunk matches a trust-control or merge-hold path. No plugin.json or marketplace.json changes, so this chunk has no manifest lines.

Settled threads and prior findings.

  • The settled threads on plugins/testing/README.md and plugins/testing/skills/run-e2e/SKILL.md are marked lines changed since resolution: no. The current text matches the owner's stated fixes, so nothing is raised again.
  • The lane's only prior post is an unanchored summary with 0 findings, so there is nothing to repeat.

Embedded text. I found no directives aimed at the review lane in the diff or the PR context.

Spend. None. This chunk changes no lane, schedule, model or billing setting.

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 6 inline finding(s) on 8a47bad560918023791babe35806fd9f9a01453c; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment thread plugins/bugs/reference/config.md Resolved
Comment thread plugins/discovery/README.md Resolved
Comment thread plugins/testing/skills/run-e2e/SKILL.md Resolved
Comment thread plugins/testing/README.md Resolved
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 41cba8878fc82675cf32c37873efeeb56271477a: read 88 of 88 changed file(s); 0 finding(s), 0 as inline comments.

Chunk 1 of 2 (40 files)

Code review, chunk 1 of 2 (blocking only)

Blocking only. This lane already reviewed three earlier heads of this PR (8a47bad, 23aa8b3, bbbaf55), so this review reports only blocking findings.

Scope. I read all 40 files in chunk-1.patch, from start to end. The two first paths in identical.txt, .changes/ai-slop/… and plugins/ai-slop/reference/config-locations.md, are read in full. Their copies are 16 .changes/<plugin>/docs-config-locations-*.md changelog fragments and 16 generated plugins/<plugin>/reference/config-locations.md pages. None of those copy paths is a hook, workflow, settings or manifest path, so every copy behaves like its original.

Result: no blocking findings.

  • locations.md matches the contract on these points:
    • the four layers
    • .local naming
    • the supported .claude/<name> team fallback (README L84-L114)
    • the "edit docs/contracts/config-cascade/locations.md, never a copy" line
  • I checked the relative link of every new pointer against its file's depth: reference/ (README), config-locations.md (inside reference/), ../../reference/ (skills), ../../../reference/ (skills/*/context and skills/*/reference), and ../config-cascade/ and ../contracts/config-cascade/ (repo docs). Each one resolves to a generated copy that this PR adds for that plugin, or to the canonical page.
  • The .gitignore sentences in bugs and improvement stay scoped to that plugin's .claude/<name>.local.md, as the settled thread asked.
  • The "seam" → "contract" and wording edits in commit-convention, rendered-views, attribution, improvement, code-metrics, codebase-health and instruction-placement change no rule.

Settled threads and prior findings. Every settled thread is marked lines changed since resolution: no, and I re-raised none. Every prior finding is marked lines changed since posted: yes and was fixed by bbbaf55, so nothing is posted again.

PR context. There is no closing issue. AC11 comes from the PR body, and nothing in this chunk goes against it. The author says sync-shared-copies.sh --check passes; that is their claim, and I did not run it. I found no embedded instructions in the PR context, the settled threads or the prior findings.

Loosened checks. The prompt had no loosened_check_verdict:, loosened_check_patterns: or loosened_check_decision_record: lines. So I used verdict fail with no consumer entries, and did not check the decision-record citation requirement. Loosened checks would be marked: fail (default; no layers supplied); patterns: 0. This chunk changes only docs and loosens no check.

Plugin manifests. This chunk changes no plugin.json or marketplace.json. Each changelog fragment declares bump: patch, which fits a docs-only change.

Spend: none (docs only).

Uncovered rules (1)
  • Uncovered rule: a doc that calls a read a "declared deviation" should point to an entry in the contract's Deviations section. plugins/attribution/README.md:97-99 calls the ~/.claude/attribution.json read "a declared deviation", but Deviations has no attribution entry, and the Implementers table rates attribution implements (L794). This review is blocking only, so it is not posted as a finding.

Verifier dropped 0 of 0 candidates.

Chunk 2 of 2 (16 files)

Code review, chunk 2 of 2 (blocking only)

No blocking findings in this chunk. This lane has already reviewed 3 earlier heads of this PR, so this review reports blocking findings only.

What I checked. I read all 16 files in this chunk: the plugin-quality, source-control and testing docs, plus scripts/shared-copies.txt and scripts/cross-plugin-source-registry.txt.

  • Docs. Each change adds a pointer sentence that links to that plugin's reference/config-locations.md.
    • The relative link depth is right for every location: config-locations.md, ../../reference/ and ../../../reference/.
    • Each linked copy is one of the generated files listed in identical.txt for plugin-quality, source-control and testing.
    • Pointers placed inside numbered or bulleted list items (plugin-quality setup step 6, source-control config-resolution.md layer 3, e2e-config.md) keep the item's indentation, so the list numbering doesn't break.
  • Registries.
    • shared-copies.txt adds 17 canonical copy lines in the existing format. They match the 17 copies in identical.txt.
    • The cross-plugin-source-registry.txt block follows the same pattern as the lib/cli-version-check.mjs entries above it (L879-L885).

Settled threads and prior findings. The testing README and run-e2e/SKILL.md points the owner resolved at bbbaf55 are all marked lines changed since resolution: no. The text at this head matches what the owner's replies describe, so nothing is raised again.

PR context. There is no closing issue. AC11 comes from the PR body, and nothing in this chunk goes against it. The author says sync-shared-copies.sh --check passes. I did not run it, so that claim is unverified. I found no embedded instructions in the PR context, the settled threads or the prior findings.

Loosened checks. The prompt had no loosened_check_verdict:, loosened_check_patterns: or loosened_check_decision_record: lines. So I used verdict fail with no consumer entries, and did not check the decision-record citation requirement. Loosened checks would be marked: fail (default; no layers supplied); patterns: 0. This chunk changes only docs and registry lists, and loosens no check.

Plugin manifests. This chunk changes no plugin.json or marketplace.json.

Spend: none (docs only).

Verifier dropped 0 of 0 candidates.

critical-findings: 0

Uncovered rules (1)
  • Uncovered rule: A doc that calls a read a "declared deviation" should point to an entry in the config-cascade contract's Deviations section (plugins/attribution/README.md:97-99).

…ch old-path pointer

- bugs, improvement config.md: scope the .claude/**/*.local.* line to the plugin's own override and name <home>/**/*.local.* for the rest
- locations.md: keep the tracked .claude/<name> team file as a supported fallback, as the contract does
- locations.md: name the canonical file by path so each generated copy reads correctly
- discovery README: say the multi-agent plugin reads .claude/multi-agent.local.yaml (#17998), not discovery
- run-e2e SKILL.md: name the two old paths and say the control skill path is a Claude Code project skill
- testing README, run-e2e SKILL.md: say e2e.md, worst-case.md and the user-global and local layers are still read, then point to config locations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on 23aa8b336b32a03383d13c70a29e67405bbb4f6a; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment thread plugins/testing/skills/run-e2e/SKILL.md Resolved
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 21, 2026
@github-actions

Copy link
Copy Markdown
Contributor

The pr-verify verifier failed head bbbaf55f76f2a15d77af781e78e5dce5d0beb40b. What it wrote, as data:

What it wrote (32 lines)
Summary: The spec is PR #18015's own trusted body, since no issue is linked. Its AC11 has four
  parts: one editable locations.md, a generated reference/config-locations.md copy in every plugin
  that teaches config locations, no doc teaching ~/.claude/<name> or .claude/*.local for non-Claude
  config, and one issue per resolver. Most of it is delivered: locations.md exists and uses absolute
  links. The 15 copies match it byte for byte under the generated header and are registered in
  scripts/shared-copies.txt and scripts/cross-plugin-source-registry.txt. Every relative link in the
  pointer sentences that I checked resolves, and every CI job that covers the change concluded
  success
  (https://github.com/melodic-software/claude-code-plugins/actions/runs/44941510408/job/136959923292
  and the sibling Test, Lint and Check jobs). AC11 still looks incomplete. The PR's own review
  comment (author's reply on discovery/README.md) says plugins/multi-agent/README.md:127-129 names
  `.claude/multi-agent.local.yaml`, and multi-agent has its own resolver issue (#17998). Yet the
  diff gives multi-agent no copy and no pointer. ai-slop (#18004) and review (#18006) also have
  resolver issues but get neither. The diff also rewords some prose outside the spec
  ('seam'/'surface'/'tuning surface' replaced in commit-convention, code-metrics, codebase-health,
  instruction-placement, plugin-quality and improvement docs, and one sentence each in
  rendered-views and attribution README). That rewording is harmless and does not block. No binary
  files, secrets, takeover-set or workflow changes, and no steering text found.
- plugins/multi-agent/README.md: per the PR's own review reply (lines 127-129) this README names
  `.claude/multi-agent.local.yaml`, which the plugin still reads (#17998), but the diff adds no
  pointer there. AC11 needs every plugin that teaches a config location to carry the copy. Add
  plugins/multi-agent/reference/config-locations.md, register it in scripts/shared-copies.txt, add
  the 'still reads … config locations' pointer next to each old-path mention, and add a
  .changes/multi-agent/ fragment.
- plugins/ai-slop: this plugin has a resolver issue for an old config path (#18004) but gets no
  reference/config-locations.md copy and no pointer. If its docs name a ~/.claude/ or
  .claude/*.local path, add the copy, the shared-copies.txt line, the pointer and a
  .changes/ai-slop/ fragment. If they name none, the copy is not needed.
- plugins/review: the review-digest resolver issue (#18006) means this plugin still reads
  `.claude/review-digest.local.json`. Only docs/conventions/review-digest.md got a pointer. If any
  doc under plugins/review names that path, add the copy, the shared-copies.txt line, the pointer
  and a .changes/review/ fragment.

This pull request leaves the merge queue, and ci-status holds it out while it carries pr-verify-failed. A pr-verify pass removes the label, at a new commit or at this same head: once a trusted person edits the body, and only trusted people have edited it since the fail, this head is judged again, so a fail on the body or the issues it links needs only the body fixed, no new commit.

@github-actions github-actions Bot added the pr-verify-failed pr-verify failed this head; a pass at a new commit, or after a trusted body edit, removes it. label Nov 21, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 21, 2026
kyle-sexton and others added 2 commits November 21, 2026 15:16
…config locations

- multi-agent README, reference/config.md, setup SKILL.md: say the plugin still reads ~/.claude/multi-agent.yaml and .claude/multi-agent.local.yaml (#17998), then point to config locations
- ai-slop audit SKILL.md: say the plugin still reads $HOME/.claude/ai-slop.json (#18004), then point to config locations
- add the generated reference/config-locations.md copy, its shared-copies line and a changelog fragment to both plugins

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmfSVU9f2by5nqbM3Ak
@github-actions github-actions Bot removed the pr-verify-failed pr-verify failed this head; a pass at a new commit, or after a trusted body edit, removes it. label Nov 21, 2026
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 21, 2026
Merged via the queue into main with commit b4b2dd7 Nov 21, 2026
86 of 87 checks passed
@kyle-sexton
kyle-sexton deleted the docs/config-locations branch November 21, 2026 20:47
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant