diff --git a/CLAUDE.md b/CLAUDE.md index f13b192..e98d792 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,101 +1,54 @@ -# Working Principles — Karpathy 4 Rules - -These 4 rules — distilled from Andrej Karpathy's Jan 26, 2026 observations on LLM coding failure modes — are the working contract for **every agent** in this workspace (main Claude, subagents, teammates, MCP-launched runs). Read them before doing anything. They override generic "be helpful" defaults. - -**The four failure modes Karpathy named:** -1. Models make wrong assumptions silently → **Rule 1: Think Before Coding** -2. Models overcomplicate / bloat → **Rule 2: Simplicity First** -3. Models touch code outside the request → **Rule 3: Surgical Changes** -4. Models claim "done" without verification → **Rule 4: Goal-Driven Execution** - -Every subagent spawned via `Agent`/`Task`/teammate tools inherits this CLAUDE.md and is bound by these rules. If you delegate, restate the rules in the prompt so the spawned agent cannot miss them. - ---- - -## 1. Think Before Coding - -Don't assume. Don't hide confusion. Surface tradeoffs. - -Before implementing: -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them — don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. - -## 2. Simplicity First - -Minimum code that solves the problem. Nothing speculative. -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. - -Ask: "Would a senior engineer say this is overcomplicated?" If yes, simplify. - -## 3. Surgical Changes - -Touch only what you must. Clean up only your own mess. - -When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, mention it — don't delete it. - -The test: every changed line should trace directly to the user's request. - -## 4. Goal-Driven Execution - -Define success criteria. Loop until verified. - -Transform tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" - ---- - # svrnty-hermes-webui-plugin -**Classification:** Svrnty plugin for `nesquena/hermes-webui` (per `hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md`). +**Classification:** Svrnty plugin for `nesquena/hermes-webui` (per `hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md`) +*Inherits Karpathy 4 rules from `~/.claude/CLAUDE.md` — read them before coding.* -## What this repo is +## What this is -THE single repo holding every Svrnty modification to hermes-webui: backend routes, brand skin (CSS/JS/fonts), assets, tests. Loaded at runtime via the plugin loader hook patched into the fork (ONE permanent fork commit). Replaces: -- `hermes-ext/` (deprecated — brand skin migrates in) +THE single repo holding every Svrnty modification to hermes-webui: backend routes, brand skin (CSS/JS/fonts), assets, tests. Loaded at runtime via the plugin loader hook patched into the fork (ONE permanent fork commit). + +**Replaces:** +- `hermes-ext/` (deprecated — brand skin migrating in) - 4 prior fork commits in `hermes-webui/api/` (deprecated — migrated to `routes/`) -## Hard rules (inherits CLAUDE.md above + protocol) +## Hard rules -- ONLY interact with hermes-webui via the public extension API: `api.register_route` · `api.register_static` · `api.inject_script` · `api.inject_stylesheet` · `api.config_get` · `api.logger` -- Any other upstream import goes in `CONNECTION-MAP.md` under **forced internal dependencies** with a written justification + risk -- CONNECTION-MAP.md is **AST-generated**, never hand-edited -- Every PR regenerates CONNECTION-MAP.md (CI enforces) +- ONLY interact with hermes-webui via the public extension API: `api.register_route` · `api.register_static` · `api.inject_script` · `api.inject_stylesheet` · `api.config_get` · `api.logger` · `api.register_audio_attachment_processor` +- Any other upstream import → `CONNECTION-MAP.md` under **forced internal dependencies** with written justification + risk +- `CONNECTION-MAP.md` is **AST-generated**, never hand-edited +- Every PR regenerates `CONNECTION-MAP.md` (CI enforces) - Secrets via credctl / env only — never in repo, never on argv, never in logs - Plugin code = stateless wrappers; state lives in upstream (or in upstream-managed `state.db`) ## Structure ``` -plugin.py # entry: register(api) wires everything -routes/.py # one file per /api/ endpoint +plugin.py # entry: register(api) wires everything +routes/.py # one file per /api/ endpoint static/{app.js,app.css,fonts/} # brand skin (subsumes hermes-ext) -CONNECTION-MAP.md # AST-generated dependency map (do not hand-edit) -manifest.yaml # plugin metadata + upstream version pin -pyproject.toml # pip-installable +CONNECTION-MAP.md # AST-generated dependency map (do NOT hand-edit) +manifest.yaml # plugin metadata + upstream version pin +pyproject.toml # pip-installable scripts/ - ast-connection-map.py # regenerates CONNECTION-MAP.md - upstream-sync.py # fetches upstream tags + runs CI matrix - boot-smoke.py # spin up + curl every plugin endpoint + ast-connection-map.py # regenerates CONNECTION-MAP.md + upstream-sync.py # fetches upstream tags + runs CI matrix + boot-smoke.py # spin up + curl every plugin endpoint tests/{unit,integration,evals}/ .github/workflows/ - plugin-tests.yml # push: unit + integration - connection-map-check.yml # PR: regen + diff vs committed - upstream-drift.yml # daily cron: detect upstream tags + run matrix + plugin-tests.yml # push: unit + integration + connection-map-check.yml # PR: regen + diff vs committed + upstream-drift.yml # daily cron: detect upstream tags + run matrix ``` ## Sources -- Protocol PRD: `hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md` (the contract) -- Upstream fork: `hermes-webui/` (holds ONLY the loader patch + pristine upstream) -- Deprecated: `hermes-ext/` (migrated into `static/`) +- Protocol PRD: `../docs/SVRNTY-PLUGIN-PROTOCOL.md` (the contract — 7 loader API methods, §10 validator assertions) +- Upstream fork: `../hermes-webui/` (holds ONLY the loader patch + pristine upstream) +- Deprecated: `../hermes-ext/` (migrating into `static/`) + +## Gotchas + +- Adding a route: drop file in `routes/`, register in `plugin.py` via `api.register_route`. Do NOT touch hermes-webui's `api/routes.py` +- After ANY structural change: `python3 scripts/ast-connection-map.py` then commit the regen. CI fails PR otherwise +- New loader API methods require: protocol PRD bump + `protocol-validate.sh` assertion + fork loader patch update +- Adding upstream imports: justify in `CONNECTION-MAP.md` BEFORE the import lands — the AST gen will flag it, but reviewer should see the rationale committed alongside diff --git a/README.md b/README.md index d0d9a20..e456e11 100644 --- a/README.md +++ b/README.md @@ -35,15 +35,16 @@ Without `HERMES_WEBUI_PYTHON_PLUGIN`, hermes-webui runs vanilla (no Svrnty mods) ## Public extension API -The plugin loader (one fork commit in hermes-webui) exposes exactly 6 methods: +The plugin loader (one fork commit in hermes-webui) exposes exactly 7 methods: ```python -api.register_route(path, method, handler) # add /api/ -api.register_static(prefix, directory) # serve files under /plugins//... -api.inject_script(url) # add