Codex Game Studios -- Game Studio Agent Architecture

Codex compatibility (read first)

This repository is Claude Code Game Studios adapted to run in OpenAI Codex. The skills (.claude/skills/), agents (.claude/agents/), rules and docs were written for Claude Code and are kept unchanged as the source of truth. When they use Claude Code vocabulary, do this instead:

Also:

• Start Codex from the repository root; the hooks use repo-relative paths.
• Never read, print or edit .env files (upstream denies this in its settings).
• Path-scoped rules: before you create or edit a file that matches a glob in the table under "Path-scoped rules", read that rule file and follow it.

Project notes

Creative decisions are always the user's

project.yaml sets modes.automation: guided and lists four creative categories in modes.automation_always_ask. Upstream only consults that list in autonomous mode; in this project it applies in every mode. Treat any decision in these categories as major: present options with your recommendation, ask in chat, and wait. Never "recommend and proceed", and never pick-and-log.

This includes decisions made by subagents: a subagent returns these as questions instead of deciding. Technical work around creative content (file formats, import settings, wiring an approved line or sound into the game) follows the normal guided rules.

交付与重试规矩

• 开始一项实现或修复任务前，先用一句话说清楚这次要交付什么（比如 PR 标题、要改哪个文件，或者预期看到的命令输出）。
• 遇到以下任一情况，就停下来先找我确认： （a）超过 10 分钟一处修改都没有做（只适用于写代码、修 bug 这类实现任务；设计讨论、调研、写文档不算）； （b）同一种方法失败了两次。
• 任何一个问题最多只试两次，不要再继续重试。这条优先于「卡住自动升级」：同一个问题失败两次后直接来问我，不要换更强的模型重试。升级机制只用于其他卡住的情况。
• 子 agent 同样遵守：同一个问题失败两次就返回 BLOCKED: two attempts failed，并说明两次各试了什么，由主会话来问我。

模型提醒

开始系统架构、技术决策、系统拆分、阶段评审这类工作前（create-architecture、architecture-decision、map-systems、gate-check、review-all-gdds、architecture-review），如果当前会话不是最强的模型（Claude 用 Fable，Codex 用 gpt-6-astra），先提醒我一次可以切换，再继续。

总监用的模型

• 技术总监（technical-director）固定用最强的模型：在 Claude Code 里派出它时，指定 model: fable；在 Codex 里它的配置已经固定为 gpt-6-astra + xhigh。
• 创意总监（creative-director）和制作人（producer）保持 Opus（Codex 里是 gpt-6-astra + high），不要额外指定。

Indie game development managed through 49 coordinated agents (Codex custom agents). Each agent owns a specific domain, enforcing separation of concerns and quality.

Technology Stack

The engine, language and pipeline are configured by $setup-engine in project.yaml and in the 'Technology Stack' section of CLAUDE.md. Read them at the start of any engine or code work.

Project Structure

Directory Structure

/
├── CLAUDE.md                    # Master configuration
├── project.yaml                 # Machine-readable project config — engine, modes, stage (source of truth)
├── .claude/                     # Agent definitions, skills, hooks, rules, docs
├── <code root>/                 # Game source code — THE PATH IS ENGINE-SPECIFIC, see below
├── assets/                      # Game assets (art, audio, vfx, shaders, data)
├── design/                      # Game design documents (gdd, narrative, levels, balance)
├── docs/                        # Technical documentation (architecture, api, postmortems)
│   └── engine-reference/        # Curated engine API snapshots (version-pinned)
├── tests/                       # Game test suites (unit, integration, performance, playtest)
├── tools/                       # Build and pipeline tools (ci, build, asset-pipeline)
├── prototypes/                  # Throwaway prototypes (outside the code root)
├── production/                  # Production management (sprints, milestones, releases)
│   ├── session-state/           # Ephemeral session state (active.md — gitignored)
│   └── session-logs/            # Session audit trail (gitignored)
└── CCGS Skill Testing Framework/ # QA for the skills/agents themselves — $skill-test, $skill-improve

The code root is engine-specific

Two of the three supported engines will not build a project whose code sits in src/. This is not a style preference — it is a hard constraint of the engine's own toolchain:

Resolve the code root from engine.name before writing any source file. A path shown as src/… alone is a Godot example: read it as "the code root" and substitute the row above. src/ is the table's Godot row, not a universal path.

Tests follow the same rule — the same compilers decide what they see:

Read tests/unit/[system]/ (or integration/) anywhere as the test root plus [System]/.

Engine Version Reference

Read docs/engine-reference/<engine>/VERSION.md for the engine set in project.yaml (or CLAUDE.md) before any engine-specific work.

Technical Preferences

project.yaml at the repo root is the primary config store — engine, specialists, naming, platform, performance, modes. Skills resolve it via resolve_config (see .claude/docs/config-resolution.md).

.claude/docs/technical-preferences.md is the legacy fallback, read on demand when a key is absent from project.yaml. It is no longer imported here: before $setup-engine runs it is almost entirely [TO BE CONFIGURED] placeholders, and after it runs project.yaml holds the real values.

Coordination Rules

Agent Coordination Rules

1. Vertical Delegation: Leadership agents delegate to department leads, who delegate to specialists. Never skip a tier for complex decisions.
2. Horizontal Consultation: Agents at the same tier may consult each other but must not make binding decisions outside their domain.
3. Conflict Resolution: When two agents disagree, escalate to the shared parent. If no shared parent, escalate to creative-director for design conflicts or technical-director for technical conflicts.
4. Change Propagation: When a design change affects multiple domains, the producer agent coordinates the propagation.
5. No Unilateral Cross-Domain Changes: An agent must never modify files outside its designated directories without explicit delegation.

Model Tier Assignment

Read .claude/docs/model-tiers.md on demand. It carries the tier table, the per-skill assignments and the authoring rule.

Key point: whether a skill's model: is used depends on how the skill starts. Typed as /skill-name: yes, except a haiku pin in auto mode. Started by Claude through the Skill tool: no. Never tell a user a haiku skill saves money; an opus skill typed in a Sonnet session costs more. The agent-side model: is a different mechanism, and is applied.

Subagents vs Agent Teams

This project uses two distinct multi-agent patterns:

Subagents (current, always active)

Spawned via the Agent tool within a single Claude Code session (renamed from Task in Claude Code 2.1.63; Task still works as an alias). Used by all team-* skills and orchestration skills. Subagents share the session's permission context, run sequentially or in parallel within the session, and return results to the parent.

When to spawn in parallel: If two subagents' inputs are independent (neither needs the other's output to begin), spawn both Agent calls simultaneously rather than waiting. Example: $review-all-gdds Phase 2 (consistency) and Phase 3 (design theory) are independent — spawn both at the same time. Phase 1 loads the GDDs and both depend on it, so it is the one phase here that must NOT be parallelised.

Agent Teams (experimental — opt-in)

Multiple independent Claude Code sessions coordinated via a shared task list. Opt-in only — read .claude/docs/agent-teams.md on demand before proposing one.

Parallel Task Protocol

When an orchestration skill spawns multiple independent agents:

1. Issue all independent Agent calls before waiting for any result
2. Collect all results before proceeding to dependent phases
3. If any agent is BLOCKED, surface it immediately — do not silently skip
4. Always produce a partial report if some agents complete and others block

Collaboration Protocol

User-driven collaboration, not autonomous execution. Every task follows: Question -> Options -> Decision -> Draft -> Approval

• Agents MUST ask "May I write this to [filepath]?" before using Write/Edit tools (exempt: active.md appends, agent memory, a subagent's new file at the path its orchestrating skill named; see .claude/rules/agent-memory.md)
• Agents MUST show drafts or summaries before requesting approval
• Multi-file changes require explicit approval for the full changeset
• No commits without user instruction
• A skipped or dismissed question is not an answer: act on nothing, re-ask in plain text and wait
• Started outside this file's folder? Warn first: hooks, deny rules and the ask-first mode load only when Codex starts here

See docs/COLLABORATIVE-DESIGN-PRINCIPLE.md for full protocol and examples.

First session? If the project has no engine configured and no game concept, run $start to begin the guided onboarding flow.

Coding Standards

Coding Standards

• All game code must include doc comments on public APIs
• Architecture decisions are recorded as ADRs in docs/architecture/. How many is set by modes.workflow — all ADRs at full, critical ADRs only at standard, and none required at minimal, where the decision log and design/game-brief.md carry the rationale instead. See .claude/docs/workflow-modes.md.
• Gameplay values must be data-driven (external config), never hardcoded
• All public methods must be unit-testable (dependency injection over singletons)
• Commits must reference the relevant design document or task ID
• Commit messages: Use Conventional Commits format — feat:, fix:, chore:, docs:, test:, refactor:. Reference the story or task ID in the body (e.g., Story: EPIC-001-S02).
• Verification-driven development: Write tests first when adding gameplay systems. For UI changes, verify with screenshots. Compare expected output to actual output before marking work complete. Every implementation should have a way to prove it works.
• A parse check is not a run. Every story that changes something player-observable is launched and observed before it closes, and the observation is a retained screenshot in production/qa/evidence/. Procedure per engine: .claude/docs/run-and-observe.md. Not waived at qa.level: minimal — tests are, the look is not.

Design Document Standards

• All design docs use Markdown
• Each mechanic has a dedicated document in design/gdd/
• How many of the 8 sections are required depends on modes.workflow — all 8 at full, 5 (+ Formulas when the system defines numeric rules — rates, curves, thresholds, costs; the system's Category is a hint, not the test) at standard, and no GDD at all at minimal, where design/game-brief.md is the design record. See .claude/docs/workflow-modes.md. The 8 sections:
  1. Overview -- one-paragraph summary
  2. Player Fantasy -- intended feeling and experience
  3. Detailed Rules -- unambiguous mechanics
  4. Formulas -- all math defined with variables
  5. Edge Cases -- unusual situations handled
  6. Dependencies -- other systems listed
  7. Tuning Knobs -- configurable values identified
  8. Acceptance Criteria -- testable success conditions
• Balance values must link to their source formula or rationale

Testing Standards

Test Evidence by Story Type

All stories must have appropriate test evidence before they can be marked Done:

The Default Gate Level applies when testing.strict is not set in project.yaml. A project may override it per test type: testing.strict.logic, .integration, .visual, .ui, and .config each take true (BLOCKING) or false (ADVISORY). $story-done, $story-readiness, $dev-story, $gate-check, and $smoke-check resolve the effective level from that setting, falling back to the defaults above when it is absent.

Why Visual and UI block. "Retained" is load-bearing — the screenshot must still be on disk in production/qa/evidence/ when the story is closed. One that was captured and discarded is an assertion, not evidence. These two rows block because for a game the way it looks is the product: an advisory visual gate gets deferred in favour of whatever does block, and the result is a well-tested game that looks wrong.

Exception — $smoke-check. The ADVISORY default for Config/Data above applies to per-story evidence gates. $smoke-check is a build-health gate, not a per-story evidence gate, so its own unset default for testing.strict.config is BLOCKING. The two defaults differ on purpose.

Automated Test Rules

• Naming: per engine — .claude/rules/test-standards.md
• Determinism: Tests must produce the same result every run — no random seeds, no time-dependent assertions
• Isolation: Each test sets up and tears down its own state; tests must not depend on execution order
• No hardcoded data: Test fixtures use constant files or factory functions, not inline magic numbers (exception: boundary value tests where the exact number IS the point)
• Independence: Unit tests do not call external APIs, databases, or file I/O — use dependency injection

What NOT to Automate

• Visual fidelity (shader output, VFX appearance, animation curves)
• "Feel" qualities (input responsiveness, perceived weight, timing)
• Platform-specific rendering (test on target hardware, not headlessly)
• Full gameplay sessions (covered by playtesting, not automation)

CI/CD Rules

• Automated test suite runs on every push to main and every PR
• No merge if tests fail — tests are a blocking gate in CI
• Never disable or skip failing tests to make CI pass — fix the underlying issue
• Engine-specific CI commands:
  • Godot: godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode
  • Unity: game-ci/unity-test-runner@v4 (GitHub Actions)
  • Unreal: headless runner with -nullrhi flag

Context Management

Read .claude/docs/context-management.md on demand — it is a reference, not session context. Two of its conventions are load-bearing and cited by name elsewhere in the repo, so they are restated here rather than lost:

• production/session-state/active.md is the session checkpoint. The file is the memory, not the conversation. Read it first after any compaction, crash, or /new.
• Helpers in .claude/scripts/ emit observations, never verdicts. A script that scores or judges will eventually contradict a mode or override it cannot see. (Cited by artifact-check.sh and adr-dep-graph.sh.)

Model tiers

Upstream rates every skill and agent by difficulty; codex-port/model_tiers.toml maps the ratings to Codex models. Custom agents run on their tier's model. Skills run in this session, so a skill cannot change the model: light skills are delegated to ccgs-light-runner, heavy skills ask the user to consider /model, and standard skills run on the session model.

Escalation when an agent is stuck

Agents return a report starting with BLOCKED: when they cannot finish or are not confident in the result. When that happens, or when an agent's result is clearly unusable (fails its acceptance criteria, tests still fail, contradicts the spec or the user's decisions):

1. Retry the step with the next agent in the "If BLOCKED" column above, in order. Give it the role or skill, the original task, the failure report (and any earlier escalation reports), and the files involved.
2. Tell the user in one line each time you escalate, e.g. "game-designer got stuck on the economy formula; retrying on ccgs-escalation."
3. If the last level is also BLOCKED, stop and tell the user what each level tried and what is still blocking, with options for how to proceed.
4. Escalate each step at most once per level. Never escalated, always taken to the user: questions for the user, the creative decisions in "Project notes", and a BLOCKED: two attempts failed report. Any single problem gets at most two attempts in total, counting every agent and level (see "Project notes").
5. If you (the main session) are stuck on a step after a real attempt and the session model is weaker than the ladder, hand that step to the ladder the same way, unless that problem has already had two attempts.

Path-scoped rules

Agent roster

Custom agents in .codex/agents/ (full roles in .claude/agents/<name>.md): accessibility-specialist, ai-programmer, analytics-engineer, art-director, audio-director, community-manager, creative-director, devops-engineer, economy-designer, engine-programmer, game-designer, gameplay-programmer, godot-csharp-specialist, godot-gdextension-specialist, godot-gdscript-specialist, godot-shader-specialist, godot-specialist, lead-programmer, level-designer, live-ops-designer, localization-lead, narrative-director, network-programmer, performance-analyst, producer, prototyper, qa-lead, qa-tester, release-manager, security-engineer, sound-designer, systems-designer, technical-artist, technical-director, tools-programmer, ue-blueprint-specialist, ue-gas-specialist, ue-replication-specialist, ue-umg-specialist, ui-programmer, unity-addressables-specialist, unity-dots-specialist, unity-shader-specialist, unity-specialist, unity-ui-specialist, unreal-specialist, ux-designer, world-builder, writer