Codex

.codex is Lumie's shared workflow control plane. It is not part of the product runtime, but it does shape how work is discovered, planned, routed, reviewed, and documented across the workspace.

What Lives In .codex

At the workspace root, .codex holds the cross-repo automation and guidance that should not be duplicated inside each product repo:

• skills/ for the phase-based workflow and helper runbooks
• agents/ for specialist roles
• knowledge/ for glossary and repo-specific guidance
• routing/ for repo cards and review routing
• rules/ and lint/ for guardrails
• hooks/ for workflow enforcement
• worktrees/ for isolated writable runs

The main idea is simple: product repos own product code, while .codex owns the shared developer workflow.

The Default Workflow

Lumie's default path is the /ship orchestrator. It composes the common phases:

Intake → Discover → Spec → Design → Plan → Execute → Verify → Review → Commit → Learn

When you do not need the full path, the same phases can be used directly through individual skills such as /discover, /plan, /execute, /verify, or /review.

Practical Conventions

• Start with the root AGENTS.md, then the affected repo's AGENTS.md.
• Use Graphify first for structural questions such as definitions, callers, and blast radius.
• Route work by repo boundary instead of using one generic workflow for everything.
• Keep .codex as the only control plane; do not re-create repo-local copies of the same machinery.

For normal writable work, Lumie expects branch or worktree isolation to be handled by the shared workflow rather than improvised ad hoc inside each repo.

Repo Routing In Practice

The workspace uses repo-specific routing so the right guidance is loaded before edits begin:

• frontend work starts from .codex/routing/repos/frontend.md
• backend work starts from .codex/routing/repos/backend.md
• worker work starts from .codex/routing/repos/worker.md
• infra work starts from .codex/routing/repos/infra.md
• product docs start from .codex/routing/repos/document.md

This keeps module boundaries, reviewer expectations, and repo-specific rules from drifting apart.

Caveman Mode And Guardrails

New workspace sessions default to a full caveman run unless the user explicitly disables it. In practice, that means Lumie prefers the more thorough workflow by default when scope is unclear or cross-repo.

Two high-level rules matter everywhere:

• final commits go through the guarded /commit flow instead of manual git commit
• product docs, code, and infra changes should be verified against the real repo state before they are treated as complete

When This Matters For Documentation

For doc work, .codex mainly helps with routing and consistency:

• it points product docs to the Docusaurus-specific doc generation rules
• it distinguishes English source pages from localization work
• it keeps docs aligned with the same repo boundaries used by code and platform work

That is why documentation updates usually involve the root rules, the lumie-document repo rules, and the document routing map before the page itself is edited.

Where To Go Next

• Documentation for Docusaurus-specific writing rules.