AGENTS.md

Rama main · réplica de lectura del repositorio original.

# 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. Vendor names never appear outside them either: not in shared contracts, settings, database columns, routes, UI, or copy, even when only one provider supports a feature today. New providers must reuse shared contracts and deterministic offline conformance tests. Packages most users won't need must load via dynamic `import()` only when configured, and must be a reputable package or the vendor's direct API from a trusted, established brand (not, say, a brand-new startup's sandbox).
- 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. Before calling a UI change done, review its screenshot with `.agents/skills/ux-declutter/SKILL.md`. 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.
- Format with Biome (`pnpm format`, or `pnpm exec biome check --write <files>`). Prettier is only a transitive dependency with no config here; never run it.
- 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. A provider-neutral interface always counts as a real boundary.
- Production deploys keep the previous release running after migrations apply (the old API for a few seconds, the old worker until its running jobs finish), 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 need new tests or CI screenshots beyond the existing homepage screenshot suite, and may name third-party vendors and providers; the product's rules on vendor names and UI tests don't apply there. Check those changes visually and with a build.
- Do not edit `CHANGELOG.md` in feature pull requests; the release skill (`.agents/skills/release/SKILL.md`) writes it from merged pull requests when a version is cut, so write the PR's `## What` and `## Risk` for that reader.
- 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.
- Ignore the Vercel "Authorization required to deploy" failure on fork PRs; it is expected and not required.
- 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, embed the CI E2E screenshot that shows the change in the PR description (`pr-watch` covers how, once CI publishes it); add the web test that opens that screen if it is missing. For native-only mobile UI that CI cannot capture, never link an unrelated web screenshot; for a large native change, add a flow to the existing iOS screenshot catalog. Whenever you captured screens while verifying a change (simulator, emulator, or browser), attach the ones that show it (`pr-watch` covers how) unless they show private data; say so only when you have none. 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.
- Feature PRs add or change UI strings in code only: never run `intl:extract` or edit translation catalogs (`messages.po`) in them. Builds show untranslated strings in English, and a workflow on main keeps one "Update translation catalogs" PR in step; translations go there or in their own translation-only PR. The one exception is adding a UI language, which commits its new catalog.
- Keep each PR to one feature or fix. A large PR is fine; bundling unrelated features is not, so open a separate PR for each.
- 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 (section headings use `SectionHeading`), 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.