codex-game-studio/docs/user-guide.md

# Codex Game Studio User Guide

This guide is the detailed companion to the root [README](../README.md).

Use the README for quick orientation. Use this guide for installation, commands, role execution, workflow prompts, task orchestration, validation, and troubleshooting.

## How Codex Game Studio runs

Codex Game Studio runs locally against the current repository checkout. By default, `init` turns the current repository root into the game workspace and keeps project state in files that can be reviewed in Git. Use `--nested` only as a legacy migration escape hatch for `projects/<slug>/`.

The checked-in wrapper runs the built TypeScript entrypoint at `dist/cli.js`. This repository does not commit generated bundled CLI artifacts.

Role execution uses Codex directly. `run <role>` prepares a bounded prompt packet under the project root and invokes `codex exec` from that project.

## Installation from a source checkout

Requirements:

- Node.js 24 or newer.
- Codex CLI on `PATH` for `run <role>` and full validation.

```sh
git clone git@github.com:merlinhu1/codex-game-studio.git
cd codex-game-studio
npm install
npm run build
./codex-game-studio --help
```

Create a project:

```sh
./codex-game-studio init --name "My Game" --engine godot --mode prototype --non-interactive \
  --concept "A compact puzzle game about routing trains"

./codex-game-studio status
./codex-game-studio validate
```

## Package-bin usage

After publishing, installing, or linking the package:

```sh
npm exec codex-game-studio -- --help
npm exec codex-game-studio -- templates list
```

The package bin is `codex-game-studio` and points to the built `dist/cli.js` entrypoint.

## Project lifecycle

### Create or inspect state

```sh
./codex-game-studio init --name "My Game" --engine godot --mode prototype --non-interactive
./codex-game-studio status
./codex-game-studio resume
```

`status` and `resume` are read-only. `freeze` is the explicit command that changes project status.

### Use templates and workflow prompts

```sh
./codex-game-studio templates list
./codex-game-studio templates show gdd
./codex-game-studio market
./codex-game-studio ship-check
```

Workflow shortcuts render focused prompts. They do not launch Codex unless you explicitly use `run <role>` or a task execution command.

### Run a studio role

```sh
./codex-game-studio run producer \
  "Create the initial market overview."
```

Inspect first when the task is risky or broad:

```sh
./codex-game-studio run producer \
  "Create the initial market overview." --dry-run

./codex-game-studio run producer \
  "Create the initial market overview." --print-prompt
```

`run <role>` loads the generated project role prompt and selected templates for that role/task. `--allow-broad-context` adds bounded discovery for existing artifacts such as the GDD, production timeline, market overview, `AGENTS.md`, and `.codex/studio.json`; it does not recursively dump the project into the prompt.

### Validate before trusting output

```sh
./codex-game-studio validate
./codex-game-studio validate
```

Repository validation checks package contracts, build output, packaged assets, template availability, hidden future-only surfaces, role/workflow rendering, and Codex CLI readiness.

Project validation checks project state, generated prompt/workflow freshness, rendered-body hashes, metadata integrity, starter docs, read-only command behavior, and forbidden legacy artifacts.

## Command reference

| Command | What it does |
| --- | --- |
| `init` / `new` | Initialize the current repository root as the game workspace; pass `--nested` only for the legacy `projects/<slug>/` layout. |
| `status` | Print project phase, status, engine, and the next validation command. |
| `resume` | Print a read-only continuation summary. |
| `refresh-context` | Regenerate `.codex/context-manifest.json` after selected context files change. |
| `freeze` | Mark a project as frozen. |
| `validate` | Run hard-failing repository or project validation. |
| `templates list` | List packaged template IDs. |
| `templates show <template-id>` | Print a packaged template. |
| `run <role>` | Prepare one bounded Codex prompt packet and invoke `codex exec`. |
| `task create` / `task run` / `task orchestrate` | Manage file-backed `.codex/tasks.json` work and bounded local orchestration. |
| `workflow create-tasks <workflow-id>` | Create explicit tasks from recipes such as `vertical-slice`, `bugfix`, `ui-ux-review`, and `release-checklist`. |
| `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff`, `review`, `ship-check` | Render focused workflow prompts. |

## Workflow prompts

Workflow shortcut commands render focused prompts for a human or Codex session to use. They are inspection and preparation surfaces.

They do not launch Codex, create run records, or mutate task state unless the command explicitly says it creates tasks.

Common shortcuts:

- `market`
- `analytics`
- `design-spec`
- `feel-review`
- `art-direction`
- `ui-review`
- `milestone`
- `handoff`
- `review`
- `ship-check`

Use `workflow create-tasks <workflow-id>` when you want a supported recipe to become explicit entries in `.codex/tasks.json`.

## File-backed tasks

Task commands manage work inside the generated project instead of relying on chat memory.

- `task create` adds explicit project tasks.
- `task run` runs a selected task through the configured role path.
- `task orchestrate` runs bounded local orchestration.
- `.codex/locks/` stores transient locks for bounded orchestration.

Task orchestration is local and bounded. Hosted background loops, unbounded parallelism, and planner/next automation are outside the current product boundary.

## Troubleshooting

### The wrapper cannot find `dist/cli.js`

Run:

```sh
npm install
npm run build
```

Generated bundled CLI artifacts are intentionally not committed.

### `run <role>` cannot launch Codex

Verify that the Codex CLI is installed and available on `PATH`:

```sh
codex --help
```

Use `--dry-run` or `--print-prompt` when you only need to inspect the prompt packet.

### Validation fails on generated project files

Regenerate the relevant project surface or inspect the diff before trusting the output. Project validation is intentionally strict about stale prompt/workflow metadata and malformed project state.

See [Workflow Validation](workflow-validation.md) for the detailed validation contract.