From c9ef02ba42d29385a4b20669665e231cc0f8b8cb Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Thu, 29 Jan 2026 00:46:05 -0800 Subject: [PATCH] docs: add requirements section and hooks field warning - Add minimum Claude Code version requirement (v2.1.0+) - Document hooks auto-loading behavior to prevent flip-flop cycles - Add flip-flop history table to PLUGIN_SCHEMA_NOTES.md - Reference issues #29, #52, #103 that were caused by this confusion - Explain that regression test now prevents reintroduction This documentation should prevent future confusion about whether to add/remove the hooks field from plugin.json. --- .claude-plugin/PLUGIN_SCHEMA_NOTES.md | 40 +++++++++++++++++++++++++++ README.md | 27 ++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/.claude-plugin/PLUGIN_SCHEMA_NOTES.md b/.claude-plugin/PLUGIN_SCHEMA_NOTES.md index 29959dc..0483945 100644 --- a/.claude-plugin/PLUGIN_SCHEMA_NOTES.md +++ b/.claude-plugin/PLUGIN_SCHEMA_NOTES.md @@ -118,6 +118,43 @@ Assume the validator is hostile and literal. --- +## The `hooks` Field: DO NOT ADD + +> ⚠️ **CRITICAL:** Do NOT add a `"hooks"` field to `plugin.json`. This is enforced by a regression test. + +### Why This Matters + +Claude Code v2.1+ **automatically loads** `hooks/hooks.json` from any installed plugin by convention. If you also declare it in `plugin.json`, you get: + +``` +Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file. +The standard hooks/hooks.json is loaded automatically, so manifest.hooks should +only reference additional hook files. +``` + +### The Flip-Flop History + +This has caused repeated fix/revert cycles in this repo: + +| Commit | Action | Trigger | +|--------|--------|---------| +| `22ad036` | ADD hooks | Users reported "hooks not loading" | +| `a7bc5f2` | REMOVE hooks | Users reported "duplicate hooks error" (#52) | +| `779085e` | ADD hooks | Users reported "agents not loading" (#88) | +| `e3a1306` | REMOVE hooks | Users reported "duplicate hooks error" (#103) | + +**Root cause:** Claude Code CLI changed behavior between versions: +- Pre-v2.1: Required explicit `hooks` declaration +- v2.1+: Auto-loads by convention, errors on duplicate + +### Current Rule (Enforced by Test) + +The test `plugin.json does NOT have explicit hooks declaration` in `tests/hooks/hooks.test.js` prevents this from being reintroduced. + +**If you're adding additional hook files** (not `hooks/hooks.json`), those CAN be declared. But the standard `hooks/hooks.json` must NOT be declared. + +--- + ## Known Anti-Patterns These look correct but are rejected: @@ -127,6 +164,7 @@ These look correct but are rejected: * Missing `version` * Relying on inferred paths * Assuming marketplace behavior matches local validation +* **Adding `"hooks": "./hooks/hooks.json"`** - auto-loaded by convention, causes duplicate error Avoid cleverness. Be explicit. @@ -148,6 +186,8 @@ Avoid cleverness. Be explicit. This structure has been validated against the Claude plugin validator. +**Important:** Notice there is NO `"hooks"` field. The `hooks/hooks.json` file is loaded automatically by convention. Adding it explicitly causes a duplicate error. + --- ## Recommendation for Contributors diff --git a/README.md b/README.md index df1edd8..2c1970e 100644 --- a/README.md +++ b/README.md @@ -244,6 +244,33 @@ See `skills/continuous-learning-v2/` for full documentation. --- +## Requirements + +### Claude Code CLI Version + +**Minimum version: v2.1.0 or later** + +This plugin requires Claude Code CLI v2.1.0+ due to changes in how the plugin system handles hooks. + +Check your version: +```bash +claude --version +``` + +### Important: Hooks Auto-Loading Behavior + +> ⚠️ **For Contributors:** Do NOT add a `"hooks"` field to `.claude-plugin/plugin.json`. This is enforced by a regression test. + +Claude Code v2.1+ **automatically loads** `hooks/hooks.json` from any installed plugin by convention. Explicitly declaring it in `plugin.json` causes a duplicate detection error: + +``` +Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file +``` + +**History:** This has caused repeated fix/revert cycles in this repo ([#29](https://github.com/affaan-m/everything-claude-code/issues/29), [#52](https://github.com/affaan-m/everything-claude-code/issues/52), [#103](https://github.com/affaan-m/everything-claude-code/issues/103)). The behavior changed between Claude Code versions, leading to confusion. We now have a regression test to prevent this from being reintroduced. + +--- + ## Installation ### Option 1: Install as Plugin (Recommended)