platform AGENTS.md

AGENTS.md - Operating Manual For Autonomous AI Assistants

1. Authority

Foundational mandates here take absolute precedence. Never invent ad-hoc behavior. This file is the hard-policy index for the Tuturuuu platform monorepo; detailed reusable patterns live in the repo-local Tuturuuu Codex plugin under plugins/tuturuuu/skills/*/references/ and in apps/docs.

Read the nearest AGENTS.md first, then load the focused Tuturuuu skill for the surface you are changing:

• $tuturuuu-platform for general apps/web, shared packages, translations, navigation, docs, and repo verification.
• $tuturuuu-web-release for version badge, release metadata, TUTURUUU_PLATFORM_VERSION, or blue/green release snapshot work.
• $tuturuuu-agent-coordination for dirty/shared worktrees, handoffs, staged path safety, coordination notes, and commit-window coordination.
• $tuturuuu-development-tooling for plugin skills, validation scripts, root scripts, CI, and durable agent workflow improvements.
• $tuturuuu-database for Supabase migrations, RLS, protected-table API writes, storage policy, generated DB types, and database aliases.
• $tuturuuu-ci-docs for GitHub Actions, tuturuuu.ts, validators, docs pages, docs navigation, and Docker deployment runbooks.
• $tuturuuu-mobile-task-board for Flutter mobile task-board behavior and mobile release metadata follow-through.
• $tuturuuu-cli, $tuturuuu-cli-tasks, and $tuturuuu-cli-finance for native ttr workflows.
• $tuturuuu-commit for explicit commit/commit-and-push requests.
• $tuturuuu-review-comments for GitHub PR review-thread follow-through.
• $tuturuuu-pr-merge-sync for PR quiet-window merge follow-through, mandatory main-green verification, bun git-sync, and production-green verification.

2. Hard Prohibitions

• Do not run long-running or build/bundling commands such as bun dev, bun run build, bun build, or equivalents unless the user explicitly asks.
• Do not run bun sb:push or bun sb:linkpush; prepare migrations and let the user apply production Supabase changes.
• Do not commit secrets, API keys, tokens, credentials, or raw sensitive values. Reference environment variables by name only.
• Do not manually edit package.json to add or update dependencies. Use the package manager command for the owning workspace.
• Do not use native browser dialogs, emojis in UI code, hard-coded hue classes, client-side raw app API fetches, or useEffect for data fetching.
• Do not add export const dynamic / export const revalidate route segment configs. Every Next app runs with cacheComponents enabled, which rejects them at build time. Opt an authed page or Supabase-backed GET route handler into request-time rendering with await connection() instead (see $tuturuuu-platform → Cache Components).
• Do not resolve actors in a registered satellite app with @tuturuuu/utils/user-helper (getCurrentUser, getCurrentWorkspaceUser) — those read Supabase auth directly. Use getSatelliteAppSessionUser('<app>') and pass the id into an injectable helper (e.g. @tuturuuu/utils/workspace-user-link). bun check enforces this via the internal-app-auth guard.
• Do not add a catch-all page ([...slug]) under [locale]/[wsId] in a satellite that proxies /api/* to web. Next checks fallback rewrites only AFTER dynamic routes, so the catch-all swallows /api/v1/... as locale="api", wsId="v1" and breaks every proxied API call. Put non-migrated-route redirects in the app's proxy.ts middleware instead.
• Use native console.* for server runtime logs, preserving severity (console.error, console.warn, etc.). Do not add serverLogger runtime imports or automatic console log-drain installation.
• Do not modify, format, stage, commit, delete, rename, or clean up files you did not intentionally touch.
• Do not use destructive Git or filesystem commands unless the user clearly asks for that operation and the scope is explicit, except for the narrowly scoped post-merge worktree and local task-branch cleanup mandated below.