orca/AGENTS.md

Useful Commands

• Typecheck: pnpm tc (or tc:node / tc:cli / tc:web)
• Test: pnpm test [path/to/file.test.ts]
• Lint: oxlint, or pnpm run check:code-quality:changed for changed files (full pnpm lint is slow); format with pnpm format
• Design system: pnpm run lint:design-system for the full renderer report (not a gate); the changed-lines gate above is what CI enforces

Design System

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. When STYLEGUIDE.md is silent, follow the resolution order in its final section.

Electron UI Validation

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.

Code Style

Reuse Before Reimplementing

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.

Avoid Comments

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

File and Module Naming

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.

Type Assertions: Prefer Checked Types

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

First Class Citizens

Every change must consider these areas:

Cross-Platform Support

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/reference/cross-platform-support.md.

Remote Use Case

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

Mobile

Any feature should be considered for parity on mobile

Folder Workspaces

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

Git / GitHub

If changing code around git, gh, source-control, or review behavior read docs/reference/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.

Tests

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