# Codex Game Studios Project Guide

This file is the root project guide for Codex. It is installed at the game
project root so Codex and bundled subagents have shared context before running
game-production workflows.

## Technology Stack

- **Engine**: [CHOOSE: Godot 4 / Unity / Unreal Engine 5]
- **Language**: [CHOOSE: GDScript / C# / C++ / Blueprint]
- **Version Control**: Git with trunk-based development
- **Build System**: [SPECIFY after choosing engine]
- **Asset Pipeline**: [SPECIFY after choosing engine]

Run `$setup-engine` after `$brainstorm` or whenever the project needs its engine,
version, language, and specialist routing initialized.

## Engine Version Reference

Pinned engine/version reference is created by `$setup-engine`:

```text
docs/engine-reference/<engine>/VERSION.md
```

When the file exists, read it before giving engine-specific implementation
guidance.

## Runtime Agents

Bundled custom agents are installed into:

```text
.codex/agents/
```

Bundled director agents:

- `creative-director`
- `art-director`
- `technical-director`
- `producer`

Bundled engine specialist agents:

- Godot: `godot-specialist`, `godot-gdscript-specialist`,
  `godot-csharp-specialist`, `godot-shader-specialist`,
  `godot-gdextension-specialist`
- Unity: `unity-specialist`, `unity-dots-specialist`,
  `unity-shader-specialist`, `unity-addressables-specialist`,
  `unity-ui-specialist`
- Unreal: `unreal-specialist`, `ue-blueprint-specialist`,
  `ue-gas-specialist`, `ue-replication-specialist`, `ue-umg-specialist`

Director agents are used by review gates. Engine specialists are routed through
`docs/technical-preferences.md`. They are not replacements for user decisions.

## Review Intensity

Review intensity is configured by:

```text
production/review-mode.txt
```

Allowed values:

- `full` — all gates active; every workflow step is reviewed.
- `lean` — phase-level gates only; ordinary per-skill gates are skipped.
- `solo` — no director gates anywhere.

Default when the file is missing: `lean`.

## Collaboration Protocol

User-driven collaboration, not autonomous execution. Every workflow follows:

```text
Question -> Options -> Decision -> Draft -> Approval
```

- Ask clarifying questions when the user's intent or constraints are unclear.
- Present options with trade-offs before major creative or technical decisions.
- The user makes final strategic decisions.
- Show drafts or summaries before writing important project files.
- Do not commit changes unless the user asks.
- Do not overwrite existing project guidance or design documents without
  explicit approval.

## Current Workflow Surface

The current plugin build exposes these workflows:

- `$brainstorm` guides concept ideation and produces:

```text
design/gdd/game-concept.md
```

Game pillars and anti-pillars are defined during `$brainstorm` and recorded
inside `design/gdd/game-concept.md`. A separate `design/gdd/game-pillars.md`
may be created later from the template if the project needs a standalone
pillar source of truth.

- `$setup-engine` configures the project technology stack and produces or
  updates:

```text
AGENTS.md
docs/technical-preferences.md
docs/engine-reference/<engine>/VERSION.md
```

## Project Documents

Current workflows use these project paths:

```text
design/gdd/game-concept.md
docs/technical-preferences.md
docs/engine-reference/<engine>/VERSION.md
production/review-mode.txt
```

`docs/technical-preferences.md` records engine/language conventions, platform
targets, performance budgets, approved libraries, and engine specialist routing.
Do not assume workflows beyond the current plugin surface are available.

## Context Management

- If a workflow becomes long, persist decisions into the relevant project file
  instead of relying only on chat context.
- When resuming, read existing project documents before restarting a workflow.
- Preserve user-authored content and update only the sections needed for the
  active task.