Slime AGENTS.md

AGENTS.md — read this first, then you can ship

The single onboarding doc for any coding agent or vibe-coder working on Slime. Read it top to bottom and you can collaborate without breaking anything. It is harness-neutral; CLAUDE.md is the Claude-Code-specific companion, and docs/STRUCTURE.md is the full file-by-file map.

What Slime is

A zero-dependency, zero-build plugin that renders a real coding session as a turn-based RPG. Hooks observe every prompt and tool call and append battle events to an append-only stream; three read-only consumers visualize them — a statusline HUD, a tmux pane, and a PixiJS browser arena. Your work goals are the bosses; your plugins are your gear.

The prime directive (never violate)

Observer principle. The plugin must never change the real session. With Slime installed, the agent's behavior must be byte-identical to without it. Therefore:

• Hooks are fail-soft: whole body in try/catch, always process.exit(0), never block, no LLM calls in the hot path (the heuristic core/estimate.js exists precisely to avoid one).
• Consumers (statusline.js, watch.js, serve.js) are read-only w.r.t. game state. The sole exception: serve.js writes the lang preference to config.json on an explicit user click (POST /set-lang, 127.0.0.1-only, validated) — a UI preference, not game state, and it never touches Claude's session, so the observer principle still holds. Nothing else under SLIME_ROOT is written by a consumer.

The other hard rules

• Zero runtime deps, zero build. No npm install to run; no bundler; no .ts source. TypeScript is dev-only via JSDoc + tsc --checkJs. The browser arena vendors public/vendor/pixi.min.js — never a CDN. devDependencies are fine.
• Statusline safety. Anything rendered to the terminal goes through hud.sanitize (strips control chars / ANSI — state files are untrusted input replayed every keystroke). Arena DOM uses textContent/escHtml, never innerHTML.
• Flash safety. Arena flashes are capped ≤3/sec by the sequencer governor; ?calm=1 and prefers-reduced-motion must keep degrading new effects.
• Determinism / replay-stability. State is replayed from the event stream and polled every keystroke. Do not use Math.random() in render or hook hot paths — derive "randomness" from an event index/hash (see mapper's hash) so output is stable across replays. Money/XP/unlocks are persisted once, never re-derived.
• i18n. User-facing strings live in data/locales/{en,zh}.json (flat key→string; locale.t falls back to en). Add both languages for every new key. Player resource is Token (boss HP keeps "HP").
• Test isolation. Every test sets process.env.SLIME_ROOT to a tmpdir before requiring libs (ROOT is captured at require time) and cleans up after.