4264c6cbe8
THE single repo holding every Svrnty modification to nesquena/hermes-webui per
the SVRNTY-HERMES Plugin Protocol PRD (hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md).
This scaffold is the empty vessel; Phase 2 migrates the existing fork
modifications (STT, vault status, brand skin) into it.
Contents:
plugin.py register(api) entry; reads 6-method
contract; wires static + routes
svrnty_hermes_webui_plugin/ package wrapper for pip install
manifest.yaml plugin name · version · upstream pin
pyproject.toml pip-installable
routes/__init__.py placeholder until Phase 2 migration
static/ placeholder for brand skin migration
CONNECTION-MAP.md AST-generated; 4 public API calls, 0 forced
scripts/ast-connection-map.py AST walker; modes: regen · --check · --diff
tests/{unit,integration,evals}/ skeleton for Phase 3 eval suite
.github/workflows/
plugin-tests.yml push: unit + integration + map check
connection-map-check.yml PR: regen + diff vs committed
upstream-drift.yml daily cron: detect new upstream tags +
run matrix (activates when Gitea runner
registered on Svrnty infra)
Karpathy 4 rules in CLAUDE.md; every subagent inherits them via the workspace
contract.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# 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`).
|
|
|
|
## What this repo 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)
|
|
- 4 prior fork commits in `hermes-webui/api/` (deprecated — migrated to `routes/`)
|
|
|
|
## Hard rules (inherits CLAUDE.md above + protocol)
|
|
|
|
- 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)
|
|
- 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/<feature>.py # one file per /api/<feature> 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
|
|
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
|
|
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
|
|
```
|
|
|
|
## 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/`)
|