# Codex Game Studio Template

This repository is a game-studio template. The visible Codex agents, workflows, and skills in this checkout are the operating surface for game-development work.

## Project Goal

Build and evolve an indie game in this repository using bounded Codex game-studio roles, reviewable workflow files, and explicit validation evidence.

## Engine

Choose and record the active engine in `.codex/studio.json` during project setup. Supported engine tracks include Godot, Unity, and Unreal.

## Commands

- Configure project state: `./codex-game-studio init --non-interactive --name "<Game>" --engine <godot|unity|unreal> --mode <design|prototype|development>`
- Validate repository/template and initialized project state: `./codex-game-studio validate`
- Run a role: `./codex-game-studio run <role> "<task>"`
- Inspect workflow status: `./codex-game-studio status`

## Context Bootstrap

Before broad inspection, use compact context helpers when available, then read only surfaced files and explicit task targets:

- `./codex-game-studio context studio`
- `./codex-game-studio context task "<task>"`
- `./codex-game-studio context role <role-id>`
- `./codex-game-studio context workflow <workflow-id>`
- `./codex-game-studio context changed`

## Model Routing

- Prompt surfaces declare both a concrete model and a reasoning effort; runtime derives only the model tier from the centralized model policy.
- Choose the model family by capability and blast radius: Sol for difficult/high-risk architecture, security, release, or cross-system decisions; Terra for bounded implementation, QA, docs, and production work; Luna for simple, repetitive, mechanical, or objectively verifiable work.
- Choose reasoning effort independently for each prompt surface. Valid combinations include Luna/medium for cheap-but-careful review, Terra/low for bounded routine work, Terra/high for difficult implementation, and Sol/medium when Sol capability is useful without maximum reasoning.
- Explicit user or task-tier overrides change the model family but preserve the selected surface's reasoning effort unless an escalation policy deliberately raises it.
- Designated fallback models are fixed by family: Sol to GPT-5.5, Terra to GPT-5.4, and Luna to GPT-5.4-mini; fallback execution keeps the selected surface effort.

## Coding Conventions

- Prefer engine-native idioms and small, reviewable changes.
- Keep gameplay code, tests, assets, and documentation aligned with the active engine.
- Use task-relevant context only; do not load every agent, workflow, or template for one task.

## Asset Conventions

- Keep source assets, imported assets, and generated outputs clearly separated.
- Describe scene, prefab, material, animation, audio, and UI changes in handoff notes.
- Do not modify binary assets without recording purpose and verification evidence.

## Documentation Impact

After functional changes to game source, engine configuration, or assets, make a fresh documentation-impact decision before handoff:

- Update the owning `design/`, `docs/`, or `production/` document when player-visible behavior, architecture, production commitments, or release communication changed.
- Otherwise record `Decision: no-update`, `Documents: none`, and a specific reason under `## Documentation Impact` in `production/session-state/active.md`.
- Run `./codex-game-studio docs-impact --base <review-base>` and include its evidence in the handoff. Reviewers report unresolved documentation impact; writable implementation or fix work performs the update.

## Studio Roles

- Codex custom agents live in `.codex/agents/*.toml`.
- Workflow recipes live in `.codex/workflows/*.md`.
- Repository skills live in `.agents/skills/*/SKILL.md`.
- These files are tracked template surfaces. They are not generated by project initialization.

## Current Milestone

Use `.codex/studio.json`, `production/timeline.md`, and `production/session-state/` to record the active milestone after project setup.

## Verification

Run validation before claiming readiness. Include command output, changed files, and remaining risks in every role handoff.

## Rules

- Treat the repository root as the game workspace.
- Do not create nested `projects/<slug>/` workspaces.
- Do not synthesize or overwrite `.codex/agents/*.toml`, `.codex/workflows/*.md`, or `.agents/skills/*/SKILL.md` during initialization.
- Keep package-maintenance and documentation-maintenance surfaces out of game-facing agent and skill folders.