AGENTS.md

AGENTS

This file provides a quick-start guide for AI agents working with the Roomote codebase.

Roomote is a product centered on Roomote agents. Those agents are the core user-facing product: they can be configured in the web app, triggered from the web UI, and interacted with through integrations such as Slack, Teams, Telegram, Linear, and GitHub.

Open source and public surfaces

This repository is open source. Treat GitHub and other public surfaces as fully public:

• Do not put customer names, customer data, private deployment details, secrets, credentials, or internal maintainer discussion into commits, PR titles/bodies, PR/issue comments, review replies, or other public artifacts.
• When writing public text, keep it general enough for an open-source audience and omit private context even when it was available in the private task thread.

Setup

• mise install && pnpm install (requires mise for repo tool versions)
• Treat mise as the default toolchain for repo-managed commands like node, npm, pnpm, uv, and python
• If a tool is missing or resolves to the wrong version, run mise install and retry with mise exec -- <command>
• Requires Docker Engine with Compose for database, Redis, and artifact-storage containers (Docker Desktop on macOS also works), ngrok for tunneling

Run

• pnpm dev — Start all services locally (PM2-managed)
• pnpm dev --reset — Start with database reset
• pm2 logs [service-name] / pm2 status — Process management

Build

• pnpm lint:fast — normal broad lint path: monorepo oxlint + residual ESLint in web and worker
• pnpm check-types:fast — normal broad type-check path
• pnpm lint and pnpm check-types — formatting-inclusive full static validation when explicitly requested
• pnpm format — oxfmt formatting

Validation

• Default to targeted test files or the narrowest package-scoped test command that covers the change.
• Targeted tests: pnpm exec dotenvx run -f .env.test -- pnpm --filter <package> exec vitest run path/to/file.test.ts
• pnpm test — Full repository Vitest suite; it is very slow, so run it rarely and only when a concrete reason requires full-suite coverage.
• If pnpm is missing or resolves to the wrong version, run mise install and retry the command with mise exec --
• pnpm lint:fast && pnpm check-types:fast && pnpm knip — Normal broad validation; matches the full pre-push suite (pre-push runs the same gates in parallel after oxlint)
• pnpm lint && pnpm check-types — Full static analysis when a concrete reason requires broader validation
• pnpm check — Full repo gate when a concrete reason requires the full gate; runs lint + check-types + test + knip
• If pnpm lint fails because of formatting, run pnpm format and rerun pnpm lint
• Pre-commit hooks: lint-staged (oxfmt on staged files). Pre-push: node scripts/pre-push-checks.mjs (oxlint, then web/worker residual ESLint + check-types:fast + knip in parallel).

Test guidance

• Read the affected package's package.json and vitest.config.* before selecting package-scoped tests.
• Do not pass test-file paths to root test commands; use the targeted package command above.
• Pair focused tests with the affected package's typecheck when a local package change requires it.
• For server-side integration paths where auth, queries, transactions, or persistence semantics matter, use the real test database, reuse available @roomote/db/server factories, and verify database state after mutations.
• In orchestration or payload-shaping unit tests, mock collaborators at the boundary instead of using database mocks to prove SQL behavior.
• For visual-only UI changes, use the smallest relevant static checks and visual proof; add UI automation only for behavioral contracts, not incidental styling or markup.
• Do not add vitest global imports where the package config already enables globals.
• Include matching build or CI-equivalent validation when a change touches Docker/build plumbing.

Working notes

• When a skill path is needed, treat repository-root-relative paths as checked-in source files. In this repo that includes .agents/skills/... and packages/cloud-agents/src/server/workflows/skills/....
• Treat absolute home-directory skill paths such as /home/roomote/.agents/skills/... as activated or installed runtime copies, not as the checked-in source of truth for repository changes.
• Treat workflow prompts and instructions as a first-class control surface. When agent behavior is off, debug prompt clarity before defaulting to code enforcement.
• apps/docs/ is the public product documentation site (published at https://docs.roomote.dev) and should be kept in sync with user-facing product changes, except for changes limited to explicitly internal-nightly experiments, which must stay out of public docs even when they change dashboard behavior.
• Keep equivalent functionality in sync across supported source-control, communication, and sandbox providers whenever applicable. Do not intentionally make provider-specific exceptions unless the user explicitly requests one.
• When adding or changing a built-in automation, explicitly evaluate whether it needs text-based Additional rules for repository scope, per-repository communication-output routing, and residual workflow/report guidance. Opt in when its output goes to a communication provider and can contain material relevant to different people or teams; exclude inherently global, triage-oriented (except CI Failure Triage), and non-communication-output automations. Keep the eligibility metadata, settings UI, save-time compilation and validation, persisted automation settings, runtime scope/routing enforcement, and prompt propagation aligned.
• Schema N-1 rollback guarantee: Roomote must always be able to roll application code back one release against the current database. Do not drop tables or columns that the previous release still reads or writes in the same release that removes the feature. Stop using the columns in app code first, keep them in packages/db with an explicit N-1 comment, and drop them only after the next release is the supported rollback target. See packages/db/AGENTS.md for the package-local rules.
• Model roles: TASK_MODEL_ROLE_DESCRIPTORS in packages/types/src/model-provider-config.ts is the single source of truth for model roles. When adding a role, define its fallback model and reasoning env vars and its fallback runtimes; wire those runtimes through the shared fallback classifier and application path; map subagents in MODEL_FALLBACK_AGENT_ROLES; and update the role fallback contract test and apps/docs/models.mdx. Do not hard-code role env lists or confuse provider-error fallback with modelFallback, which means Same as coding model inheritance.

Slack message formatting

• Present LLM / agent narrative output in Slack as markdown blocks ({ type: 'markdown', text }) with standard markdown ([label](url), **bold**, lists, tables, code fences) whenever possible. Do not convert that body text into legacy mrkdwn (*bold*, <url|label>) before posting a markdown block.
• Do not migrate hardcoded product UI Block Kit (routing confirmations, sticky footers, unfurls, accessory sections, etc.) for style alone; keep mrkdwn there when those builders already rely on it or Slack requires it (for example section text with an accessory).
• When reading inbound Slack message blocks, continue to accept both markdown blocks and legacy mrkdwn text objects.
• Built-in automation result cards use the icon named by slackIcon in packages/types/src/background-automation-registry.ts; custom automations always use zap. When adding an automation or changing its Automations UI icon, update that registry value and apps/web/scripts/generate-automation-icons.mjs, then run pnpm --filter @roomote/web automation:icons so the matching black-on-white PNG under apps/web/public/automation-icons/ stays in sync for Slack.
• New automation messages should reuse the shared automation result layout with the automation icon, header, and standard Configure/action row instead of introducing bespoke chrome; preserve the automation's content and platform-specific behavior.