Zoo-Code AGENTS.md

AGENTS.md

This file provides guidance to agents when working with code in this repository.

• Settings View Pattern: When working on SettingsView, inputs must bind to the local cachedState, NOT the live useExtensionState(). The cachedState acts as a buffer for user edits, isolating them from the ContextProxy source-of-truth until the user explicitly clicks "Save". Wiring inputs directly to the live state causes race conditions.
• Changesets: Do NOT create .changeset files for each commit or code change. Changesets are managed separately by maintainers and should not be generated by agents during normal development.
• CHANGELOG: Do NOT update CHANGELOG.md or src/CHANGELOG.md in individual PRs. CHANGELOG entries are added in bulk during release preparation PRs.

ESLint Suppressions

src/eslint-suppressions.json tracks per-file counts of suppressed lint rules. Suppression counts must never increase. When touching a file, prefer reducing its count when the fix is local and low-risk; avoid broad unrelated cleanup.

When writing new code:

• Fix lint violations in the new code rather than suppressing them.
• Avoid as any; use typed APIs directly (e.g. RooCodeEventName.X constants with typed on()/listenerCount()), or bracket notation (obj["privateField"]) to access private members. Prefer precise test doubles or unknown with a type guard over double assertions (as unknown as T); use double assertions only as a last resort, with a comment explaining why.
• Avoid floating promises; add void, await, or .catch() as appropriate.
• After editing a file, run pnpm --dir src exec eslint --prune-suppressions --max-warnings=0 <relative-file> and confirm the count for that file did not increase.
• If a suppression is truly unavoidable (e.g. vi.spyOn(Cls.prototype as any, "privateMethod") where no typed alternative exists), document why in a comment next to the cast.

Persisted Setting Checklist

When adding or changing a user setting, trace the complete round trip. A setting is not complete merely because its control renders or its value reaches storage.