codex-game-studio/AGENTS.md

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.