Change a Shared Library or SDK Without Breaking Its Public API

## Run All Tests and Builds Before Calling a Change Done Run the project's full verification stack before declaring any change complete when the change affects runtime code, tests, or build/test behavior. Verification applies when you modify: - Core library code or shared utilities. - Tests, including snapshot tests. - Example projects. - Build or test configuration (dependency manifests, task-runner files, documentation build config, CI workflows). You may skip full verification for docs-only or repository-meta changes (documentation, contributor guides, metadata files) unless the user explicitly asks for the full stack. Decide whether verification applies from the actual files changed, not from a subjective sense of how large the change is. Rerun the entire stack after applying any fixes — a partial rerun hides regressions introduced by the fix itself. When integrating with an external platform's API, consult that platform's authoritative documentation rather than relying on generic API assumptions, and inspect the local code path for the library's own behavior. ## Stay on the Current Git Branch and Worktree Unless the User Approves Work in the user's current checkout and on the current branch by default. If the task is already running inside a selected worktree, use that worktree without requesting extra permission. Do not create or switch to another worktree, and do not create or switch branches, unless the user explicitly asks for or approves that exact action in the current conversation. A request to implement, investigate, review, test, or verify changes does not by itself authorize changing the active worktree or branch. If isolation or a different checkout is genuinely needed, explain why and ask before changing any Git state. This holds even when another rule or workflow recommends a linked worktree: stop and request approval instead of selecting or creating one automatically. ## Add New API Parameters at the End So Existing Calls Keep Working The parameter and field order of exported runtime APIs is a contract, not an implementation detail. - Preserve the positional meaning of existing public constructor arguments and dataclass fields. Never insert a new parameter or field in the middle of existing public order. - Append new optional public fields or parameters to the end, keeping existing fields in their original order. - If reordering is unavoidable, add an explicit compatibility layer plus regression tests that exercise the old positional call pattern. - Prefer keyword arguments at call sites to reduce accidental breakage, but never rely on that to justify breaking positional compatibility. - Treat intended import paths and public export lists as contracts. When adding or moving a public symbol, update the owning module, the intended top-level or subpackage re-exports, and an import regression test. - Keep top-level imports free of optional-dependency failures and runtime side effects; use lazy exports when needed. ## Judge Breaking Changes Against the Latest Release, and Plan Bigger Work Judge breaking changes against the latest release, not against unreleased branch-local churn. Interfaces introduced or changed after the latest release may be rewritten directly, without compatibility shims, unless they define a released or explicitly supported durable external state boundary, or the user explicitly asks for a migration path. Unreleased persisted formats may be renumbered or squashed before release when intermediate snapshots are intentionally unsupported. Prefer direct replacement over compatibility layers for post-release branch churn. Call out compatibility risk early — but only when the change affects behavior shipped in the latest release or a released, supported durable state boundary — and confirm the approach before implementing. Use an execution plan when work is multi-step, spans several files, involves new features or refactors, or is likely to take more than about an hour. Keep its living sections (progress, discoveries, decision log, outcomes) current as you execute, and rewrite the plan if scope shifts. If you intentionally skip a plan for a complex task, note why so reviewers understand the choice. ## Read the Subsystem Reference First, Then Update Every Place a Change Reaches A library's runtime is a set of interacting subsystems — the run loop, tool execution, model and provider adapters, tracing, sessions and persistence, real-time and voice pipelines, sandboxing, and serialized run state. Before changing one, read its dedicated architecture reference and confirm you understand the boundary you are touching. When you add or change a variant that ripples across the system — a new model-output, tool-call, approval, or run-item type — update every applicable surface: processing, events, replay, persistence, tracing, and serialization. Missing one surface produces subtle, hard-to-trace corruption. Keep streaming and non-streaming paths behaviorally aligned. For any subsystem that owns connections, tasks, or other resources, verify resource ownership on both the normal and the failure path. When a serialized run-state shape changes, follow the release-boundary, schema-version, backward-read, and regression-test rules for that format. ## Keep Docs Matched to the Real Code, and Keep Sensitive Data Out of Logs - Documentation is often published to a live site, so coordinate behavior changes and docs carefully. If docs would describe behavior that is not released yet, delay the docs change until the release is available or split it into a follow-up. - Treat runnable documentation snippets as API compatibility checks. Before adding constructor or API examples, verify the shown arguments and call shape against the actual implementation. - Do not let untrusted sandbox or manifest data opt itself out of host filesystem or base-directory boundaries. Escape hatches for local materialization must be controlled by trusted application code at the call site, never by serialized manifest data. - When documenting a security grant or boundary, verify that the actual code path enforces it. Do not claim a grant applies to a materialization path (local directory, local file, archive extraction) unless that path actually consults it. - When redacting sensitive payloads, account for traceback display, exception chaining, retained exception context, logs, and telemetry. Suppressing a traceback is not enough if the original exception object still carries sensitive input. ## Pass Formatting and Test Checks, Then Write a Pull Request Handoff Extend tests whenever you touch code, and ensure the relevant checks pass before submitting. - Run the full test suite; use focused test runs by pattern while iterating. - Run static type checking; type hints must pass. - For snapshot-based tests, regenerate snapshots deliberately and rerun the suite afterward. - Coverage must stay above the project threshold. - Apply the formatter and linter; keep imports sorted; write comments as full sentences ending with a period. - Run the checks in the project's mandatory order — format, then lint, then type check, then tests. For pull requests and commits: - Use the project's PR template: include a summary, a test plan, and the related issue when applicable. - Write concise commit messages in the imperative mood; keep commits small and focused. - Add tests for new behavior and update documentation for any user-facing change. - Before your final response for an eligible change, produce a PR handoff block (summary, suggested branch name, title, draft description). Producing this handoff does not by itself authorize creating a branch, committing, pushing, or opening a pull request; skip it only for trivial or conversation-only tasks, meta or doc-only tasks without behavior impact, or when the user says not to include it. Reviewers look for: passing checks; tests that cover new behavior and edge cases; readable, consistent code; documented public-API and user-facing changes; updated examples when behavior changes; and a clean history with a clear description.