Repository navigation
refactor(docs-naming): move the .claude/docs-naming.json settings to docs/conventions/docs-naming.yaml #9731
Description
Parent
Refs #5906
Depends on
- none: on the frontier now
Outcome
The docs-naming, docs-hygiene settings this repository keeps in .claude/docs-naming.json resolve from docs/conventions/docs-naming.yaml,
validated by a schema the plugin ships. The old location is read only when the YAML is absent, for one release.
The setup skill, if the plugin has one, writes the YAML.
Decisions
- ADR 0064 Decision 1: a plugin's team settings live in one
docs/conventions/<concern>.yaml, validated by a
JSON Schema atplugins/<plugin>/schemas/<concern>.schema.json(Decision 6), checked in CI by
scripts/check-convention-yaml.sh(Decision 7). Script readers use the shared readerlib/parse-concern-value.sh. - ADR 0075: layers are plugin default <
userConfig< team<home>/<concern>.yaml< personal
<home>/<concern>.local.<ext>; every resolver reports the layer that supplied each value. - Migrate per-skill .claude config files to userConfig, one conventions doc, or the cascade (ADR 0018) #5906 (comment 2026-10-04): each reader keeps reading the old file for one release when the new file is
absent, and this repository keeps its old file until the cleanup slice.
Key interfaces
- The docs-naming audit, gate generator and realign readers,
plugins/docs-naming/reference/config.md, docs-hygiene's readers,scripts/check-docs-naming.sh.
Done when
-
docs/conventions/docs-naming.yamlcarries every value of.claude/docs-naming.jsonandscripts/check-convention-yaml.sh --checkexits 0 againstplugins/docs-naming/schemas/docs-naming.schema.json. -
scripts/run-test-file.sh plugins/docs-naming/scripts/resolve-config.test.shexits 0. -
scripts/run-test-file.sh plugins/docs-naming/skills/setup/scripts/setup-apply.test.shexits 0. -
scripts/run-test-file.sh scripts/check-docs-naming.test.shexits 0. - The reader's tests include: the YAML wins when both exist, the old location is read when the YAML is absent, and the resolver names the layer that supplied each value.
- No skill body tells an agent to read or write the old location:
git grep -nfor it underplugins/docs-naming,plugins/docs-hygieneprints only compatibility-read code, its tests and changelog lines. - The PR body lists each migrated setting with its new home and schema.
-
scripts/check-changelog-fragments.sh --check-required origin/mainexits 0.
Out of scope
- Deleting this repository's old file or block (the cleanup slice under Migrate per-skill .claude config files to userConfig, one conventions doc, or the cascade (ADR 0018) #5906).
Activity
melodic-automation-lanes commentedon Oct 24, 2026
The work-resolve-issue lane stopped partway through this issue and needs a person.
Why, in the run's own words:
Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/40127088052
To retry, remove
needs-humanand addagent-readyagain.kyle-sexton commentedon Oct 26, 2026
Builder: the Automation Lanes session builds this from the owner's machine. The fix edits
.github/workflows, which the lanes App cannot push (patch-rules.json:3); that boundary stays. Its PR closes this issue.needs-humancame off under the owner's 2026-10-26 rule (a person only for an intent or vision change, an implementation finding that alters intent or the primary design, or a HIGH/CRITICAL security issue); none applies.agent-readystays off so the issue lane does not race the build.github-actions commentedon Oct 26, 2026
The triage sweep dispatched intake triage for this issue (attempt 2 of 2).
github-actions commentedon Oct 26, 2026
Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: none
Understood: move the docs-naming and docs-hygiene settings from
.claude/docs-naming.jsontodocs/conventions/docs-naming.yaml. A schema the plugin ships validates the YAML. Readers fall back to the old file for one release when the YAML is absent. The setup skill writes the YAML. Nothing is missing, since the outcome, the decisions and the done-when checks are explicit. I found no likely duplicates among the open issues. The earlier comments say the fix touches workflow paths and is being built from the owner's machine.Automated triage, applied by the lanes App.