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.

Typed test files

New or substantially changed test files must not add @typescript-eslint/no-explicit-any suppression entries to src/eslint-suppressions.json:

• Prefer typed structural doubles: type mock context/proxy classes against the real public types they stand in for (e.g. vscode.ExtensionContext), and use unknown for storage values and mock callback parameters instead of any.
• Access private members with bracket notation (provider["view"]) and call public members without casts so their generic signatures keep checking arguments.
• When a partial double cannot be assigned to the real type, cast it once at the construction site (as unknown as T) with a comment naming the members the double provides; do not repeat as any at every use site.
• Validate with pnpm --dir src run check-types, the narrowest affected Vitest suite, and pnpm --dir src exec eslint --prune-suppressions --max-warnings=0 <relative-test-file>; the run must not add a new entry or raise an existing count.
• An exception requires a comment next to the cast explaining why no typed alternative exists and maintainer approval in review.

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.

• Define the setting, validation, and optionality in packages/types/src/global-settings.ts (or the appropriate provider/settings schema). Define a shared default constant when multiple readers need the same default.
• If the webview uses the setting, include it in ExtensionState in packages/types/src/vscode-extension-host.ts and any relevant message types.
• In SettingsView, initialize and read the control from local cachedState, NOT directly from live useExtensionState(). The cache buffers edits until the user explicitly clicks Save; binding to live state causes races and discarded edits.
• Update cachedState from the control and include the setting in the updateSettings payload sent by SettingsView.handleSubmit() (or document and test a deliberate immediate-save flow).
• Verify webviewMessageHandler handles any setting-specific normalization or side effects and persists the final value through ContextProxy. Generic settings normally use contextProxy.setValue().
• Add the setting to ClineProvider.getState() with the intended default so extension/runtime consumers can read it.
• Add the setting to both the destructuring and returned object in ClineProvider.getStateToPostToWebview(). This completes the storage-to-webview round trip and prevents a saved control from reverting visually.
• Update every runtime consumer and ensure all consumers use the same default semantics.
• If users can import/export the setting, verify its schema inclusion makes it round-trip and add special handling only when required (for example, secrets or non-exportable state).
• Add focused tests for: UI binding/save behavior, persistence or normalization, and the saved value returned by getStateToPostToWebview(). Include both true and false/unset cases when defaulting can hide omissions.
• Run the narrowest relevant Vitest suites from the package directory that declares Vitest.

Test Placement Guidance

Prefer the narrowest test layer that proves the behavior. This follows standard test-pyramid guidance: keep most coverage in fast, focused tests; add integration tests for cross-module contracts; reserve end-to-end tests for full workflow confidence.

• Use package-local unit tests for pure logic, parsing, state transitions, validation, serialization, request construction, retry decisions, and error handling.
• Use integration tests when behavior depends on multiple internal modules working together, but does not require the real VS Code extension host or browser/webview runtime.
• Use webview-ui tests for React rendering, hooks, component state, forms, validation, and webview UI wiring.
• Use apps/vscode-e2e only when the behavior depends on the real VS Code extension host, VS Code workspace APIs, extension activation, webview/extension messaging, file watcher behavior, or a complete user workflow.
• Keep e2e tests focused on high-value smoke coverage across boundaries. Avoid placing detailed protocol, parsing, storage, retry, or edge-case assertions in e2e when they can be covered reliably at a lower layer.
• When fixing a regression, add the regression test at the lowest layer that would have failed for the bug. Add an e2e test only if lower-level tests cannot represent the failure mode.
• For a guard or validator, test the accept path and the reject path through every public entry point. A test that only rejects bad input does not prove the guard still accepts good input.
• Use it.each for repeated cases and share the setup in a helper. Do not copy a test body per input.
• A Stryker disable comment states the reason in one sentence. ESLint max-len limits it to 300 characters.

Task Lifecycle Changes

• Read docs/architecture/task-lifecycle-model.md before changing task status, delegation, interruption, completion, abandonment, persistence ownership, or scheduler fan-out behavior.
• Keep lifecycle mutations in the shared reducers under src/core/task-persistence/taskLifecycle.ts. Update model actions, invariants, or named semantic landmarks for every new transition or concurrency bug class representable in the lifecycle model, then run pnpm lifecycle:model-check.
• The in-memory run-state submodel lives in src/core/task/run-state/runState.ts. It is a pure nextRunState(state, event) kernel, separate from the persisted reducers. Read docs/architecture/task-lifecycle-target-architecture.md before changing it.
• Add extension-host E2E coverage only for a boundary the reducer model cannot prove, such as restart visibility, real persistence/rehydration, delayed provider streams, scheduler permits, or webview task scoping. Do not duplicate reducer interleavings in E2E.
• Run the focused lifecycle tests and pnpm test before completing a Zoo Code lifecycle change.

Shared Test Utilities

• Use src/test-utils/stream.ts for mechanical async-stream setup and collection.
• Use the typed helpers in src/test-utils/api.ts, src/test-utils/fs.ts, src/test-utils/reset.ts, and src/test-utils/vscode.ts when they remove repeated setup without hiding the scenario.
• Keep provider-specific payloads, failure streams, and assertions inline when they explain the behavior under test.
• Prefer shared helpers for mechanical duplication; use fixtures only when setup is reusable, typed, and independently disposable.
• New helpers must preserve failure clarity, return fresh objects, and avoid as any; keep unavoidable VS Code structural casts inside the helper with a brief explanation.