You are not here to build a feature. You are here to extract this repo’s working constitution so future Codex sessions can move fast, choose the right abstractions, and stop rediscovering the same architecture.

Goal: Create a repo-local “bible” for Codex in this repository. It should feel like it was written by the technical lead after living in the codebase for months, not by a generic documentation bot.

What I want: Build a thin router-based skill tree plus supporting guidance that maximally accelerates future work in this repo.

Do not give me generic best practices. Do not invent architecture from memory. Ground everything in the actual codebase: code, scripts, configs, docs, tests, build tooling, entrypoints, and runtime flows.

Deliverables:

1. A root AGENTS.md (create or extend) that captures:

   • instruction discovery / layering rules
   • coding principles for this repo
   • refactor and delivery rules
   • product/system posture and important mode splits
   • “where code goes” guidance
   • validation posture
   • pointers to the repo-local skills

2. A repo-local router skill at skills/<repo_name>/SKILL.md that:

   • acts as a thin index/router, not a giant runbook
   • routes users to the right narrower sub-skill
   • includes routing rules for ambiguous requests
   • includes a “required before push” checklist
   • includes a default path for unspecific requests

3. A shared principles/reference doc at skills/<repo_name>/references/principles.md that captures the cross-cutting engineering posture once.

4. A small set of high-value sub-skills, usually 4-10 total, organized by real workflows/responsibilities rather than by arbitrary folders. Each sub-skill should include:

   • when to use it
   • required context to load first
   • source-of-truth paths
   • the workflow / decision model
   • repo-specific rules and anti-patterns
   • validation commands
   • when to pull in sibling skills

5. If justified, add narrower AGENTS.md files only in areas where local rules genuinely differ.

How to work:

1. Inspect the repo first.

   • Read existing docs and instructions.
   • Identify real product surfaces, runtime modes, ownership boundaries, entrypoints, common workflows, validation commands, and failure-prone areas.
   • Find how frontend/backend/worker/data/deploy/test/dev flows actually work.
   • Prefer evidence from current code over stale docs.

2. Design the skill tree.

   • Prefer a thin router plus narrower workflow-owned skills.
   • Have one default orchestrator skill for vague “build/fix this” requests.
   • Add specialist skills only where the mental model, commands, or validation really differ.
   • Do not make one skill per folder.
   • Name skills the way a human would naturally invoke them.

3. Write the files.

   • Be concise, directive, and high-signal.
   • Use concrete file paths, modules, commands, and validation steps.
   • Encode the repo’s actual operating model.
   • Capture important distinctions like mode splits, generated artifacts, deployment/runtime constraints, request-path vs background work, shared module boundaries, etc.
   • Prefer stable abstractions; do not mirror volatile internals too literally.

4. Validate your own output.

   • Verify every path exists.
   • Verify every command is plausible in this repo.
   • Make sure the routing model is coherent and covers the common request types.
   • Remove generic fluff.
   • Make sure future Codex sessions would know where to look, what to change, and how to validate it.

Quality bar:

• This should materially reduce future context loading.
• It should help Codex choose the right files faster.
• It should reduce bad abstractions and duplicated work.
• It should make vague requests route cleanly.
• It should encode repo-specific taste, not only repo structure.
• It should be opinionated where the repo is opinionated.
• If something is uncertain, label it clearly instead of pretending.

Important constraints:

• Work with existing docs; do not overwrite useful user-authored guidance blindly.
• Keep the number of skills small and strong.
• Prefer workflow boundaries over implementation taxonomy.
• Do not stop at analysis; create the files unless blocked.
• If the repo already has partial guidance, unify and tighten it instead of duplicating it.

When done, give me:

1. the file tree you created/updated
2. the routing model in a short paragraph
3. the top repo-specific principles you encoded
4. any open questions or weak spots that still need human judgment