rakazo: Instructions file for Codex

AGENTS.md

• This is a public repository: assume all tracked content and diffs are public. Never commit secrets, .env files, private URLs, personal/customer data, or real production data; use fake placeholders. Review git status and the staged diff before committing, and never force-add ignored files. If private data appears, stop and alert the maintainer.
• Rakazo is one product across web, Electron desktop, and Expo mobile; Electron hosts the web UI. Put shared behavior, contracts, API logic, and reusable UI in packages. Keep only genuinely native navigation, storage, permissions, and interactions platform-specific. Core workflows must cover every applicable surface or degrade safely for an explicit reason.
• No hosted vendor is required to run the core product. Keep LLMs, sandboxes, memory, voice, integrations, and future external services optional and behind provider-neutral interfaces. Vendor SDKs, configuration, and translation belong only in adapters and composition roots. New providers must reuse shared contracts and deterministic offline conformance tests.
• Keep UI and copy minimal. Show advanced capability progressively and only when it becomes relevant; do not add explainer text that repeats the interface. Frontends express intent and render state; the backend owns orchestration, authorization, validation, retries, recovery, and provider translation. Give controls concise accessible names when needed.
• Treat every visible word as UI. Start UX work by asking what can be removed, and prefer progressive disclosure over persistent explanation or status chrome. If a PR adds user-facing copy, its description must quote the copy, explain why it is necessary, and say why removing it or revealing it only when relevant would not work.
• Configure compatible providers and models through shared connection settings and standard protocol capabilities; never add provider- or model-specific environment variables when the generic connection can express the behavior.
• Use top-level import type, never inline type imports. Reserve dynamic import() for necessary deferred loading.
• Keep code simple: reuse existing primitives and one source of truth, remove duplication and unused flexibility, and avoid speculative abstractions. Add an interface when it protects a real external or platform boundary, not for its own sake.
• Production deploys run the previous and new API side by side for a few seconds after migrations apply, so every migration must keep working with the previous release's code. Adding tables and columns is safe. To drop one, remove it from the Prisma schema and code and, in the same PR, add a migration whose first line is -- deferred: the migrate command holds it back for one run, so it applies on the next deploy, once nothing running reads it. A dropped column must be nullable or have a default while it waits; relax it in an ordinary migration in the same PR if needed. Rename by adding and backfilling the new column, switching the code, and dropping the old one deferred.
• Build for many concurrent users across several instances. Work that waits on the network (agent runs, jobs, deliveries) starts as soon as it arrives: never put it behind a global slot count, a single-flight loop, or a queue hop on the hot path. Limit only the specific resource that needs it (one bot, one computer, one provider's rate limit) so unrelated work never waits, and coordinate across processes through Postgres claims and leases.
• Treat auth, secret handling, sandbox boundaries, host commands, and integrations as security-sensitive. Keep tests deterministic and offline by default.
• Judge natural-language meaning and factual claims with an LLM and an explicit, versioned rubric calibrated against reviewed examples; do not grade free-form prose with keyword lists, regexes, or exact wording. Keep deterministic assertions for observable effects and structured output contracts. Keep judge calls opt-in and provider-neutral, report their cost separately, and treat judge errors as unqualified results rather than passes.
• The desktop Playwright suite (pnpm --filter @rakazo/desktop test:e2e) opens real Electron windows and steals focus on macOS. Do not run it on a maintainer's machine as routine verification; run the unit tests locally and let CI's virtual-display job run the e2e on push.
• Marketing pages (the Astro site in apps/www) don't get tests. Check those changes visually and with a build, not with unit or E2E tests.
• After creating a pull request, stay with it until CI and automated review bots have finished; passing checks alone do not mean the review is complete. Follow .agents/skills/pr-watch/SKILL.md: run its pr-digest --watch helper as a single backgrounded call that blocks until a new review comment or check failure arrives or the checks on the current head commit are terminal, then act on the verdict it prints and watch again. Do not poll in the foreground on a timer, which mostly buys repeated snapshots of an unchanged PR and dies at the tool timeout. Address every actionable issue, push the fixes, and repeat until no actionable feedback remains. Do not merge while review bots are still pending or review issues remain unresolved.
• PR descriptions start with ## What: a short plain-language paragraph explaining what the PR does, simple enough for someone who has never seen the code. Then ## Why: the product reason in the same plain words, what was wrong or missing and who it hurt. Then ## Changes: behavior and decisions a reviewer needs, not a tour of files, libraries, or internals the diff already shows; at most about 8 bullets. Add ## Risk only when there is one (security, migrations, limits, irreversible effects). End with ## Tested: a short paragraph naming the kinds of tests run and what was not tested, not a list of every case. Keep it under about 350 words unless the change is security- or migration-heavy. Write as the author, never as a third-person briefing about the maintainer.
• Commit messages, PR descriptions, issues, and review replies are public too. Describe test results in words instead of pasting tool output. Never include business metrics such as analytics, traffic, click-through, conversion, signup, revenue, or star-growth numbers; give the product reason in words, even when data motivated the change. Never include anything that identifies a person, machine, or account: local paths, usernames, hostnames, signing identities, legal entity names, Apple Team IDs, API key IDs, issuer or tenant IDs, account emails, or the accounts, machines, and files that secret values came from. Naming the secrets a workflow reads is fine; use placeholders when a value must be shown.
• For UI changes, link the CI E2E screenshot that shows the change on the PR; add the web test that opens that screen if it is missing. For native-only mobile UI that CI cannot capture, say so in the PR instead of linking an unrelated web screenshot; for a large native change, add a flow to the existing iOS screenshot catalog and attach the capture. Never add feature-specific flags, runners, or fake services to shared test or screenshot tooling to capture one screen; if the existing fixtures cannot show it, say so instead.
• Review bots ask how to make the code work as written, never whether it should exist. Before fixing a finding, decide whether the flagged code belongs in the PR; remove speculative, unrun, or out-of-scope code instead of building more to support it, and refute wrong findings with evidence.
• When reviewing a PR, judge it against this file. Recommend removing code that cannot work or does not belong rather than suggesting more code to support it, and flag changes the PR description does not mention, such as new vendor or provider presets, dependencies, test runners, environment variables, or edits to shared tooling.
• UI system. Colors live in @rakazo/ui-tokens as semantic tokens (background, card, muted, border, primary, destructive, ...) with one TypeScript source that generates tokens.css; never hardcode a product hex or use [var(--…)] arbitrary values. Web and Electron use shadcn/ui on Base UI, vendored into packages/ui-web via pnpm exec shadcn add from the official registry only (third-party registries are a supply-chain risk); reuse those components before writing chrome by hand, and reuse apps/web/src/components/ai/ for AI moments (loading, shimmer, success). The app is monochrome: primary is ink, status colors are destructive/success/warning, bots carry the only identity color. Mobile is native-first: Expo Router, Expo UI, native sheets, menus, alerts and pickers wherever one exists; custom surfaces (thread, composer, avatars, cards) use plain StyleSheet with the shared tokens through apps/mobile/lib/appearance, and system chrome stays PlatformColor via lib/native. Mobile may diverge from web when the native pattern is better.
• On mobile, use built-in native iOS controls (@expo/ui SwiftUI and Liquid Glass, native header items, context menus, alerts, pickers, and switches) wherever possible instead of custom React Native pills or buttons.