wip: [01-stabilize] paused at task 1/1 - OCR Hallucination Immune logic via Semantic delta window and fret-isolation
This commit is contained in:
@@ -0,0 +1,220 @@
|
||||
# Plugin Manifest Schema Notes
|
||||
|
||||
This document captures **undocumented but enforced constraints** of the Claude Code plugin manifest validator.
|
||||
|
||||
These rules are based on real installation failures, validator behavior, and comparison with known working plugins.
|
||||
They exist to prevent silent breakage and repeated regressions.
|
||||
|
||||
If you edit `.claude-plugin/plugin.json`, read this first.
|
||||
|
||||
---
|
||||
|
||||
## Summary (Read This First)
|
||||
|
||||
The Claude plugin manifest validator is **strict and opinionated**.
|
||||
It enforces rules that are not fully documented in public schema references.
|
||||
|
||||
The most common failure mode is:
|
||||
|
||||
> The manifest looks reasonable, but the validator rejects it with vague errors like
|
||||
> `agents: Invalid input`
|
||||
|
||||
This document explains why.
|
||||
|
||||
---
|
||||
|
||||
## Required Fields
|
||||
|
||||
### `version` (MANDATORY)
|
||||
|
||||
The `version` field is required by the validator even if omitted from some examples.
|
||||
|
||||
If missing, installation may fail during marketplace install or CLI validation.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Field Shape Rules
|
||||
|
||||
The following fields **must always be arrays**:
|
||||
|
||||
* `agents`
|
||||
* `commands`
|
||||
* `skills`
|
||||
* `hooks` (if present)
|
||||
|
||||
Even if there is only one entry, **strings are not accepted**.
|
||||
|
||||
### Invalid
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": "./agents"
|
||||
}
|
||||
```
|
||||
|
||||
### Valid
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": ["./agents/planner.md"]
|
||||
}
|
||||
```
|
||||
|
||||
This applies consistently across all component path fields.
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution Rules (Critical)
|
||||
|
||||
### Agents MUST use explicit file paths
|
||||
|
||||
The validator **does not accept directory paths for `agents`**.
|
||||
|
||||
Even the following will fail:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": ["./agents/"]
|
||||
}
|
||||
```
|
||||
|
||||
Instead, you must enumerate agent files explicitly:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": [
|
||||
"./agents/planner.md",
|
||||
"./agents/architect.md",
|
||||
"./agents/code-reviewer.md"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This is the most common source of validation errors.
|
||||
|
||||
### Commands and Skills
|
||||
|
||||
* `commands` and `skills` accept directory paths **only when wrapped in arrays**
|
||||
* Explicit file paths are safest and most future-proof
|
||||
|
||||
---
|
||||
|
||||
## Validator Behavior Notes
|
||||
|
||||
* `claude plugin validate` is stricter than some marketplace previews
|
||||
* Validation may pass locally but fail during install if paths are ambiguous
|
||||
* Errors are often generic (`Invalid input`) and do not indicate root cause
|
||||
* Cross-platform installs (especially Windows) are less forgiving of path assumptions
|
||||
|
||||
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:
|
||||
|
||||
* String values instead of arrays
|
||||
* Arrays of directories for `agents`
|
||||
* 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.
|
||||
|
||||
---
|
||||
|
||||
## Minimal Known-Good Example
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.1.0",
|
||||
"agents": [
|
||||
"./agents/planner.md",
|
||||
"./agents/code-reviewer.md"
|
||||
],
|
||||
"commands": ["./commands/"],
|
||||
"skills": ["./skills/"]
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
Before submitting changes that touch `plugin.json`:
|
||||
|
||||
1. Use explicit file paths for agents
|
||||
2. Ensure all component fields are arrays
|
||||
3. Include a `version`
|
||||
4. Run:
|
||||
|
||||
```bash
|
||||
claude plugin validate .claude-plugin/plugin.json
|
||||
```
|
||||
|
||||
If in doubt, choose verbosity over convenience.
|
||||
|
||||
---
|
||||
|
||||
## Why This File Exists
|
||||
|
||||
This repository is widely forked and used as a reference implementation.
|
||||
|
||||
Documenting validator quirks here:
|
||||
|
||||
* Prevents repeated issues
|
||||
* Reduces contributor frustration
|
||||
* Preserves plugin stability as the ecosystem evolves
|
||||
|
||||
If the validator changes, update this document first.
|
||||
17
.agent/knowledge/everything_claude/.claude-plugin/README.md
Normal file
17
.agent/knowledge/everything_claude/.claude-plugin/README.md
Normal file
@@ -0,0 +1,17 @@
|
||||
### Plugin Manifest Gotchas
|
||||
|
||||
If you plan to edit `.claude-plugin/plugin.json`, be aware that the Claude plugin validator enforces several **undocumented but strict constraints** that can cause installs to fail with vague errors (for example, `agents: Invalid input`). In particular, component fields must be arrays, `agents` must use explicit file paths rather than directories, and a `version` field is required for reliable validation and installation.
|
||||
|
||||
These constraints are not obvious from public examples and have caused repeated installation failures in the past. They are documented in detail in `.claude-plugin/PLUGIN_SCHEMA_NOTES.md`, which should be reviewed before making any changes to the plugin manifest.
|
||||
|
||||
### Custom Endpoints and Gateways
|
||||
|
||||
ECC does not override Claude Code transport settings. If Claude Code is configured to run through an official LLM gateway or a compatible custom endpoint, the plugin continues to work because hooks, commands, and skills execute locally after the CLI starts successfully.
|
||||
|
||||
Use Claude Code's own environment/configuration for transport selection, for example:
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://your-gateway.example.com
|
||||
export ANTHROPIC_AUTH_TOKEN=your-token
|
||||
claude
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
|
||||
"name": "everything-claude-code",
|
||||
"description": "Battle-tested Claude Code configurations from an Anthropic hackathon winner — agents, skills, hooks, commands, and rules evolved over 10+ months of intensive daily use",
|
||||
"owner": {
|
||||
"name": "Affaan Mustafa",
|
||||
"email": "me@affaanmustafa.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Battle-tested Claude Code configurations from an Anthropic hackathon winner"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "everything-claude-code",
|
||||
"source": "./",
|
||||
"description": "The most comprehensive Claude Code plugin — 14+ agents, 56+ skills, 33+ commands, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
|
||||
"version": "1.9.0",
|
||||
"author": {
|
||||
"name": "Affaan Mustafa",
|
||||
"email": "me@affaanmustafa.com"
|
||||
},
|
||||
"homepage": "https://github.com/affaan-m/everything-claude-code",
|
||||
"repository": "https://github.com/affaan-m/everything-claude-code",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"agents",
|
||||
"skills",
|
||||
"hooks",
|
||||
"commands",
|
||||
"tdd",
|
||||
"code-review",
|
||||
"security",
|
||||
"best-practices"
|
||||
],
|
||||
"category": "workflow",
|
||||
"tags": [
|
||||
"agents",
|
||||
"skills",
|
||||
"hooks",
|
||||
"commands",
|
||||
"tdd",
|
||||
"code-review",
|
||||
"security",
|
||||
"best-practices"
|
||||
],
|
||||
"strict": false
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"name": "everything-claude-code",
|
||||
"version": "1.9.0",
|
||||
"description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, and rules evolved over 10+ months of intensive daily use",
|
||||
"author": {
|
||||
"name": "Affaan Mustafa",
|
||||
"url": "https://x.com/affaanmustafa"
|
||||
},
|
||||
"homepage": "https://github.com/affaan-m/everything-claude-code",
|
||||
"repository": "https://github.com/affaan-m/everything-claude-code",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
"agents",
|
||||
"skills",
|
||||
"hooks",
|
||||
"rules",
|
||||
"tdd",
|
||||
"code-review",
|
||||
"security",
|
||||
"workflow",
|
||||
"automation",
|
||||
"best-practices"
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user