hermes/svrnty-hermes-webui-plugin
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(claude+readme): standardize CLAUDE.md, sync loader API method count 6 → 7
Some checks failed
plugin-tests / test (push) Successful in 6s
Details
upstream-drift / drift (push) Failing after 36s
Details

Browse Source 
- CLAUDE.md: drop Karpathy block, list all 7 loader methods incl
  register_audio_attachment_processor
- README: extend "Public extension API" to 7 methods

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Svrnty 2026-05-23 11:46:44 -04:00
parent adc4c98cf8
commit 33014fbea9
2 changed files with 41 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
CLAUDE.md
View File

@ -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 # 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: 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).
- `hermes-ext/` (deprecated — brand skin migrates in)
**Replaces:**
- `hermes-ext/` (deprecated — brand skin migrating in)
- 4 prior fork commits in `hermes-webui/api/` (deprecated — migrated to `routes/`) - 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` - 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 goes in `CONNECTION-MAP.md` under **forced internal dependencies** with a written justification + risk - Any other upstream import → `CONNECTION-MAP.md` under **forced internal dependencies** with written justification + risk
- CONNECTION-MAP.md is **AST-generated**, never hand-edited - `CONNECTION-MAP.md` is **AST-generated**, never hand-edited
- Every PR regenerates CONNECTION-MAP.md (CI enforces) - Every PR regenerates `CONNECTION-MAP.md` (CI enforces)
- Secrets via credctl / env only — never in repo, never on argv, never in logs - 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`) - Plugin code = stateless wrappers; state lives in upstream (or in upstream-managed `state.db`)
## Structure ## Structure
``` ```
plugin.py # entry: register(api) wires everything plugin.py # entry: register(api) wires everything
routes/<feature>.py # one file per /api/<feature> endpoint routes/<feature>.py # one file per /api/<feature> endpoint
static/{app.js,app.css,fonts/} # brand skin (subsumes hermes-ext) static/{app.js,app.css,fonts/} # brand skin (subsumes hermes-ext)
CONNECTION-MAP.md # AST-generated dependency map (do not hand-edit) CONNECTION-MAP.md # AST-generated dependency map (do NOT hand-edit)
manifest.yaml # plugin metadata + upstream version pin manifest.yaml # plugin metadata + upstream version pin
pyproject.toml # pip-installable pyproject.toml # pip-installable
scripts/ scripts/
ast-connection-map.py # regenerates CONNECTION-MAP.md ast-connection-map.py # regenerates CONNECTION-MAP.md
upstream-sync.py # fetches upstream tags + runs CI matrix upstream-sync.py # fetches upstream tags + runs CI matrix
boot-smoke.py # spin up + curl every plugin endpoint boot-smoke.py # spin up + curl every plugin endpoint
tests/{unit,integration,evals}/ tests/{unit,integration,evals}/
.github/workflows/ .github/workflows/
plugin-tests.yml # push: unit + integration plugin-tests.yml # push: unit + integration
connection-map-check.yml # PR: regen + diff vs committed connection-map-check.yml # PR: regen + diff vs committed
upstream-drift.yml # daily cron: detect upstream tags + run matrix upstream-drift.yml # daily cron: detect upstream tags + run matrix
``` ```
## Sources ## Sources
- Protocol PRD: `hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md` (the contract) - 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) - Upstream fork: `../hermes-webui/` (holds ONLY the loader patch + pristine upstream)
- Deprecated: `hermes-ext/` (migrated into `static/`) - 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

15
README.md
View File

@ -35,15 +35,16 @@ Without `HERMES_WEBUI_PYTHON_PLUGIN`, hermes-webui runs vanilla (no Svrnty mods)
## Public extension API ## 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 ```python
api.register_route(path, method, handler) # add /api/<path> api.register_route(path, method, handler) # add /api/<path>
api.register_static(prefix, directory) # serve files under /plugins/<prefix>/... api.register_static(prefix, directory) # serve files under /plugins/<prefix>/...
api.inject_script(url) # add <script> to index.html api.inject_script(url) # add <script> to index.html
api.inject_stylesheet(url) # add <link> to index.html api.inject_stylesheet(url) # add <link> to index.html
api.config_get(key, default) # safe upstream config read api.config_get(key, default) # safe upstream config read
api.logger(name) # namespaced logger api.logger(name) # namespaced logger
api.register_audio_attachment_processor(fn) # hook STT/voice attachment pipeline
``` ```
Touching anything else in hermes-webui = a Rule 2 violation per the protocol. Document the escape hatch in `CONNECTION-MAP.md` under "forced internal dependencies". Touching anything else in hermes-webui = a Rule 2 violation per the protocol. Document the escape hatch in `CONNECTION-MAP.md` under "forced internal dependencies".