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

# Codex Plugin

> Use and maintain the local Tuturuuu Codex plugin.

The local Tuturuuu Codex plugin lives at `plugins/tuturuuu`. It packages
repo-specific operating knowledge as Codex skills so future agent sessions can
load focused guidance without copying long instructions into every prompt.

## Discovery

Codex discovers repo-local plugins through
`.agents/plugins/marketplace.json`. The Tuturuuu marketplace is named
`tuturuuu`, displays as `Tuturuuu`, and points its local plugin entry at
`./plugins/tuturuuu`.

After changing marketplace metadata or plugin files, validate the plugin and
refresh the repo-local marketplace from the repo root. Do not bump
`plugins/tuturuuu/.codex-plugin/plugin.json` `version` for ordinary authored
workflow updates unless a release workflow or user request requires it.
The repo-local plugin manifest is currently refreshed to `0.2.23`.

```bash theme={null}
codex plugin marketplace add ./
```

Restart Codex after refreshing the marketplace. Then open the plugin directory,
choose the `Tuturuuu` marketplace, and install or update the `Tuturuuu` plugin.

If Codex does not show the repo marketplace after restart, add the repo root as
a local marketplace source from the CLI:

```bash theme={null}
codex plugin marketplace add ./
```

## skills.sh Discovery

The public skills.sh registry discovers skills from GitHub repositories after
someone installs the repo with the `skills` CLI. The platform repo exposes the
Tuturuuu plugin skills for that flow through two root metadata files:

* `.claude-plugin/marketplace.json` points compatible skill installers at
  `plugins/tuturuuu/skills`.
* `skills.sh.json` groups the public repo page so Tuturuuu skills appear ahead
  of unrelated installed project skills.

Do not run the public install trigger before the metadata is pushed to GitHub.
After pushing the metadata commit, run the trigger from a disposable directory,
not from this checkout:

```bash theme={null}
npx skills add tutur3u/platform --agent codex --copy -y \
  --skill tuturuuu-agent-coordination \
  --skill tuturuuu-browser-vercel-debugging \
  --skill tuturuuu-ci-docs \
  --skill tuturuuu-cli \
  --skill tuturuuu-cli-finance \
  --skill tuturuuu-cli-tasks \
  --skill tuturuuu-cms-studio \
  --skill tuturuuu-commit \
  --skill tuturuuu-database \
  --skill tuturuuu-devbox-ops \
  --skill tuturuuu-development-tooling \
  --skill tuturuuu-e2e-auth-debugging \
  --skill tuturuuu-external-apps \
  --skill tuturuuu-mobile-task-board \
  --skill tuturuuu-platform \
  --skill tuturuuu-pr-merge-sync \
  --skill tuturuuu-review-comments \
  --skill tuturuuu-satellite-app-ux \
  --skill tuturuuu-validation-offload \
  --skill tuturuuu-web-release
```

Then verify the cached page after refresh at
`https://skills.sh/tutur3u/platform`.

## Included Skills

* `$tuturuuu-platform`: repo-wide workflow guidance for `apps/web`,
  `packages/*`, `apps/database`, `apps/docs`, translations, navigation, and
  verification follow-through, including shared-worktree preflight, scoped
  staging expectations, and Effect adoption guidance for TypeScript
  server/service orchestration.
* `$tuturuuu-browser-vercel-debugging`: authenticated Browser/Chrome and Vercel
  CLI guidance for reproducing deployed UI/API bugs, correlating runtime and
  build logs, checking satellite routing/auth, auditing responsive and i18n
  behavior, investigating performance/cost, and verifying improvements without
  mutating customer data.
* `$tuturuuu-cms-studio`: CMS and external-project content studio guidance for
  `apps/cms`, branded project adapters, landing-page content editing, content
  collections, media workflows, preview delivery, and non-technical editor UX.
* `$tuturuuu-satellite-app-ux`: standalone app shell guidance for satellite apps
  such as Mail and CMS, including `@tuturuuu/satellite` auth, app-session
  routes, i18n, workspace navigation, permissions, and focused operational UX.
* `$tuturuuu-external-apps`: external and branded sibling app integration
  guidance for app-token exchange, refreshable admin sessions, direct signed
  storage uploads, external-project mutations, delivery fallbacks, and
  sanitized diagnostics.
* `$tuturuuu-e2e-auth-debugging`: local E2E authentication guidance for native
  Playwright patch iteration, `dev-session`, guest access, onboarding
  redirects, app-session verification, rate-limit tests, and explicit
  Docker-parity auth checks.
* `$tuturuuu-commit`: scoped commit workflow guidance for explicit commit,
  commit-and-push, atomic staging, Conventional Commit subjects, shared-worktree
  path isolation, commit-window claim/wait/release, proof-gated no-verify
  commit evidence, hook failure handling, and final commit reporting.
* `$tuturuuu-agent-coordination`: shared-worktree coordination guidance for
  dirty checkouts, active ownership notes, archived context, overlapping edits,
  stale handoffs, explicit write sets, commit-window coordination, and
  path-scoped staging safety.
* `$tuturuuu-cli`: core native `ttr` CLI install, browser login, copy-token
  login, workspace discovery, scoped help, SDK-backed command surfaces, task
  template command boundaries, version checks, and release verification
  guidance. It documents autonomous Bun and CLI installation with
  `curl -fsSL https://bun.sh/install | bash` on macOS/Linux,
  `powershell -c "irm bun.sh/install.ps1 | iex"` on Windows, then
  `bun i -g tuturuuu`.
* `$tuturuuu-cli-tasks`: focused `ttr tasks` and `ttr task-templates` guidance
  for task capture, task board/list/label discovery, open-task defaults,
  compact task tables, task creation, reusable task-template import/export,
  template instantiation, splitting, movement, completion, closure, and task
  verification. It documents ttr-first task capture for requests to add, create,
  template, track, or split Tuturuuu tasks, including label discovery and
  closing superseded combined tasks after replacements are created.
* `$tuturuuu-cli-finance`: focused `ttr finance` guidance for wallet,
  transaction, category, budget, and recurring CRUD; analytics reads; finance
  pagination footers; explicit-workspace finance read diagnostics; and wrapped
  finance response normalization in the SDK client.
* `$tuturuuu-development-tooling`: shared guidance for improving Codex skills,
  plugin behavior, validation scripts, docs runbooks, helper scripts, and
  durable workflow learnings that should benefit future Tuturuuu contributors
  and assistants, including Turborepo/Next cache boundaries, local dev-speed
  diagnostics, release-please merge automation, and package release automation
  rules.
* `$tuturuuu-pr-merge-sync`: PR closeout guidance for quiet-window review
  watching, efficient GitHub polling, merge/admin-merge follow-through, the hard
  main-green gate before `bun git-sync`, production sync, and production
  workflow verification.
* `$tuturuuu-devbox-ops`: operational guidance for `ttr box` setup, runner
  registration, one-shot smoke tests, 24/7 system services, runner-token
  cleanup, CLI upgrades, and infrastructure devbox observability.
* `$tuturuuu-validation-offload`: validation strategy guidance for deciding
  when to run focused tests, `bun check`, Supabase, Docker, or browser-heavy
  workflows through internal devboxes instead of the local agent session.
* `$tuturuuu-web-release`: `apps/web` release badge metadata, blue/green
  runtime snapshot fallback, `PLATFORM_BUILD_*` precedence, and
  release-please-managed `TUTURUUU_PLATFORM_VERSION` guidance.
* `$tuturuuu-mobile-task-board`: Flutter mobile task-board guidance for task
  dates, overdue behavior, task detail routing, description mode, assignee
  flows, and release-please-managed mobile version metadata.
* `$tuturuuu-database`: Supabase migration, RLS, workspace-scoped API write,
  generated type, storage, and database verification guidance.
* `$tuturuuu-ci-docs`: GitHub Actions, `tuturuuu.ts`, validation script,
  docs-page, and docs navigation guidance.
* `$tuturuuu-review-comments`: GitHub PR review-thread guidance for checking,
  re-checking, validating, fixing, resolving, and committing unresolved review
  comments. Addressed review threads are resolved by default after validation;
  commits and pushes still require an explicit user request. Its bundled
  `fetch_review_threads.py` helper supports `--active-only --summary` and emits
  review-thread counts for final re-check reports.

## Translation Key Workflow

When a platform change introduces a new translation key, prefer the root helper
instead of editing message JSON by hand:

```bash theme={null}
bun i18n:add --app web --key common.save --value en=Save --value vi=Lưu
```

Use `--dir apps/<app>/messages` for non-standard message directories and
`--all` only for shared UI keys that must exist in every detected app message
setup. The helper detects locale JSON files in the target setup, requires a
value for each locale, blocks unsafe key paths, prevents accidental overwrites
unless `--overwrite` is passed, and writes sorted JSON. Manual message edits are
reserved for broad copy rewrites or value-only updates; run `bun i18n:sort`
after those edits.

For larger translation updates, use bulk modes instead of repeatedly editing
JSON:

```bash theme={null}
bun i18n:add --app web --mode add --entries '{"common.save":{"en":"Save","vi":"Lưu"}}'
bun i18n:add --app web --mode remove --entries '["common.old"]'
bun i18n:add --app web --mode replace --entries-file ./translations.json
```

Bulk add and replace entries use a JSON object keyed by translation key, with
locale values underneath each key. Bulk remove accepts an array of translation
keys. Replace and remove fail when a key is missing unless `--ignore-missing` is
passed.

## CI Coverage

`.github/workflows/codex-plugin.yaml` runs the plugin-local validator and parses
the docs navigation JSON. The workflow is enabled through `tuturuuu.ts`, matching
the repo's other CI switchboard-controlled checks.

The CI check currently verifies:

* plugin manifest JSON and interface metadata
* natural default prompt examples for the invokable skills, written as short
  user requests instead of visible `$skill` commands
* dedicated prompt coverage for CMS studio and landing-page content management
* dedicated prompt coverage for external app integrations and direct uploads
* dedicated prompt coverage for satellite app UX and app-session workflows
* dedicated prompt coverage for native local E2E auth and dev-session debugging
* dedicated prompt coverage for browser and Vercel production troubleshooting
* dedicated prompt coverage for shared-worktree coordination and agent handoff
* dedicated prompt coverage for PR quiet-window merge sync with main-green
  gating before production sync
* dedicated prompt coverage for devbox runner operations and validation offload
* dedicated prompt coverage for web release badge metadata
* durable CI tooling guidance for npm package release auto-recovery
* durable CI tooling guidance for Supabase CLI setup retry and GitHub-tokened
  release lookup
* durable CI tooling guidance for bounded Codecov coverage test retries
* scoped commit workflow coverage for explicit commit requests
* native `ttr` task-template workflow coverage in the CLI task skill
* proof-gated no-verify commit evidence coverage
* commit-window claim, wait, release, and stale-lock guidance
* repo marketplace metadata at `.agents/plugins/marketplace.json`
* public skills.sh discovery metadata at `.claude-plugin/marketplace.json`
* public skills.sh grouping metadata at `skills.sh.json`
* skill folder and frontmatter naming parity
* `agents/openai.yaml` defaults for every skill
* skill `references/` links
* plugin docs page registration in `apps/docs/docs.json`
* Codex plugin workflow registration in `tuturuuu.ts`
* absence of scaffold `[TODO: ...]` placeholders
* absence of machine-specific local paths in plugin text

## Shared Worktree Coordination

Agents should assume that humans or other agents may have uncommitted work in the
same checkout. The docs-facing protocol lives in the
[Agent Operating Manual](/overview/agent-operating-manual#shared-worktree-coordination),
and the agent-facing workflow lives in `$tuturuuu-agent-coordination`.

Open Tuturuuu pull requests are always handled in isolated worktrees under
`.worktrees/`. Run `bun setup` immediately after creating the PR worktree, keep
the worktree and local task branch while the PR is open, and remove both only
after the merge is confirmed on `main` and post-merge verification is complete.
This lifecycle is documented in the Agent Operating Manual and enforced as a
cross-cutting rule in `AGENTS.md`.

Use `tmp/agent-coordination/` for lightweight agent-to-agent notes when work may
overlap, the worktree is dirty, the task is long-running, or the task changes
agent workflow rules. The directory is ignored by git, so it can hold live
intent, ownership, status, verification, risk, and handoff messages without
polluting commits.

Active notes are notes marked `working`, `blocked`, or `handoff`. Treat stale
active notes as ownership signals until you have read them and checked the
current worktree. Keep active notes as direct files under
`tmp/agent-coordination/`; archive completed notes under
`tmp/agent-coordination/archive/<YYYY>/<original-note-name>.md` after they are
marked `done` and no longer need top-level visibility.

Use `bun git-commit-window` before changing the staged set or creating commits
in a shared checkout. `claim` creates an advisory lock under
`tmp/agent-coordination/git-commit-window.lock.json`; `wait` sleeps until the
current lock is released or expires, then claims it before notifying the waiting
agent that it can commit. Claims default to 10 minutes, accept only 5-10-minute
TTLs, and should be held only while staging, inspecting, committing, amending,
rebasing, or finishing commit-and-push follow-through. Release the lock with
`bun git-commit-window release --token <token>` after the commit operation
finishes or aborts, and do not record tokens in coordination notes.

Archived notes are historical context for targeted lookup, not locks. Agents
should search them by path, feature, or workflow only when previous decisions or
verification matter to the current task. If another active note claims the same
file set, agents should choose non-overlapping slices, write a response note, or
ask the human partner to arbitrate. They should never format, stage, or fix
unrelated dirty files simply because a repo-wide check or commit hook reports
them.

When coordinating subagents, split work into named lanes with disjoint owned
paths, excluded paths, validation commands, and a no-stage/no-commit boundary
unless the lane explicitly owns a commit. The coordinator owns integration and
shared generated artifacts by default, including TanStack route trees, migration
manifests, route overrides, OpenAPI snapshots, docs navigation, sorted
translation bundles, and Supabase generated types. Workers should report
generated drift and hand off exact follow-up instead of silently committing it.
When a generator can see dirty or untracked files owned by another lane,
regenerate from a clean worktree or an explicit input set and copy back only the
intended artifact.

Write a lane contract before spawning: owner, mode, owned paths, excluded paths,
generated outputs, validation, handoff shape, and commit authority. Read-only
lanes return evidence and risks without taking ownership. In Codex, choose
either a typed worker/explorer role with explicit lane context in the prompt or
a full-history fork without a role override; the harness rejects a spawn request
that asks for both. After integrating a
slice, checkpoint before dispatching more work: refresh status, close completed
subagents, update the parent note with the commit or handoff state, list
validation and unrelated blockers, and choose the next lane from the current
worktree state.

The normal scoped commit path still lets Git hooks run. Agents may use
`git commit --no-verify` only when they can produce a proof packet for their
exact staged paths: reviewed status and staged diff output, path ownership,
separated validation mapped to the relevant `bun check` components, path-based
rationale for skipped components, and `bun check:mobile` coverage when
`apps/mobile` is touched. Incomplete proof, unclear ownership, or uncertain
check mapping means the hook should run or the risk should be reported instead
of bypassed.

## AGENTS.md Split

Root `AGENTS.md` is intentionally a compact hard-policy index. Detailed
implementation gotchas and composable patterns live in focused Tuturuuu skill
references instead:

* web/API/shared UI patterns in `$tuturuuu-platform`
* release badge/version metadata in `$tuturuuu-web-release`
* database/API/storage patterns in `$tuturuuu-database`
* CI/root-script/tooling patterns in `$tuturuuu-development-tooling`
* Docker blue/green watcher patterns in `$tuturuuu-ci-docs`
* mobile task-board and overlay patterns in `$tuturuuu-mobile-task-board`

When a session reveals durable knowledge, update the narrowest matching skill
reference and docs page. Add to root `AGENTS.md` only when the rule is a
cross-cutting hard mandate that agents must see before skill loading.

## Validate The Plugin

Run the local validator after changing the plugin manifest or its skills:

```bash theme={null}
python3 plugins/tuturuuu/scripts/validate_plugin.py
```

The local validator also checks the root skills.sh metadata files against the
actual Tuturuuu skill folders, so add every new public skill to both
`.claude-plugin/marketplace.json` and `skills.sh.json`.

For individual skills, run the Codex skill validator:

```bash theme={null}
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-platform
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cms-studio
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-satellite-app-ux
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-e2e-auth-debugging
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-external-apps
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-commit
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-agent-coordination
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cli
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cli-tasks
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-cli-finance
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-development-tooling
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-devbox-ops
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-validation-offload
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-web-release
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-mobile-task-board
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-database
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-ci-docs
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/tuturuuu/skills/tuturuuu-review-comments
```

The Codex skill validator imports `yaml`, so it requires `PyYAML` in the active
Python environment. The plugin-local validator uses only the Python standard
library.

## Maintenance Rules

* Keep `plugins/tuturuuu/.codex-plugin/plugin.json` aligned with the plugin
  folder name. Do not bump its `version` for ordinary authored work unless a
  release workflow or user request requires it; when a user explicitly asks for
  a plugin refresh, bump the manifest and keep this page current.
* Keep each skill folder name aligned with its `SKILL.md` frontmatter `name`.
* Keep plugin and skill default prompts short, natural, and action-oriented.
  Marketplace prompt cards should read like user goals, for example "Clear the
  unresolved review comments on this PR."
* Keep skill text portable across machines. Prefer repo-relative paths,
  `<repo-root>`, or `~` over user-specific absolute paths.
* Put detailed guidance in `references/` and keep `SKILL.md` focused on the
  workflow that should be loaded immediately.
* Keep shared-worktree and commit-window coordination guidance aligned across
  `AGENTS.md`, the Agent Operating Manual, `$tuturuuu-agent-coordination`, and
  `$tuturuuu-commit`.
* Keep the open-PR `.worktrees/` lifecycle, immediate `bun setup`, and
  post-merge worktree/branch cleanup guidance aligned across `AGENTS.md`, the
  Agent Operating Manual, `$tuturuuu-agent-coordination`, the platform
  checklist, and `$tuturuuu-pr-merge-sync`.
* Keep parallel subagent lane, staged-set ownership, generated-artifact
  ownership, and hook-failure guidance aligned across the Agent Operating
  Manual, `$tuturuuu-agent-coordination`, `$tuturuuu-commit`, and Git
  conventions docs.
* Keep platform release/version guidance aligned across `AGENTS.md`,
  `$tuturuuu-web-release`, and the Web Docker Deployment runbook.
* Add marketplace metadata only when deciding where the plugin should be
  installed from: repo-local `.agents/plugins/marketplace.json` or home-local
  `~/.agents/plugins/marketplace.json`.
* Keep public skills.sh metadata aligned across `.claude-plugin/marketplace.json`
  and `skills.sh.json`; do not modify `.agents/skills` just to publish the
  Tuturuuu plugin skills.