Skip to main content
This page distills the canonical rules defined in 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

DomainYou MayYou MustNever
Code (TS/JS)Build Next.js App Router routes, React server/client components, shared packagesAdd/adjust tests & types, update related docsShip breaking public API changes without a BREAKING note
Code (Python)Modify apps under apps/* (python) with env isolationMaintain pinned requirements / lockfilesBlend unrelated refactors into feature work
Database (Supabase)Author migrations in apps/database/supabase/migrations, run typegenCommit regenerated @tuturuuu/types outputHand-edit generated type files
AI EndpointsAdd handlers under app/api/... using Vercel AI SDKEnforce auth + feature flags, validate payloadsExpose provider keys or skip validation
ToolingAdjust configs (biome.json, turbo.json, etc.)Document the rationaleRemove caching or security settings silently
DocsUpdate .md/.mdx for accuracyCross-link neighbouring guidesInvent behaviour that is not implemented
Dependenciesbun add --workspace / remove depsPrefer workspace:* for internal packagesAdd 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 → 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.

​
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. Completed context should move out of the active scan path. Use tmp/agent-coordination/archive/<YYYY>/<original-note-name>.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/<YYYYMMDD-HHMMSS>-<agent-or-task>.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.

​
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: 
bun git-commit-window claim --owner "<agent/task>" --scope "<commit 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: 
bun git-commit-window wait --owner "<agent/task>" --scope "<commit scope>"
Use status to inspect, check --token <token> before committing if needed, and release --token <token> after the commit operation succeeds or aborts. Do not put tokens in coordination notes.

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