Extract and Test

Implement the requested behavior with the smallest clean module boundary and direct regression coverage.

Load context

1. Read the root CLAUDE.md in full.
2. Read the relevant local CLAUDE.md before opening or editing that area.
3. Run git status --short and preserve unrelated work.
4. Inspect the production path, its callers, and nearby tests before choosing a seam.

Apply canonical architecture rules to the concrete change without copying them here.

Before implementing database-backed behavior, invoke woc_database_performance for a read-only checkpoint when the change can affect SQL or query call sites, schema or indexes, query frequency or cardinality, pool configuration, lock scope, timeout policy, or stored-data growth, including database driver/dependency upgrades and PostgreSQL engine/resource/configuration/topology changes. Carry its concrete bounds and evidence requirements into the test-first contract.

Choose the workflow

For a bug fix:

1. Reproduce the defect through the real production path.
2. Add a focused test that fails for the intended reason.
3. Confirm the test is red before changing production code.
4. Make the smallest coherent fix.
5. Add nearby edge cases only when they protect the same contract.

For a feature or refactor:

1. Identify the existing module, coordinator, state owner, or extension seam.
2. Place behavior in a pure sibling module, current state owner, or thin adapter.
3. Separate pure decisions from I/O, rendering, global state, and transport.
4. Give the extracted unit direct tests and keep consumers thin.
5. When relocating behavior, preserve semantics before redesigning anything.

Do not grow a monolith when a tested sibling is appropriate, introduce a framework for one call site, bypass existing seams to reach private state, or build parallel versions of the same rule. Preserve determinism, parity, localization, and persistence contracts. Do not commit unless explicitly asked.

Validate

Run focused tests while iterating, then:

npm run ci:changed
npx tsc --noEmit

Run domain guards for architecture, localization, persistence, parity, or security when applicable. Re-run woc_database_performance on the finished diff when its database triggers match, and woc_server_hot_path when the diff adds or changes per-tick, per-request, per-broadcast, or recurring server work (a selfWireJson key or the src/sim/ read it calls, an autosave, sweep, or durability write, a world_state blob). Before declaring the implementation ready, run npm run gate.

Report the selected seam, behavior covered, commands run, and remaining manual checks.