> ## Documentation Index > Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent Operating Manual > Field guide summarizing the AGENTS.md policies for autonomous contributors inside the Tuturuuu monorepo. This page distills the canonical rules defined in [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md). Treat the original document as the source of truth. The root file is now a hard-policy index; detailed reusable implementation patterns live in the repo-local Tuturuuu Codex plugin skills under `plugins/tuturuuu/skills/*/references/`. ## Core Principles * **Least privilege** – Touch only the files required for the task and keep changes scoped. * **Shared worktree discipline** – Assume humans or other agents may have dirty files in the same checkout; inspect before editing and never clean up work you do not own. * **Deterministic & reproducible** – Generated artefacts must come from scripted commands; rerunning the workflow should produce the same result. * **Security first** – Never surface secret values. Reference environment variables by name and keep sensitive flows audited. * **Document intent** – When behaviour changes, update tests and docs alongside the code so the platform stays explainable. * **Human-in-the-loop** – Escalate when work exceeds the documented boundaries (e.g., major refactors, new third-party services, complex data backfills). * **Focused knowledge** – Add durable gotchas to the narrowest plugin skill reference instead of expanding the root operating manual by default. ## Capability Matrix | Domain | You May | You Must | Never | | ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- | | **Code (TS/JS)** | Build Next.js App Router routes, React server/client components, shared packages | Add/adjust tests & types, update related docs | Ship breaking public API changes without a `BREAKING` note | | **Code (Python)** | Modify apps under `apps/*` (python) with env isolation | Maintain pinned requirements / lockfiles | Blend unrelated refactors into feature work | | **Database (Supabase)** | Author migrations in `apps/database/supabase/migrations`, run typegen | Commit regenerated `@tuturuuu/types` output | Hand-edit generated type files | | **AI Endpoints** | Add handlers under `app/api/...` using Vercel AI SDK | Enforce auth + feature flags, validate payloads | Expose provider keys or skip validation | | **Tooling** | Adjust configs (`biome.json`, `turbo.json`, etc.) | Document the rationale | Remove caching or security settings silently | | **Docs** | Update `.md`/`.mdx` for accuracy | Cross-link neighbouring guides | Invent behaviour that is not implemented | | **Dependencies** | `cd && bun add ` / remove deps | Prefer `workspace:*` for internal packages | Add duplicate versions already satisfied | ## Mandatory Guardrails 1. Do not run long-lived dev/build commands unless a human requests it (e.g., `bun dev`, `bun run build`). 2. **Supabase apply is user-only** – prepare migrations, but the user runs `bun sb:push` / `bun sb:linkpush`. 3. Run formatters and checks required for files you changed, but keep auto-fixes scoped to your owned paths. 4. Avoid committing noisy logs; add diagnostics only when they materially aid debugging. 5. Never commit credentials, tokens, destructive migrations, or unrelated worktree changes. 6. Do not stage, rename, delete, or format unknown dirty/untracked files; treat them as human-owned or other-agent-owned until confirmed. 7. Do not manually bump release versions for ordinary authored work. Release Please owns package versions, changelogs, and the account-gated web badge version. Keep release-please annotations intact. ## Escalate When… * A migration needs >30 lines of backfill logic. * A refactor would touch more than three apps or five packages. * Introducing a new external service, adjusting auth flows, or changing env-var contracts. ## Canonical Workflows (Cheat Sheet) * **Add/Update dependency** – scope → `cd && bun add ` → ensure types/docs → run targeted build. * **New shared package** – scaffold under `packages/`, add `package.json` + `tsconfig`, export via `src/index.ts`, add tests & README, then build/test. * **Next.js API route** – implement under `app/api/.../route.ts`, enforce auth, validate with Zod, add tests or docs. * **AI structured endpoint** – define schema in `packages/ai`, use `generateObject`/`streamObject`, guard feature flags, redact secrets, handle errors gracefully. * **Supabase migration** – run `bun sb:new`, author additive SQL, request user to apply and regenerate types via `bun sb:typegen`, commit regenerated files together. See AGENTS.md §4 for full step-by-step instructions across all workflows. ## Focused Skill References Use the repo-local Tuturuuu Codex plugin for detailed pattern catalogs: * `$tuturuuu-platform` for web/API/shared UI patterns. * `$tuturuuu-web-release` for version badge metadata, `PLATFORM_BUILD_*`, and release-please-managed `TUTURUUU_PLATFORM_VERSION` updates. * `$tuturuuu-database` for Supabase, protected-table API, and storage patterns. * `$tuturuuu-ci-docs` for docs, CI, and Docker blue/green deployment runbooks. * `$tuturuuu-development-tooling` for root scripts, plugin validation, and CI/tooling behavior. * `$tuturuuu-agent-coordination` for shared worktrees, active notes, handoffs, and commit-window coordination. * `$tuturuuu-commit` for scoped commits, exact staging, and commit-window claim/wait/release. * `$tuturuuu-mobile-task-board` for Flutter mobile task-board and mobile UX patterns. ## Collaboration Protocol * Roles: Execution (ship code/docs), Review (verify lint/type/test/build), Architecture (cross-cutting improvements), Knowledge (docs & schema sync). * Only one agent modifies a file set at a time; reviewers work read-only unless paired. * Prefer linear history (rebases) and group commits by concern (schema vs code vs docs). ### Shared Worktree Coordination Use `tmp/agent-coordination/` as the ignored, in-worktree conversation space for agent-to-agent coordination. This is not source-controlled and should not be committed. Before editing, run `git status --short`. If dirty or untracked files already exist, record which ones are unrelated and leave them alone. If `tmp/agent-coordination/` exists, inspect top-level notes marked `working`, `blocked`, or `handoff` before choosing files. Stale active notes still count as ownership signals until checked against the current worktree. Use exact `Status:` values in coordination notes: `working`, `blocked`, `handoff`, or `done`. Put details such as `committed`, `done with concerns`, or follow-up context in `Needs`, `Verification`, or `Risks`. Treat missing or noncanonical statuses as active until resolved. Completed context should move out of the active scan path. Use `tmp/agent-coordination/archive//.md` for notes that are already marked `done` and no longer need top-level visibility. Search the archive with targeted keywords when a task mentions prior work or a workflow decision needs history; archived notes explain context, verification, and residual risks, but they are not active ownership claims. Create a note named `tmp/agent-coordination/-.md` when the worktree is dirty, active notes touch a nearby area, the task is long-running, or the task changes coordination, commit, validation, CI, deployment, plugin, or skill behavior. Each note should include: * `Agent`: stable name or session id if available. * `Intent`: one-line task summary. * `Owned paths`: files or directories the agent expects to edit. * `Observed dirty paths`: relevant pre-existing paths the agent will not touch. * `Status`: `working`, `blocked`, `handoff`, or `done`. * `Needs`: specific question or response requested from other agents. * `Commit window`: `not needed`, `claimed`, `waiting`, `blocked`, or `released` when a commit may be needed. * `Verification`: commands already run, when available. * `Risks`: remaining overlap or validation risk, when relevant. If two agents need the same file set, do not race. Reply in `tmp/agent-coordination/`, choose a disjoint slice, or ask the human partner to arbitrate. Do not edit another agent's note unless explicitly asked. Before the final response or handoff, update your own note to `done`, `handoff`, or `blocked` with verification and residual risks. Archive only your own completed `done` note unless the human partner explicitly requests broader cleanup. When committing, stage explicit paths only and never stage coordination notes or archived coordination notes. If a repo-wide check or commit hook fails because of another agent's files, do not fix those files just to satisfy the hook; report the blocker and keep your own diff scoped. For parallel subagent work, split lanes before spawning workers. Each worker needs a narrow owned path set, forbidden overlap, validation commands, and a handoff contract; workers should not stage or commit unless that is their explicit lane. Make the lane contract explicit: owner, mode, owned paths, excluded paths, generated outputs, validation, handoff shape, lifecycle (`pending`, `active`, `handoff`, `integrated`, or `closed`), and commit authority. Do not overlap implementation worker write paths unless the parent note records an explicit takeover or continuation. In Codex, use either a typed worker/explorer prompt with explicit lane context or a full-history fork without a role override; combining both is rejected by the subagent harness. The coordinator owns integration: review worker diffs, regenerate shared artifacts such as route trees, route manifests, route overrides, OpenAPI snapshots, docs navigation, sorted translations, or generated DB types after inputs are stable, then stage exact paths. After each integrated slice, refresh status, close completed subagents in the harness, mark their lanes integrated or closed in the parent note, list validation and unrelated blockers, and choose the next lane from current worktree state. Existing staged files belong to the staging agent or coordinator until explicitly reassigned; if a path is `MM`, review both staged and unstaged portions before committing. When unrelated dirty files touch shared generated inputs or outputs such as route trees, migration manifests, `packages/internal-api/src/index.ts`, generated DB types, message bundles, or `bun.lock`, default new implementation work to an isolated worktree or read-only audit unless the write set is clearly disjoint and no generator or root formatter will scan those files. If you must generate from a dirty shared checkout, use a clean tree or explicit input/output paths and record the base commit, scanned globs, copied lane inputs, generator command, copied-back artifacts, cleanup, and proof that no untracked or other-lane files leaked into the output. ### Git Commit Window Use `bun git-commit-window` to serialize Git index and commit operations in a shared checkout. The lock lives at `tmp/agent-coordination/git-commit-window.lock.json`, which is ignored by Git. It is advisory: it does not grant ownership of files and does not allow broad staging. Claims default to 10 minutes, may only be 5-10 minutes, and should be held only for focused staging and commit work. Claim the window immediately before staging, unstaging, committing, amending, rebasing, or commit-and-push work: ```bash theme={null} bun git-commit-window claim --owner "" --scope "" ``` If another agent owns the window and waiting is appropriate, use `wait`. It sleeps until the current lock is released or expires, then atomically claims the window before notifying the waiting agent. The wait timeout can be longer than the claim TTL, but the claim received after waking is still limited to 5-10 minutes: ```bash theme={null} bun git-commit-window wait --owner "" --scope "" ``` Use `status` to inspect, `check --token ` before committing if needed, and `release --token ` after the commit operation succeeds or aborts. Do not put tokens in coordination notes. For commits made in a dirty shared checkout, record a closeout packet in the parent note: staged path list, validation results for the staged set, hook result or proof-gated `--no-verify` rationale, commit hash, release confirmation, and remaining dirty-path summary. ## Tooling & Environment Rules * Single package manager: **Bun**. Use workspace filters (`bun --filter ...`) to target apps/packages. * Use `bun check:now` when you need to cancel queued or running repo-root `bun check` invocations for the current workspace and start a fresh pass immediately. * Supabase lifecycle via scripts: `sb:start`, `sb:stop`, `sb:new`, `sb:up`, `sb:typegen` (user applies pushes). * Do not invent new caches; rely on Turborepo + Bun caching. * Python services (`apps/discord/`) maintain their own pinned dependencies and README instructions. ## Testing & Quality Expectations * Add happy-path and edge-case coverage where feasible; default to Vitest via `bun run test` or filtered scope. * For DB changes, provide migrations, request the user apply them, then verify regenerated types. * Performance-sensitive changes should document rationale in-code (≤3 lines) plus PR notes. * For `html2canvas`-based preview exports, inline critical SVG brand marks (or use raster assets) and provide a solid export background color so downloaded images do not lose logos or pick up transparent-edge artifacts. For deeper detail—such as React Query policy, toast usage rules, or Tailwind dynamic color guidance—refer directly to [AGENTS.md](https://github.com/tutur3u/platform/blob/main/AGENTS.md#readme).