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

​
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 <app-or-package> && bun add <pkg> → 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).

​
Open Pull Request Worktrees

Every open Tuturuuu pull request must be reviewed, fixed, validated, and prepared for merge in an isolated checkout under .worktrees/. Do not switch the shared main checkout onto the PR branch. Immediately run bun setup after creating the worktree so dependencies and required workspace builds are ready. In a non-interactive environment where Portless would require sudo to bind port 443, run SKIP_PORTLESS_SETUP=1 bun setup so only the interactive proxy step is skipped. Keep the worktree and its local task branch for as long as the PR remains open. After GitHub confirms the PR merge is present on main and required post-merge verification is complete, remove the completed worktree and delete its local task branch. Do not use that cleanup as permission to remove unrelated worktrees, branches, or unmerged work. When a user authorizes ongoing integration rather than a single PR, checkpoint completed lanes periodically. Integrate a scoped commit onto current main, wait until every workflow for that exact main SHA is green, run bun git-sync, and verify production before removing the completed worktree and its local task branch. Retain dirty, blocked, unmerged, user-owned, and other-agent-owned lanes. Rust build output is rebuildable but can be large in retained worktrees. Use bun rust-cache report to measure it and only the repository-owned bounded prune/auto commands to reclaim apps/backend/target space. Inspect the worktree first and never delete source or an unmerged worktree as cache cleanup.

​
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/<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. 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:
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:
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. 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 cache stores; rely on Turborepo, Bun, BuildKit, and Cargo caches plus the documented bounded cleanup wrappers.
  • 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.