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.mdindex 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-PatternsThese 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 errorAvoid 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 Contributorsdiff --git a/README.md b/README.mdindex 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)