Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs: add requirements section and hooks field warning

Affaan Mustafac9ef02ba42d2
diff --git a/.claude-plugin/PLUGIN_SCHEMA_NOTES.md b/.claude-plugin/PLUGIN_SCHEMA_NOTES.md
index 29959dcff..0483945ed 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 df1edd86c..2c1970eb5 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)