Config location: docs convention file with a CLAUDE.md pointer as the default, .claude/ as an option #5606

Problem

The config-cascade convention (docs/conventions/config-cascade/README.md) puts every plugin's consumer config under .claude/<name> (user, team, local overlay). Plugins reference more than 30 distinct .claude/* files today (for example .claude/source-control.md, .claude/testing.yaml, .claude/topic-docs.yaml), each in its own format.

The owner's preference (2026-09-30): rules like these apply to other agents and tools too, and .claude/ is not a shared or reusable location (tools that write there hit edit restrictions, and other agents do not read it). The default a plugin ships should be:

• a prose convention doc under docs/conventions/<concern>.md (for example docs/conventions/testing.md) holding the rules;
• a CLAUDE.md or AGENTS.md pointer that loads it on demand ("if testing, read docs/conventions/testing.md"), per progressive disclosure;
• a structured file only where performance or readability needs one.

Both routes stay supported, and the location stays configurable per repository.

Constraint

Scripts and hooks cannot follow a CLAUDE.md pointer. The testing scanner and its test-scan hook run on every test-file write under a p95 budget of 150 ms on WSL, so they need a machine-readable block at a known path. A proposed form: the convention doc carries one fenced config block (same keys as today's file) that the script reads directly, with .claude/<name> accepted as a fallback. The read time must be measured inside the hook before adoption.

Scope

1. Extend the config-cascade contract with a location axis: a docs convention file with a pointer as the default, .claude/<name> as an option, and the resolution order between them.
2. Adopt it in the testing plugin first (.claude/testing.yaml → docs/conventions/testing.md with a fenced block), including a timing probe inside the hook and a migration note.
3. List the other plugins' .claude/* surfaces for later adoption; do not migrate them in the same change.

Acceptance

• The config-cascade contract names both locations and their precedence.
• The testing plugin reads its config from the docs convention file by default, still reads .claude/testing.yaml, and the test-scan hook stays within its latency budget with the new read (measured).
• New plugin work (Release 2b mutation scope docs(testing): plan Release 2b mutation scope #5603, Release 3 cleanup docs(testing): plan Release 3 cleanup, split mode and wave 2 #5604) adds no new .claude/* config file.

Related: #5575 (removing docs/topics and docs/specs), #5603, #5604.

🤖 Generated with Claude Code