Skip to main content
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. 
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: 
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: 
npx skills add tutur3u/platform --agent codex --copy -y \
  --skill tuturuuu-agent-coordination \
  --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-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 and scoped staging expectations.
  • $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, 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 guidance for task capture, task board/list/label discovery, open-task defaults, compact task tables, task creation, splitting, movement, completion, closure, and task verification. It documents ttr-first task capture for requests to add, create, 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-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: 
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: 
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 shared-worktree coordination and agent handoff
  • 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
  • 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, and the agent-facing workflow lives in $tuturuuu-agent-coordination. 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. 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: 
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: 
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 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.