Agent Operating Manual

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.

This page distills the canonical rules defined in AGENTS.md. Treat the original document as the source of truth—this guide exists to make the most important expectations discoverable inside the docs site.

​

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).

​

Capability Matrix

​

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.

​

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 → bun add --workspace → 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.

​

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 your task may overlap with another agent, create a note named tmp/agent-coordination/<YYYYMMDD-HHMMSS>-<agent-or-task>.md. 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.

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. When committing, stage explicit paths only. 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.

​

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.