• Validation: Run the smallest checks that verify the change. Prefer focused tests; expand only for concrete risk, failures, or explicit requests. Shared imports alone don’t justify broad suites.
• Typecheck: pnpm tc (or tc:node / tc:cli / tc:web)
• Test: pnpm test [path/to/file.test.ts]; affected only: pnpm test:changed [path] --maxWorkers=2 (details)
• Lint: oxlint; format: pnpm format

Never break main. Use stacks or collapse PRs before merge

All UI work — layout, color, typography, spacing, component selection, UX behavior — must follow docs/STYLEGUIDE.md. Use the tokens defined in src/renderer/src/assets/main.css (the canonical source) and the shadcn primitives in src/renderer/src/components/ui/. Don't invent new color values, font sizes, or shadow tiers when a documented one already covers the role. Read the docs/styleguide/ deep dive it links only when your change touches that topic. When STYLEGUIDE.md is silent, follow the resolution order in its final section.

Always run tests and agent-launched apps in the background with ORCA_BACKGROUND_LAUNCH=1. Never steal monitor focus or reveal test windows: no show(), showInactive(), bringToFront(), app.focus(), or OS activation. Use CDP screenshots of hidden renderers. Keep native-focus and visible-window tests paused on the user's desktop; run them on an isolated display or CI. Rebuild modified launch-policy code before running an app; stale build wrappers are not safe.

Use the $electron skill and Playwright CDP for rendered Orca UI checks. Do not use computer-use for Orca UI validation. Screenshot presentational components without Electron: pnpm fixtures:shot <id> (fixtures).

Before writing new logic at any scale — a function, component, IPC channel, state store, or whole subsystem/flow — check whether an existing implementation already does the job. Extend or generalize it instead of building a parallel version.

• Only use when code does not describe
• BE CONCISE. 1 LINE if possible (why not how)

Never use vague names like helpers, utils, common, misc, or shared-stuff for files, folders, or modules. They carry zero info and tend to become dumping grounds. Name files after what they actually contain — prefer the concrete domain concept (e.g. tab-group-state.ts, terminal-orphan-cleanup.ts) over the generic role (tabs-helpers.ts, terminal-utils.ts). If you find yourself reaching for helpers, the file probably has more than one responsibility and should be split, or there's a better name hiding in the code that describes what the functions operate on.

Avoid type assertions except as const. Unavoidable casts need a line-specific SAFETY: explanation:

Every change must consider these areas:

Support macOS, Linux, and Windows. Guard platform-specific behavior at runtime; use platform-aware shortcuts, paths, and existing process wrappers. Before changing platform-specific code, processes, shells, shortcuts, paths, or native modules, read docs/agents-md-refs/cross-platform-support.md.

Support remote execution as well as local. Clients and servers update independently; preserve compatibility across mixed versions.

Any feature should be considered for parity on mobile

All changes must consider folder workspaces as well as git worktrees. Don't assume every workspace is a git worktree.

If changing code around git, gh, source-control, or review behavior read docs/agents-md-refs/git-workflow.md.

For a failed GitHub Actions run, inspect the failed jobs and retry with gh run rerun <run-id> --failed --repo stablyai/orca. Preserve successful jobs; use a full rerun only when the failure requires revalidating them. A code fix needs a new push and fresh checks, not a retry of the old SHA.

Avoid adding low-value tests. These might be fine for development but offer negative value when checked in. Anti-patterns