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

Codex Game Studio User Guide

This guide is the detailed companion to the root README.

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. init turns the current repository root into the game workspace and keeps project state in files that can be reviewed in Git.

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.

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:

./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:

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

./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

./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

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

Inspect first when the task is risky or broad:

./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> assembles a runtime prompt packet from tracked custom agents, project state, selected templates, and bounded context 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

./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, tracked template surfaces, context 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.
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 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:

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:

codex --help

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

Validation fails on template or project files

Inspect the relevant tracked template surface or project-state file before trusting the output. Project validation is intentionally strict about missing template files, malformed context metadata, and malformed project state.

See Workflow Validation for the detailed validation contract.