world-of-claudecraft

# Codex entry point

This file owns Codex runtime behavior for World of ClaudeCraft. The root and
directory-local `CLAUDE.md` files remain canonical for repository facts, architecture,
hard invariants, conventions, commands, the default task workflow and deliverable
contract, and the QA contract. Claude-specific model,
memory, Workflow, slash-command, and agent-runtime instructions do not apply to Codex.
Do not edit or replace the Claude setup unless the user explicitly asks for that work.

## Start safely

1. Run `git status --short` before edits and preserve unrelated user work.
2. Follow the default task workflow in `CLAUDE.md`: base the work on the latest
   `release/**` branch, never `main`, and create a separate worktree for the task.
3. Read the root `CLAUDE.md` in full. Before reading or changing files in a directory,
   read that directory's `CLAUDE.md` if it exists. Codex builds its instruction chain at
   session start, so opening a nested file does not load local guidance automatically.
4. Use `rg` and targeted reads to discover the current shape. Follow existing code and
   tests instead of relying on remembered inventories or line numbers.

Never revert, discard, stage, commit, push, file an issue, post a review, or mutate a
remote system unless the user authorized that action. If a commit is requested, stage
only this task's files and follow the scoped Conventional Commit rule in `CLAUDE.md`.

## Work effectively

- Keep the main thread responsible for integration and final verification.
- Parallelize bounded exploration, log analysis, and read-only reviews when useful.
  Give overlapping files one implementation owner and wait for every delegated task
  before reporting completion.
- Treat subagent results as evidence to verify, not verdicts to relay unchanged.
- Use the active session model and reasoning setting. Do not weaken acceptance criteria,
  tests, or review depth for a faster model. Route by task shape, not a hardcoded model:
  clear mechanical work can run fast, while ambiguous architecture and security work
  needs deeper reasoning.
- Fetch current official documentation for external APIs and libraries. Do not write
  unstable interfaces from memory.
- Prefer small modules, decisive tests, and existing seams. Do not add frameworks or
  abstractions without a concrete repository need.

## Codex workflows

Repository skills live in `.agents/skills/` and are invoked as `$skill-name`:

- `$woc-qa`: scope and run the contribution gate, then dispatch relevant reviewers.
- `$woc-extract-and-test`: extract a module behind behavior-pinning tests.
- `$woc-feature-plan`: produce an implementation-ready plan for cross-cutting work.
- `$woc-review-pr`: verify a pull request without posting unless explicitly requested.
- `$woc-file-issue`: draft an issue, and file it only with explicit authorization.
- `$woc-write-game-tooltips`: write or audit plain English tooltips against live combat values and
  scaling.
- `$woc-image-to-glb`: build a shipping GLB asset from a reference image through the
  repo pipeline.
- `$woc-release-merge-audit`: find semantic damage after release integration.
- `$woc-release-malware-audit`: scan and judge malicious-code risk.
- `$woc-codex-audit`: compare the checked-in Codex architecture with current official
  guidance.

Read-only specialist agents live in `.codex/agents/`. Use only the roles matching the
changed surface: sim architecture, cross-platform parity, persistence, database
performance, server hot-path performance, security, test coverage, frontend, release
malware, and official documentation research. The parent runs deterministic commands once; reviewers inspect
evidence instead of duplicating the full gate.

For SQL, database call sites, schema or indexes, query cadence/cardinality, pool or lock
behavior, timeout policy, background work, database driver/dependency versions, PostgreSQL engine
or resource/configuration/topology changes, or stored-data growth, invoke
`woc_database_performance` before implementation decisions and again on the finished diff.
Pair it with persistence or security review when those concerns also apply.

For server work that runs per tick, per request, per broadcast, per session, or on a
recurring main-thread job (a shared read or cache, a growing collection, a snapshot or event
payload, a `selfWireJson` key or the `src/sim/` read it calls, an autosave or sweep job, a
`world_state` blob write), invoke `woc_server_hot_path`; it owns the non-SQL server budget
and the grown-collection rules in `server/CLAUDE.md` "Hot paths".

## Completion contract

Run checks proportional to the change while iterating. Before calling an implementation
complete, use `$woc-qa` or follow `docs/qa-gate.md`, including the pre-merge bar
`node scripts/gate_select.mjs` (or the deeper `npm run gate`) when the canonical gate
requires it. Report the exact commands and outcomes, remaining risks, and
any checks you could not run. A hook or subagent report never substitutes for the shared
test, typecheck, build, i18n, and security gates.

More agent context in levy-street/world-of-claudecraft

36 other files this repository gives its agents.