svrnty-hermes-webui-plugin/CLAUDE.md

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/)