Current state
A developer who places a spec file at lua/config/plugins/my-plugin.lua instead of lua/config/plugins/specs/my-plugin.lua causes lazy.nvim to load it as a category file — the plugin loads, but without any category-level vim.opt settings or keymap context. There is no error or warning. CLAUDE.md describes the "two-tier registration" rule as a fact but does not explain the mechanism (why specs/ files are not auto-discovered) or the failure mode (what silent misbehavior results from the wrong placement). A developer following the add-new-plugin playbook and placing the file in the wrong layer would have no signal that anything went wrong.
Ideal state
- CLAUDE.md explains that lazy.nvim's
import = 'config.plugins' only loads .lua files directly in plugins/, not files in subdirectories; spec files are loaded only when explicitly require()d by a category file.
- CLAUDE.md explains that placing a spec file directly in
plugins/ causes it to be treated as a category file, so the plugin loads without category-level setup.
docs/playbooks/add-new-plugin.md includes a callout: "Spec files belong in lua/config/plugins/specs/ — placing one directly in plugins/ causes it to be treated as a category file."
Out of scope
- Changing how lazy.nvim discovers plugins.
- Restructuring the spec or category directories.
Starting points
CLAUDE.md — the "two-tier registration" section to extend with mechanism and failure modedocs/playbooks/add-new-plugin.md — where the placement warning should be added
QA plan
- Read
CLAUDE.md — expect a description of why spec files are not auto-discovered and what happens if one is placed at the category level.
- Read
docs/playbooks/add-new-plugin.md — expect a callout warning against placing spec files directly in plugins/.
- Confirm no spec files exist directly under
lua/config/plugins/ (all should be in subdirectories).
Done when
CLAUDE.md explains the consequence of placing a spec file at the category level, so a developer adding a plugin knows exactly where to put it and why.
Current state
A developer who places a spec file at
lua/config/plugins/my-plugin.luainstead oflua/config/plugins/specs/my-plugin.luacauses lazy.nvim to load it as a category file — the plugin loads, but without any category-levelvim.optsettings or keymap context. There is no error or warning. CLAUDE.md describes the "two-tier registration" rule as a fact but does not explain the mechanism (whyspecs/files are not auto-discovered) or the failure mode (what silent misbehavior results from the wrong placement). A developer following the add-new-plugin playbook and placing the file in the wrong layer would have no signal that anything went wrong.Ideal state
import = 'config.plugins'only loads.luafiles directly inplugins/, not files in subdirectories; spec files are loaded only when explicitlyrequire()d by a category file.plugins/causes it to be treated as a category file, so the plugin loads without category-level setup.docs/playbooks/add-new-plugin.mdincludes a callout: "Spec files belong inlua/config/plugins/specs/— placing one directly inplugins/causes it to be treated as a category file."Out of scope
Starting points
CLAUDE.md— the "two-tier registration" section to extend with mechanism and failure modedocs/playbooks/add-new-plugin.md— where the placement warning should be addedQA plan
CLAUDE.md— expect a description of why spec files are not auto-discovered and what happens if one is placed at the category level.docs/playbooks/add-new-plugin.md— expect a callout warning against placing spec files directly inplugins/.lua/config/plugins/(all should be in subdirectories).Done when
CLAUDE.md explains the consequence of placing a spec file at the category level, so a developer adding a plugin knows exactly where to put it and why.