Codebase Guidelines

Task Completion

Carry the requested change through implementation, relevant verification, and fixes for failures it causes. Continue authorized, reversible local work without asking for approval at each step; ask when a missing user decision blocks progress.
Match verification to the change. Once relevant checks pass, broaden or repeat them only for new changes, failures, or unresolved concerns.
Read the linked guidance when its topic applies to the task.

Code comments are forbidden, except for semantic tool directives and Plugin SDK declaration comments.
When renaming a domain concept, search project-wide for stale names in variables, files, query keys, constants, tests, and docs; TypeScript only catches type references.
Parse and validate data at system boundaries, then pass typed values internally. Restrict unknown and as X casts to genuinely unknowable boundaries and narrow immediately.
Keep one-off types local; share types only for real cross-package contracts.
Optional or nullable fields must represent meaningful absence. Fill defaults once at the server boundary and pass explicit values through internal routes, commands, and persisted events.
Delete accepted-but-ignored route or command fields, or implement them end to end. Document route and command behavior when it is non-obvious.

The server owns product policy: defaults, instructions, manager behavior, tool lists, and thread behavior. The host daemon owns host-local primitives, provider translation, runtime/session management, and workspace execution.
Return raw host-local data from the daemon; assemble product behavior on the server. Move responsibility across this boundary only when the change requires it.
Increment HOST_DAEMON_PROTOCOL_VERSION for changes to server/daemon wire fields, including their types, requiredness, defaults, or meaning, unless compatibility with the previously shipped daemon is deliberately preserved and tested. This covers session payloads, WebSocket messages, and host RPC commands/results. Shared TypeScript builds do not verify compatibility with enrolled machines; the version bump triggers their update.

Every end-user feature must also be usable through the SDK and bb CLI; ship and document these surfaces with the UI.
For changes to CLI commands/flags or user-facing configuration (env vars, .bb/ workspace files, settings), update the discoverable surfaces listed in docs/cli-guide-and-skill.md.
New public plugin API members (@get-bb/plugin-sdk/app exports, app.slots.* methods, or BbPluginApi properties) require an experimental_ prefix and an entry in docs/api_to_audit.md describing behavior, stabilization criteria, and the core callers that use the same path. Stabilization includes the audit, a project-wide rename, and removal of the entry.
A plugin API that performs a core action must be the path core uses for that action. Extract core's implementation and route core's controls, shortcuts, and the API through it; never add a parallel plugin-only path. When several surfaces host the action, they share that implementation and one contract test table run against every surface. If core cannot use the API, it is not ready to ship.
The Plugin Guide is the only plugin API documentation. Add new surfaces to plugins/plugin-api-docs/src/surfaces.ts with their SDK symbols.

Use targeted WHERE/JOIN queries instead of loading all rows and filtering in JavaScript. Add indexes only when required by the query.
Change Drizzle schemas and regenerate migrations/snapshots; never edit snapshot JSON manually.
Never mock the database in tests. Use createMigratedConnection() from @bb/db/testing, a real SQLite database copied from a template built once by the real migrations. Call migrate(db) directly only when testing migrations or an on-disk database.

Use sanctioned typography tokens instead of arbitrary text-[Npx] classes.
Derive theme colors from --canvas/--ink or other derived tokens; never use achromatic oklch(L 0 0) literals. Mix opaque steps in oklch and translucent steps in oklab. See apps/app/src/components/ui/theme.css and theme.test.ts.
Never use CSS @scope; it causes severe WebKit style-recalculation costs. Confine styles with zero-specificity :where(<roots>) descendant and compound selector arms, as implemented in packages/plugin-build/src/scope-plugin-utilities.ts.
Use the shared persistent responsive drawer for compact slide-out menus, pickers, popovers, and dialogs. Avoid modal primitives that add inert or aria-hidden to the app root. Start the transform before heavy content; realize content after two animation frames with a timeout fallback, then retain it. Verify representative drawers in iOS Simulator Safari and test app-root and deferred-realization behavior.

Use Turbo for builds, typechecks, and tests so upstream dependencies run first: pnpm exec turbo run <task> --filter=@bb/<pkg>. Use the package's actual name for other scopes. Bypass orchestration only for deliberate investigation; do not invoke package scripts or raw tsc routinely.
Generated modules are gitignored: packages/templates/src/generated/, packages/plugin-build/src/generated/, and packages/plugin-sdk/bundled-types/. Never commit them or add a --check mode. New generated modules need Turbo tasks with explicit inputs, outputs, and consumer dependencies.
If a plugin cannot resolve @get-bb/plugin-sdk, run pnpm exec turbo run build:types --filter=@get-bb/plugin-sdk.
Test plausible failure modes; avoid trivial getters/setters and framework wiring. Pipe slow test output to a file and inspect it.
Build Vitest projects with sharedWorkerProjects from vitest.shared.ts. Node tests share workers (isolate: false); DOM tests and files/helpers that mutate worker-global state receive isolated workers. Restore any global state a test changes.

When filing issues, follow docs/filing-issues.md: reproduce first, check for duplicates, and include versions, copy-pasteable steps, verbatim expected/actual output, commit-permalink evidence, and what you ruled out. Add evidence to an existing issue when applicable.
Use .github/PULL_REQUEST_TEMPLATE.md: root cause, change, verification that demonstrates the fix, and Fixes #N when applicable.
End every agent-created issue and PR body with > AGENT GENERATED.
Ground debugging in observed state: logs, database queries, server APIs, or CLI output. For dev ports, data directories, entity IDs, and the local QA launcher, see docs/debugging-and-qa.md.
Never tail the production bb connect gate (bb-connect) with wrangler tail or the dashboard's live logs. Attaching or detaching a tail resets its Durable Objects and drops every connected tunnel. Instead, query stored Workers Logs or the Cloudflare GraphQL Analytics API (httpRequestsAdaptiveGroups, durableObjectsInvocationsAdaptiveGroups), and reproduce with wrangler tail --env staging against bb-connect-staging.