From 2968ca38ab74efdb6da4c7e73d8ba2088b20f9cc Mon Sep 17 00:00:00 2001 From: MerlinH Date: Sun, 28 Jun 2026 23:00:40 +0000 Subject: [PATCH] docs: reorganize README into docs guide --- README.md | 278 +++++---------------- docs/README.md | 72 ++++++ docs/development.md | 67 +++++ docs/examples.md | 33 +-- docs/examples/README.md | 102 ++++++++ docs/project-anatomy.md | 88 +++++++ docs/readmes/README.ja.md | 79 ++++++ docs/readmes/README.ko.md | 79 ++++++ docs/readmes/README.zh.md | 79 ++++++ docs/setup.md | 4 +- docs/standards/documentation-governance.md | 2 + docs/studio-roles.md | 88 +++++++ docs/user-guide.md | 180 +++++++++++++ 13 files changed, 899 insertions(+), 252 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/development.md create mode 100644 docs/examples/README.md create mode 100644 docs/project-anatomy.md create mode 100644 docs/readmes/README.ja.md create mode 100644 docs/readmes/README.ko.md create mode 100644 docs/readmes/README.zh.md create mode 100644 docs/studio-roles.md create mode 100644 docs/user-guide.md diff --git a/README.md b/README.md index 30bd3ee..e92e8b4 100644 --- a/README.md +++ b/README.md @@ -2,55 +2,19 @@ **Turn a Codex session into a structured, local-first game studio.** -Codex Game Studio is a TypeScript CLI that creates game-project workspaces with Codex-ready roles, prompts, workflow templates, and validation. It keeps the studio state in Git-reviewable files instead of hiding planning, prompts, and run context in a hosted service. +[🇺🇸 English](README.md) | [🇨🇳 简体中文](docs/readmes/README.zh.md) | [🇯🇵 日本語](docs/readmes/README.ja.md) | [🇰🇷 한국어](docs/readmes/README.ko.md) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-NodeNext-3178c6.svg)](tsconfig.json) -```sh -./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ - --concept "A compact puzzle game about routing trains through haunted switchyards" +Codex Game Studio is a TypeScript CLI for running game-development work through Codex with a studio-shaped workspace: roles, workflow prompts, project files, task state, and validation live in ordinary Git-reviewable files. -./codex-game-studio run producer --project projects/signal-cartographer \ - "Create the initial market overview." +It is not a game engine and not a hosted project manager. It gives Codex a clearer contract for production, design, engineering, QA, art, audio, localization, and release work while leaving creative decisions and review with you. -./codex-game-studio validate --project projects/signal-cartographer -``` +## Quick start -## Why this exists - -Working with one general-purpose AI coding session is powerful, but game development needs more structure than a blank chat box: - -- Producers need milestones, handoffs, and release checks. -- Designers need GDDs, systems specs, player journeys, and tuning loops. -- Engineers need bounded implementation prompts and validation gates. -- Artists, QA, audio, localization, and live-ops work need their own context. -- Reviewers need ordinary files they can inspect in Git. - -Codex Game Studio gives Codex a studio-shaped workspace: role prompts, workflow prompts, engine context, templates, file-backed task state, and hard-failing validation. You still make the creative decisions; the CLI gives each Codex task a clear contract. - -## What you get - -| Capability | What it does | -| --- | --- | -| Local project scaffolding | Creates deterministic game projects under `projects//`. | -| Codex-native role prompts | Generates `.codex/prompts/.md` and a project `AGENTS.md`. | -| Workflow prompts | Generates reusable production, design, QA, release, and review workflows. | -| Engine overlays | Adds Godot, Unity, or Unreal context and source layout markers. | -| Focused context packets | Gives each role the templates and project files it needs, not the whole repo. | -| Direct Codex execution | Runs `codex exec` for `run ` by default. | -| Inspection modes | Supports `--dry-run` and `--print-prompt` before Codex touches the workspace. | -| File-backed tasks | Stores explicit tasks, locks, and run metadata under `.codex/**`. | -| Validation | Fails on stale generated prompts, malformed metadata, missing assets, invalid project state, and future-only CLI drift. | -| Git-reviewable state | Keeps project contracts, prompts, workflows, and docs in normal files. | - -## Quick start from a source checkout - -Requirements: - -- Node.js 24 or newer. -- Codex CLI on `PATH` for `run ` and full validation. +Requirements: Node.js 24 or newer. The Codex CLI is required for `run `. ```sh git clone git@github.com:merlinhu1/codex-game-studio.git @@ -58,205 +22,79 @@ cd codex-game-studio npm install npm run build -./codex-game-studio --help +./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ + --concept "A compact puzzle game about routing trains through haunted switchyards" + +./codex-game-studio status --project projects/signal-cartographer +./codex-game-studio validate --project projects/signal-cartographer ``` -Create and validate a project: +To inspect a role prompt before launching Codex: ```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 --project projects/my-game -./codex-game-studio validate --project projects/my-game +./codex-game-studio run producer --project projects/signal-cartographer \ + "Create the initial market overview." --print-prompt ``` -This repository does **not** commit generated bundled CLI artifacts. The checked-in wrapper runs the built TypeScript entrypoint at `dist/cli.js`; if that file is missing, run `npm install && npm run build`. +For command-by-command usage, see the [User Guide](docs/user-guide.md). + +## Why this exists + +A blank AI coding chat is flexible, but game development needs repeatable studio structure: + +- Producers need milestones, handoffs, and release checks. +- Designers need GDDs, systems specs, player journeys, and tuning loops. +- Engineers need bounded implementation prompts and validation gates. +- Artists, QA, audio, localization, and live-ops work need their own context. +- Reviewers need files they can inspect in Git, not decisions trapped in chat history. + +Codex Game Studio turns that structure into local project artifacts that Codex can read and humans can review. + +## What you get + +| Capability | What it means | +| --- | --- | +| Local project scaffolding | Creates deterministic game workspaces under `projects//`. | +| Codex-native studio roles | Generates focused role prompts for production, design, engineering, art, QA, localization, and release work. | +| Workflow prompts | Provides reusable prompts for market review, analytics, specs, handoffs, ship checks, UI review, and more. | +| Engine overlays | Adds Godot, Unity, or Unreal context without turning this project into an engine wrapper. | +| File-backed task state | Stores explicit tasks, locks, and run metadata under `.codex/**`. | +| Inspection before execution | Supports dry-run and prompt-print paths before Codex touches a project. | +| Hard-failing validation | Detects stale generated surfaces, malformed metadata, missing assets, and future-only CLI drift. | ## The studio loop ```mermaid flowchart LR - A[init project] --> B[project files] - B --> C[role and workflow prompts] - C --> D[inspect prompt] - D --> E[run Codex role] - E --> F[review output] - F --> G[validate] + A[Idea] --> B[Init project] + B --> C[Generated studio files] + C --> D[Inspect prompt] + D --> E[Run Codex role] + E --> F[Review output] + F --> G[Validate] G --> C ``` -A generated project contains the contract Codex needs: project summary, engine context, role prompts, workflow prompts, starter production docs, and validation metadata. Role runs prepare bounded prompt packets under `.codex/runs/` and invoke `codex exec` from the project root. +The generated project is the contract. It contains the project summary, engine context, role prompts, workflow prompts, starter production docs, and validation metadata that keep later Codex sessions grounded. -## Daily workflow +## Where details live -### 1. Create or inspect project state - -```sh -./codex-game-studio init --name "My Game" --engine godot --mode prototype --non-interactive -./codex-game-studio status --project projects/my-game -./codex-game-studio resume --project projects/my-game -``` - -`status` and `resume` are read-only. `freeze` is the explicit command that changes project status. - -### 2. Use templates and workflow prompts - -```sh -./codex-game-studio templates list -./codex-game-studio templates show gdd -./codex-game-studio market --project projects/my-game -./codex-game-studio ship-check --project projects/my-game -``` - -Workflow shortcuts render focused prompts. They do not launch Codex unless you explicitly use `run ` or a task execution command. - -### 3. Run a studio role - -```sh -./codex-game-studio run producer --project projects/my-game \ - "Create the initial market overview." -``` - -Inspect first when the task is risky or broad: - -```sh -./codex-game-studio run producer --project projects/my-game \ - "Create the initial market overview." --dry-run - -./codex-game-studio run producer --project projects/my-game \ - "Create the initial market overview." --print-prompt -``` - -`run ` 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. - -### 4. Validate before trusting output - -```sh -./codex-game-studio validate -./codex-game-studio validate --project projects/my-game -``` - -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. - -## Commands - -| Command | What it does | +| Need | Start here | | --- | --- | -| `init` / `new` | Create a project under `projects//`. | -| `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 ` | Print a packaged template. | -| `run ` | 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 ` | 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. | +| Install, commands, workflows, validation | [User Guide](docs/user-guide.md) | +| Role catalog and when to use each role | [Studio Roles](docs/studio-roles.md) | +| Generated project tree and file ownership | [Project Anatomy](docs/project-anatomy.md) | +| Realistic usage scenarios | [Examples](docs/examples/README.md) | +| Contributor workflow and checks | [Development](docs/development.md) | +| Full documentation map | [Docs Index](docs/README.md) | +| Product boundaries and non-goals | [Product Boundary](docs/architecture/product-boundary.md) | +| Differences from Claude Code Game Studios | [Migration from Claude](docs/migration-from-claude.md) | -## Studio roles +## Project status -| Area | Roles | -| --- | --- | -| Direction and production | `studio-orchestrator`, `producer`, `release-manager` | -| Market and analytics | `market-analyst`, `data-scientist` | -| Design and writing | `creative-director`, `senior-game-designer`, `game-designer`, `narrative-designer`, `writer`, `world-builder`, `level-designer`, `game-feel-designer`, `systems-designer`, `economy-designer` | -| Engineering | `gameplay-programmer`, `ai-programmer`, `network-programmer`, `ui-programmer`, `engine-programmer`, `tools-programmer`, `technical-director`, `devops-engineer`, `security-engineer`, `performance-analyst` | -| Engine specialists | `godot-specialist`, `unity-specialist`, `unreal-specialist` | -| Art, audio, UX | `senior-game-artist`, `technical-artist`, `audio-director`, `sound-designer`, `ui-ux-designer`, `accessibility-specialist` | -| QA, localization, operations | `qa-playtester`, `localization-lead`, `live-ops-designer`, `community-manager` | +Codex Game Studio currently supports deterministic project scaffolding, Codex role execution, workflow prompt rendering, file-backed task orchestration, and repository/project validation. -Role IDs are Codex-native and hyphenated. Unsupported legacy underscore IDs are rejected instead of silently mapped. - -## What gets generated - -Repository assets: - -- `src/`: TypeScript CLI implementation. -- `src/roles.ts`: role-package registry compiled into the CLI. -- `templates/`: design, production, art, QA, release, analytics, and engine templates. -- `engine_configs/`: engine overlays for Godot, Unity, and Unreal. -- `engine_reference/`: curated engine reference packs selected by role and task. -- `docs/`: setup, migration, validation, architecture, and truth docs. -- `tests/`: Vitest coverage for projects, prompts, templates, validation, runner behavior, engine behavior, and orchestration. - -Generated project assets: - -- `projects//`: generated project root. -- `AGENTS.md`: generated Codex project instructions, owned by `src/agents.ts`. -- `.codex/studio.json`: project metadata, role roster, workflow IDs, and workflow state. -- `.codex/prompts/`: generated role prompts. -- `.codex/workflows/`: generated workflow prompts. -- `.codex/runs/`: prompt packets and run metadata. -- `.codex/tasks.json`: file-backed task state. -- `.codex/locks/`: transient locks for bounded local orchestration. -- `documentation/`: starter game-design and production documents. -- `source/project-/`: engine project location contract. - -Generated role prompts and workflow files carry deterministic freshness metadata and rendered-body hashes. Validation compares those files against the current renderer and flags stale, malformed, or manually tampered surfaces. - -## Design boundaries - -Codex Game Studio is a local workflow layer, not a game engine and not an autonomous studio manager. - -Implemented now: - -- deterministic project scaffolding; -- generated Codex role and workflow surfaces; -- direct `codex exec` role execution; -- dry-run and prompt-print inspection; -- file-backed tasks and bounded local orchestration; -- workflow task recipes for selected high-value workflows; -- curated CCGS adaptation decisions; -- hard-failing repository and project validation. - -Not exposed as working features: - -- planner or `next` command; -- telemetry; -- changed-file tracking; -- hosted/background orchestration; -- unbounded parallelism; -- hard output-ownership enforcement; -- generated `CODEX.md` or `project_orchestrator.md` surfaces. - -See [`docs/known-upstream-differences.md`](docs/known-upstream-differences.md) and [`docs/migration-from-claude.md`](docs/migration-from-claude.md) for migration details. - -## Package use - -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. - -## Development - -```sh -npm install -npm run build -npm run typecheck -npm test -npm run validate -``` - -This project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include emitted `.js` specifiers. - -Before opening changes, run the checks in [`CONTRIBUTING.md`](CONTRIBUTING.md). Functional behavior changes should keep README claims, validation behavior, tests, and Truthmark-backed docs in sync. - -## Documentation - -- [Setup](docs/setup.md) -- [Examples](docs/examples.md) -- [Workflow validation](docs/workflow-validation.md) -- [Known upstream differences](docs/known-upstream-differences.md) -- [Migration from Claude-oriented game studio workflows](docs/migration-from-claude.md) -- [Architecture overview](docs/architecture/product-boundary.md) +The project deliberately does not expose a planner or `next` command, telemetry, hosted orchestration, unbounded parallelism, hard output-ownership enforcement, or generated `CODEX.md` / `project_orchestrator.md` surfaces. See [Known Upstream Differences](docs/known-upstream-differences.md) for migration details. ## License diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..73c23fa --- /dev/null +++ b/docs/README.md @@ -0,0 +1,72 @@ +# Codex Game Studio Docs + +## Purpose + +This directory keeps detailed usage, product, architecture, validation, and repository-truth material out of the root README. + +The root [README](../README.md) is the concise human storefront. Use this index when you need the next layer of detail. + +## Audience split + +### For users + +| Doc | Purpose | +| --- | --- | +| [User Guide](user-guide.md) | Installation, commands, role runs, workflows, tasks, validation, and troubleshooting. | +| [Setup](setup.md) | Short setup commands for source checkouts and package-bin smoke checks. | +| [Examples](examples/README.md) | Scenario-based examples inspired by the CCGS example-index style. | +| [Studio Roles](studio-roles.md) | Role catalog, role groups, and guidance for choosing the right Codex role. | +| [Project Anatomy](project-anatomy.md) | Generated project tree, file ownership, and validation-sensitive artifacts. | + +### For contributors + +| Doc | Purpose | +| --- | --- | +| [Development](development.md) | Build, test, validation, package, and documentation-maintenance workflow. | +| [Workflow Validation](workflow-validation.md) | What repository and project validation check. | +| [Known Upstream Differences](known-upstream-differences.md) | Intentional differences from the CCGS inspiration project. | +| [Migration from Claude](migration-from-claude.md) | Migration notes from Claude-oriented game-studio workflows. | +| [Product Boundary](architecture/product-boundary.md) | Implemented behavior, non-goals, and architecture boundaries. | + +### For agents + +| Doc | Purpose | +| --- | --- | +| [AGENTS.md](../AGENTS.md) | Agent entry point and repository instructions. | +| [Repo Rules](ai/repo-rules.md) | Mirrored repository-wide rules for Truthmark authority discovery. | +| [Truthmark routes](truthmark/routes/areas.md) | Route map for canonical truth docs. | +| [Product truth](truthmark/product/README.md) | Product capability promises and acceptance criteria. | +| [Engineering truth](truthmark/engineering/README.md) | Current implementation contracts, workflows, and operations. | + +## Recommended reading order + +### New user + +1. [README](../README.md) +2. [User Guide](user-guide.md) +3. [Examples](examples/README.md) +4. [Project Anatomy](project-anatomy.md) + +### Project maintainer + +1. [README](../README.md) +2. [Development](development.md) +3. [Workflow Validation](workflow-validation.md) +4. [Product Boundary](architecture/product-boundary.md) +5. Relevant Truthmark product or engineering docs + +### Agent changing behavior + +1. [AGENTS.md](../AGENTS.md) +2. [Repo Rules](ai/repo-rules.md) +3. [Product Boundary](architecture/product-boundary.md) +4. [Truthmark routes](truthmark/routes/areas.md) +5. The nearest owning product or engineering truth doc + +## Update rules + +- Keep the root README concise. Move command reference, role catalog, generated-file detail, and contributor workflow detail into subdocs. +- When the root README changes materially, update localized README variants under `docs/readmes/` in the same change or state why they intentionally differ. +- When a command, workflow, generated artifact, role, or validation behavior changes, update the nearest user-facing doc and the owning Truthmark doc if it is behavior-bearing. +- Do not keep parallel current-state docs for the same subject. Link to the owning doc instead of duplicating details. +- Keep scenario examples concrete and outcome-oriented, not exhaustive command dumps. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..5525e6d --- /dev/null +++ b/docs/development.md @@ -0,0 +1,67 @@ +# Development + +This document is for contributors working on Codex Game Studio itself. + +For user-facing command usage, see the [User Guide](user-guide.md). For generated project layout, see [Project Anatomy](project-anatomy.md). + +## Setup + +```sh +npm install +npm run build +./codex-game-studio --help +``` + +This project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include emitted `.js` specifiers. + +## Standard checks + +Run these before publishing a change: + +```sh +npm run typecheck +npm test +npm run validate +truthmark check --json +truthmark index --json +``` + +Use focused tests while developing, then run the full gate before committing. + +## Source-checkout wrapper + +The checked-in `./codex-game-studio` wrapper runs the built TypeScript entrypoint at `dist/cli.js`. + +Generated bundled CLI artifacts are not committed. If the wrapper cannot find `dist/cli.js`, run: + +```sh +npm install +npm run build +``` + +## Package-bin smoke + +After build, link, install, or package smoke testing: + +```sh +npm exec codex-game-studio -- --help +npm exec codex-game-studio -- templates show gdd +``` + +The package bin is `codex-game-studio` and points to `dist/cli.js`. + +## Documentation maintenance + +- Keep the root README concise and human-facing. +- Move command detail to [User Guide](user-guide.md). +- Move role detail to [Studio Roles](studio-roles.md). +- Move generated-file detail to [Project Anatomy](project-anatomy.md). +- Move contributor/build detail to this file. +- When the root README changes materially, update localized README storefronts under `docs/readmes/` in the same change or document the intentional deferral. +- Behavior-bearing changes should keep README claims, validation behavior, tests, and Truthmark-backed docs in sync. + +## Truthmark-aware changes + +This repository contains Truthmark-managed docs. Functional behavior changes should update the nearest canonical product or engineering truth doc and then run Truthmark validation. + +Docs-only navigation changes do not require a Truth Sync workflow, but they should still pass `truthmark check` and `truthmark index` before publication. diff --git a/docs/examples.md b/docs/examples.md index 36aee9c..3d3906e 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,34 +1,5 @@ # Examples -Create and validate a project from this repository: +Examples now live in the scenario index at [docs/examples/README.md](examples/README.md). -```sh -./codex-game-studio init --name "Rogue Core" --engine godot --mode prototype --non-interactive --competitor "Mini Metro" --competitor "Dorfromantik" -./codex-game-studio status --project projects/rogue-core -./codex-game-studio validate --project projects/rogue-core -``` - -Run a studio role directly through Codex: - -```sh -./codex-game-studio run producer --project projects/rogue-core "Create the initial market overview." -``` - -Inspect prompts without launching Codex: - -```sh -./codex-game-studio run producer --project projects/rogue-core "Create the initial market overview." --dry-run -./codex-game-studio market --project projects/rogue-core --dry-run -./codex-game-studio analytics --project projects/rogue-core --dry-run -./codex-game-studio handoff --project projects/rogue-core --dry-run -./codex-game-studio design-spec --project projects/rogue-core --dry-run -./codex-game-studio feel-review --project projects/rogue-core --dry-run -./codex-game-studio ui-review --project projects/rogue-core --dry-run -``` - -Discover packaged templates: - -```sh -./codex-game-studio templates list -./codex-game-studio templates show market_analysis -``` +The new index follows the CCGS pattern: each example explains the scenario, complexity, command sequence, and what the reader should learn. diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 0000000..37265c5 --- /dev/null +++ b/docs/examples/README.md @@ -0,0 +1,102 @@ +# Examples + +This directory contains scenario-oriented examples for using Codex Game Studio. Each example focuses on the workflow shape: what you are trying to do, which commands you run, and what you learn. + +## Start here + +If you are new to the system, read the root [README](../../README.md), run the quick start, then come back here for common scenarios. + +## Available examples + +### Create and validate a Godot prototype + +**Type:** project initialization +**Complexity:** low + +Create a local project, inspect its state, and run validation. + +```sh +./codex-game-studio init --name "Rogue Core" --engine godot --mode prototype --non-interactive \ + --competitor "Mini Metro" --competitor "Dorfromantik" +./codex-game-studio status --project projects/rogue-core +./codex-game-studio validate --project projects/rogue-core +``` + +**Learn:** project creation, generated project location, status output, and project validation. + +--- + +### Run a producer market pass + +**Type:** role execution +**Complexity:** low-medium + +Inspect the prompt first, then run the producer role through Codex. + +```sh +./codex-game-studio run producer --project projects/rogue-core \ + "Create the initial market overview." --print-prompt + +./codex-game-studio run producer --project projects/rogue-core \ + "Create the initial market overview." +``` + +**Learn:** role selection, prompt inspection, direct Codex execution, and review-before-trust workflow. + +--- + +### Prepare focused workflow prompts + +**Type:** workflow prompt rendering +**Complexity:** low + +Render workflow prompts without launching Codex. + +```sh +./codex-game-studio market --project projects/rogue-core --dry-run +./codex-game-studio analytics --project projects/rogue-core --dry-run +./codex-game-studio handoff --project projects/rogue-core --dry-run +./codex-game-studio design-spec --project projects/rogue-core --dry-run +./codex-game-studio feel-review --project projects/rogue-core --dry-run +./codex-game-studio ui-review --project projects/rogue-core --dry-run +``` + +**Learn:** workflow shortcuts are preparation surfaces; they do not launch Codex or create run records. + +--- + +### Create a vertical-slice task plan + +**Type:** file-backed task workflow +**Complexity:** medium + +Turn a supported workflow recipe into explicit project tasks. + +```sh +./codex-game-studio workflow create-tasks vertical-slice --project projects/rogue-core +./codex-game-studio validate --project projects/rogue-core +``` + +**Learn:** task recipes, `.codex/tasks.json`, and validation after task-state changes. + +--- + +### Discover packaged templates + +**Type:** template discovery +**Complexity:** low + +List templates and inspect one before using it in a role prompt or design session. + +```sh +./codex-game-studio templates list +./codex-game-studio templates show market_analysis +``` + +**Learn:** packaged template IDs and how templates support studio workflows. + +## More detail + +- [User Guide](../user-guide.md) for command-by-command usage. +- [Studio Roles](../studio-roles.md) for choosing a role. +- [Project Anatomy](../project-anatomy.md) for generated files. diff --git a/docs/project-anatomy.md b/docs/project-anatomy.md new file mode 100644 index 0000000..9e45cee --- /dev/null +++ b/docs/project-anatomy.md @@ -0,0 +1,88 @@ +# Project Anatomy + +Codex Game Studio projects are ordinary directories under `projects//`. The generated files are the contract between humans, Codex, validation, and later role runs. + +## Generated project tree + +A typical project starts like this: + +```text +projects/my-game/ + AGENTS.md + .codex/ + studio.json + context-manifest.json + prompts/ + workflows/ + runs/ + tasks.json + locks/ + studio/ + config.json + documentation/ + source/ + project-my-game/ +``` + +Exact files vary by engine, mode, and generated workflow state. + +## What humans edit + +Humans normally edit: + +- `documentation/` game-design and production docs; +- source files under `source/project-/`; +- explicit task descriptions in `.codex/tasks.json` when using task workflows; +- project customization in `.codex/studio/config.json`. + +Review changes to generated prompts and workflow files carefully. They carry freshness metadata that validation checks. + +## What agents read + +Codex roles read bounded context selected for the role and task. A role run may include: + +- project `AGENTS.md`; +- `.codex/studio.json`; +- selected generated role prompts; +- selected workflow prompts; +- relevant `documentation/` files; +- relevant templates; +- engine context and engine reference snippets. + +Codex Game Studio does not recursively dump the whole project into every prompt. + +## Important files + +| Path | Purpose | +| --- | --- | +| `AGENTS.md` | Generated project instructions for Codex. Owned by the CLI renderer. | +| `.codex/studio.json` | Project metadata, role roster, workflow IDs, workflow state, and validation contract. | +| `.codex/context-manifest.json` | Selected context-file manifest used to keep prompt context explicit. | +| `.codex/prompts/` | Generated role prompts for supported studio roles. | +| `.codex/workflows/` | Generated workflow prompts and recipes. | +| `.codex/runs/` | Prompt packets and run metadata produced by role execution. | +| `.codex/tasks.json` | File-backed task state for explicit task workflows. | +| `.codex/locks/` | Transient locks for bounded local orchestration. | +| `.codex/studio/config.json` | Optional project-local customization overlay. | +| `documentation/` | Starter game-design and production documents. | +| `source/project-/` | Engine project location contract. | + +## Repository assets that feed projects + +| Repository path | Purpose | +| --- | --- | +| `src/` | TypeScript CLI implementation. | +| `src/roles.ts` | Role-package registry compiled into the CLI. | +| `templates/` | Design, production, art, QA, release, analytics, and engine templates. | +| `engine_configs/` | Engine overlays for Godot, Unity, and Unreal. | +| `engine_reference/` | Curated engine reference packs selected by role and task. | +| `docs/` | Setup, migration, validation, architecture, and truth docs. | +| `tests/` | Vitest coverage for projects, prompts, templates, validation, runner behavior, engine behavior, and orchestration. | + +## Validation-sensitive surfaces + +Generated role prompts and workflow files include deterministic freshness metadata and rendered-body hashes. Validation compares those files against the current renderer and flags stale, malformed, or manually tampered surfaces. + +Project validation also checks starter docs, engine source markers, read-only command behavior, forbidden legacy artifacts, and future-only CLI drift. + +See [Workflow Validation](workflow-validation.md) for the full validation contract. diff --git a/docs/readmes/README.ja.md b/docs/readmes/README.ja.md new file mode 100644 index 0000000..73550dc --- /dev/null +++ b/docs/readmes/README.ja.md @@ -0,0 +1,79 @@ +# Codex Game Studio + +**Codex セッションを、構造化されたローカル優先のゲームスタジオに変える CLI。** + +[🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) + +Codex Game Studio は TypeScript 製の CLI です。ゲームプロジェクト用に、Codex が使いやすいワークスペースを作成します。ロールプロンプト、ワークフロープロンプト、プロジェクトファイル、タスク状態、検証情報は、Git でレビューできる通常のファイルとして保存されます。 + +これはゲームエンジンでも、ホステッドなプロジェクト管理サービスでもありません。Codex に明確な作業契約を与えつつ、創造的な判断とレビューは人間側に残します。 + +## クイックスタート + +Node.js 24 以上が必要です。`run ` には Codex CLI が必要です。 + +```sh +git clone git@github.com:merlinhu1/codex-game-studio.git +cd codex-game-studio +npm install +npm run build + +./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ + --concept "A compact puzzle game about routing trains through haunted switchyards" + +./codex-game-studio status --project projects/signal-cartographer +./codex-game-studio validate --project projects/signal-cartographer +``` + +Codex を起動する前に、ロールプロンプトを確認できます： + +```sh +./codex-game-studio run producer --project projects/signal-cartographer \ + "Create the initial market overview." --print-prompt +``` + +詳しいコマンド説明は英語の [User Guide](../user-guide.md) を参照してください。 + +## なぜ必要か + +空の AI コーディングチャットは柔軟ですが、ゲーム開発には反復可能なスタジオ構造が必要です： + +- プロデューサーにはマイルストーン、引き継ぎ、リリースチェックが必要です。 +- デザイナーには GDD、システム仕様、プレイヤージャーニー、チューニングループが必要です。 +- エンジニアには境界の明確な実装プロンプトと検証ゲートが必要です。 +- アート、QA、オーディオ、ローカライズ、ライブ運用にはそれぞれ専用の文脈が必要です。 +- レビュー担当者には、チャット履歴ではなく Git で確認できるファイルが必要です。 + +Codex Game Studio は、その構造をローカルなプロジェクト成果物に変換します。 + +## 得られるもの + +| 機能 | 意味 | +| --- | --- | +| ローカルプロジェクト生成 | `projects//` に決定的なゲームワークスペースを作成します。 | +| Codex ネイティブなスタジオロール | 制作、デザイン、エンジニアリング、アート、QA、ローカライズ、リリース用のロールプロンプトを生成します。 | +| ワークフロープロンプト | 市場調査、分析、仕様、引き継ぎ、出荷確認、UI レビューなどの再利用可能なプロンプトを提供します。 | +| エンジンオーバーレイ | Godot、Unity、Unreal の文脈を追加しますが、エンジンラッパーにはなりません。 | +| ファイルベースのタスク状態 | `.codex/**` にタスク、ロック、実行メタデータを保存します。 | +| 実行前の確認 | dry-run とプロンプト表示で、Codex 実行前に内容を確認できます。 | +| 厳格な検証 | 古い生成ファイル、不正なメタデータ、欠落アセット、未実装サーフェスの混入を検出します。 | + +## 詳しく読む + +| 目的 | ドキュメント | +| --- | --- | +| インストール、コマンド、ワークフロー、検証 | [User Guide](../user-guide.md) | +| ロールカタログ | [Studio Roles](../studio-roles.md) | +| 生成プロジェクト構造 | [Project Anatomy](../project-anatomy.md) | +| 利用例 | [Examples](../examples/README.md) | +| ドキュメント全体の地図 | [Docs Index](../README.md) | + +## プロジェクト状態 + +Codex Game Studio は現在、決定的なプロジェクト生成、Codex ロール実行、ワークフロープロンプト生成、ファイルベースのタスク編成、リポジトリ/プロジェクト検証をサポートしています。 + +planner または `next` コマンド、テレメトリ、ホステッド編成、無制限の並列処理、強制的な出力所有権、`CODEX.md` / `project_orchestrator.md` の生成は現在の製品境界外です。 + +## ライセンス + +Codex Game Studio は MIT License で公開されています。詳しくは [`LICENSE`](../../LICENSE) を参照してください。 diff --git a/docs/readmes/README.ko.md b/docs/readmes/README.ko.md new file mode 100644 index 0000000..79f75ac --- /dev/null +++ b/docs/readmes/README.ko.md @@ -0,0 +1,79 @@ +# Codex Game Studio + +**Codex 세션을 구조화된 로컬 우선 게임 스튜디오로 바꿉니다.** + +[🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) + +Codex Game Studio는 TypeScript CLI입니다. 게임 프로젝트를 위해 Codex가 바로 사용할 수 있는 워크스페이스를 만들고, 역할 프롬프트, 워크플로 프롬프트, 프로젝트 파일, 작업 상태, 검증 정보를 Git에서 리뷰 가능한 일반 파일로 저장합니다. + +이 도구는 게임 엔진도, 호스팅 프로젝트 관리자도 아닙니다. Codex에 더 명확한 작업 계약을 제공하면서 창작 결정과 최종 리뷰는 사람에게 남겨 둡니다. + +## 빠른 시작 + +Node.js 24 이상이 필요합니다. `run `에는 Codex CLI가 필요합니다. + +```sh +git clone git@github.com:merlinhu1/codex-game-studio.git +cd codex-game-studio +npm install +npm run build + +./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ + --concept "A compact puzzle game about routing trains through haunted switchyards" + +./codex-game-studio status --project projects/signal-cartographer +./codex-game-studio validate --project projects/signal-cartographer +``` + +Codex를 실행하기 전에 역할 프롬프트를 확인할 수 있습니다. + +```sh +./codex-game-studio run producer --project projects/signal-cartographer \ + "Create the initial market overview." --print-prompt +``` + +자세한 명령 설명은 영어 [User Guide](../user-guide.md)를 참고하세요. + +## 왜 필요한가 + +빈 AI 코딩 채팅은 유연하지만, 게임 개발에는 반복 가능한 스튜디오 구조가 필요합니다. + +- 프로듀서는 마일스톤, 핸드오프, 출시 체크가 필요합니다. +- 디자이너는 GDD, 시스템 명세, 플레이어 여정, 튜닝 루프가 필요합니다. +- 엔지니어는 경계가 명확한 구현 프롬프트와 검증 게이트가 필요합니다. +- 아트, QA, 오디오, 로컬라이제이션, 라이브 운영은 각자의 맥락이 필요합니다. +- 리뷰어는 채팅 기록이 아니라 Git에서 확인할 수 있는 파일이 필요합니다. + +Codex Game Studio는 이 구조를 Codex가 읽고 사람이 리뷰할 수 있는 로컬 프로젝트 산출물로 바꿉니다. + +## 제공하는 것 + +| 기능 | 의미 | +| --- | --- | +| 로컬 프로젝트 스캐폴딩 | `projects//` 아래에 결정적인 게임 워크스페이스를 만듭니다. | +| Codex 네이티브 스튜디오 역할 | 제작, 디자인, 엔지니어링, 아트, QA, 로컬라이제이션, 출시 작업용 역할 프롬프트를 생성합니다. | +| 워크플로 프롬프트 | 시장 리뷰, 분석, 명세, 핸드오프, 출시 체크, UI 리뷰 등 재사용 가능한 프롬프트를 제공합니다. | +| 엔진 오버레이 | Godot, Unity, Unreal 맥락을 추가하지만 엔진 래퍼가 되지는 않습니다. | +| 파일 기반 작업 상태 | `.codex/**` 아래에 작업, 잠금, 실행 메타데이터를 저장합니다. | +| 실행 전 검사 | dry-run과 프롬프트 출력으로 Codex 실행 전 내용을 확인할 수 있습니다. | +| 엄격한 검증 | 오래된 생성 파일, 잘못된 메타데이터, 누락 자산, 미래 기능 표면을 감지합니다. | + +## 더 읽기 + +| 필요 | 문서 | +| --- | --- | +| 설치, 명령, 워크플로, 검증 | [User Guide](../user-guide.md) | +| 역할 카탈로그 | [Studio Roles](../studio-roles.md) | +| 생성 프로젝트 구조 | [Project Anatomy](../project-anatomy.md) | +| 사용 예시 | [Examples](../examples/README.md) | +| 전체 문서 지도 | [Docs Index](../README.md) | + +## 프로젝트 상태 + +Codex Game Studio는 현재 결정적 프로젝트 스캐폴딩, Codex 역할 실행, 워크플로 프롬프트 렌더링, 파일 기반 작업 오케스트레이션, 저장소/프로젝트 검증을 지원합니다. + +planner 또는 `next` 명령, 텔레메트리, 호스팅 오케스트레이션, 무제한 병렬 처리, 강제 출력 소유권, `CODEX.md` / `project_orchestrator.md` 생성은 현재 제품 경계 밖입니다. + +## 라이선스 + +Codex Game Studio는 MIT License로 배포됩니다. [`LICENSE`](../../LICENSE)를 참조하세요. diff --git a/docs/readmes/README.zh.md b/docs/readmes/README.zh.md new file mode 100644 index 0000000..3183441 --- /dev/null +++ b/docs/readmes/README.zh.md @@ -0,0 +1,79 @@ +# Codex Game Studio + +**把一次 Codex 会话变成结构化、本地优先的游戏工作室。** + +[🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) + +Codex Game Studio 是一个 TypeScript CLI。它为游戏项目创建 Codex 可直接使用的工作区：角色提示词、工作流提示词、项目文件、任务状态和验证信息都保存在普通的、可通过 Git 审查的文件中。 + +它不是游戏引擎，也不是托管式项目管理器。它的目标是给 Codex 更清晰的工作契约，同时让创意决策和最终审查继续由人类掌握。 + +## 快速开始 + +需要 Node.js 24 或更新版本。`run ` 需要 Codex CLI。 + +```sh +git clone git@github.com:merlinhu1/codex-game-studio.git +cd codex-game-studio +npm install +npm run build + +./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ + --concept "A compact puzzle game about routing trains through haunted switchyards" + +./codex-game-studio status --project projects/signal-cartographer +./codex-game-studio validate --project projects/signal-cartographer +``` + +在真正运行 Codex 之前，可以先检查角色提示词： + +```sh +./codex-game-studio run producer --project projects/signal-cartographer \ + "Create the initial market overview." --print-prompt +``` + +详细命令说明见英文版 [User Guide](../user-guide.md)。 + +## 为什么需要它 + +空白 AI 编程聊天很灵活，但游戏开发需要更稳定的工作室结构： + +- 制作人需要里程碑、交接和发布检查。 +- 设计师需要 GDD、系统规格、玩家旅程和调参循环。 +- 工程师需要边界清晰的实现提示词和验证门槛。 +- 美术、QA、音频、本地化和运营也需要各自的上下文。 +- 审查者需要能在 Git 中检查的文件，而不是消失在聊天历史里的决策。 + +Codex Game Studio 把这些结构变成本地项目文件，让 Codex 能读取，也让人类能审查。 + +## 你会得到什么 + +| 能力 | 含义 | +| --- | --- | +| 本地项目脚手架 | 在 `projects//` 下创建确定性的游戏工作区。 | +| Codex 原生工作室角色 | 为制作、设计、工程、美术、QA、本地化和发布生成聚焦的角色提示词。 | +| 工作流提示词 | 提供市场、数据、规格、交接、发布检查、UI 审查等可复用提示词。 | +| 引擎覆盖层 | 添加 Godot、Unity 或 Unreal 上下文，但不把本项目变成引擎包装器。 | +| 文件化任务状态 | 在 `.codex/**` 下保存任务、锁和运行元数据。 | +| 执行前检查 | 支持 dry-run 和打印提示词，避免直接让 Codex 修改项目。 | +| 严格验证 | 检测过期生成文件、格式错误元数据、缺失资源和未来功能漂移。 | + +## 深入阅读 + +| 需要 | 文档 | +| --- | --- | +| 安装、命令、工作流和验证 | [User Guide](../user-guide.md) | +| 角色目录 | [Studio Roles](../studio-roles.md) | +| 生成项目结构 | [Project Anatomy](../project-anatomy.md) | +| 使用场景 | [Examples](../examples/README.md) | +| 完整文档地图 | [Docs Index](../README.md) | + +## 项目状态 + +Codex Game Studio 当前支持确定性项目脚手架、Codex 角色执行、工作流提示词渲染、文件化任务编排，以及仓库/项目验证。 + +它目前不提供 planner 或 `next` 命令、遥测、托管编排、无限并行、强制输出所有权，或生成 `CODEX.md` / `project_orchestrator.md`。 + +## 许可证 + +Codex Game Studio 使用 MIT License。见 [`LICENSE`](../../LICENSE)。 diff --git a/docs/setup.md b/docs/setup.md index 2be0b80..a1c2e53 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,5 +1,7 @@ # Setup +This is the short setup reference. For full command usage, see the [User Guide](user-guide.md). + ## Use from source checkout Clone the repository, install dependencies, build TypeScript output, and then run the checked-in CLI wrapper. Generated bundled CLI artifacts are not committed. @@ -17,7 +19,7 @@ npm run build ## Contributor development -Install npm dependencies when using or modifying Codex Game Studio from a source checkout. Development validation rebuilds TypeScript output before running checks. +Contributor workflow lives in [Development](development.md). ```bash npm install diff --git a/docs/standards/documentation-governance.md b/docs/standards/documentation-governance.md index a92e8d7..4b3d641 100644 --- a/docs/standards/documentation-governance.md +++ b/docs/standards/documentation-governance.md @@ -14,6 +14,8 @@ source_of_truth: - Each class of fact should have one canonical source. - Current implementation, reusable standards, and future proposals should be stored separately. - Generated helper output is never canonical truth. +- The root README is the concise human storefront; command reference, role catalog, generated-file detail, and contributor workflow detail belong in linked subdocs. +- Material root README changes should update localized README storefronts under `docs/readmes/` in the same change or state why they intentionally differ. - Architecture docs describe structure, ownership, and runtime views; truth docs describe current product behavior and remain the canonical behavior reference. - Architecture flow guides may explain branching logic and failure paths, but they must trace back to the owning truth docs rather than becoming a competing source of behavior truth. diff --git a/docs/studio-roles.md b/docs/studio-roles.md new file mode 100644 index 0000000..c8246b6 --- /dev/null +++ b/docs/studio-roles.md @@ -0,0 +1,88 @@ +# Studio Roles + +Codex Game Studio generates Codex-native role prompts for common game-studio disciplines. Role IDs are hyphenated and stable. Unsupported legacy underscore IDs are rejected instead of silently mapped. + +Use this catalog to choose a role before calling `run `. + +## Direction and production + +| Role | Use it for | +| --- | --- | +| `studio-orchestrator` | Coordinating a bounded slice across roles and handoffs. | +| `producer` | Milestones, production planning, priority calls, and market-facing summaries. | +| `release-manager` | Release readiness, ship checks, handoff quality, and launch coordination. | + +## Market and analytics + +| Role | Use it for | +| --- | --- | +| `market-analyst` | Competitor review, positioning, audience fit, store-page risks, and market summaries. | +| `data-scientist` | Telemetry plans, analytics questions, experiment design, and metrics interpretation. | + +## Design and writing + +| Role | Use it for | +| --- | --- | +| `creative-director` | Pillars, tone, experience direction, and cross-discipline creative alignment. | +| `senior-game-designer` | Systems direction, design cohesion, and high-level gameplay decisions. | +| `game-designer` | GDD sections, mechanics, rules, progression, and feature design. | +| `narrative-designer` | Narrative systems, quest structure, story-gameplay integration. | +| `writer` | Dialogue, prose, descriptions, and voice/tone work. | +| `world-builder` | Setting, factions, locations, lore, and world consistency. | +| `level-designer` | Level goals, encounter flow, spatial pacing, and layout specs. | +| `game-feel-designer` | Moment-to-moment feel, tuning targets, juice, responsiveness, and experiential checks. | +| `systems-designer` | Interlocking systems, economies, progression, constraints, and balancing models. | +| `economy-designer` | Currencies, sinks/sources, pricing, reward loops, and economy risks. | + +## Engineering + +| Role | Use it for | +| --- | --- | +| `gameplay-programmer` | Gameplay implementation plans, feature code, and mechanics integration. | +| `ai-programmer` | NPC behavior, decision logic, navigation, perception, and combat AI. | +| `network-programmer` | Multiplayer architecture, synchronization, rollback, replication, and latency concerns. | +| `ui-programmer` | UI implementation, menus, HUD, state binding, and input/accessibility integration. | +| `engine-programmer` | Engine-level systems, performance-sensitive architecture, and low-level integration. | +| `tools-programmer` | Editor tools, pipelines, scripts, importers, and production automation. | +| `technical-director` | Technical architecture, constraints, feasibility reviews, and cross-system decisions. | +| `devops-engineer` | Build, CI, release automation, packaging, and environment workflow. | +| `security-engineer` | Threat models, abuse cases, credential handling, and multiplayer/backend risks. | +| `performance-analyst` | Profiling plans, optimization hypotheses, budgets, and bottleneck analysis. | + +## Engine specialists + +| Role | Use it for | +| --- | --- | +| `godot-specialist` | Godot-specific architecture, APIs, project layout, and version-sensitive guidance. | +| `unity-specialist` | Unity-specific architecture, packages, scenes/prefabs, and C# guidance. | +| `unreal-specialist` | Unreal-specific architecture, modules, Blueprints/C++, plugins, and content workflow. | + +## Art, audio, and UX + +| Role | Use it for | +| --- | --- | +| `senior-game-artist` | Art direction, asset planning, style guides, and visual production constraints. | +| `technical-artist` | Shaders, pipelines, asset integration, VFX, optimization, and DCC-engine bridges. | +| `audio-director` | Audio direction, music/sound strategy, mix priorities, and implementation needs. | +| `sound-designer` | SFX concepts, interactive audio details, event naming, and feedback loops. | +| `ui-ux-designer` | UX flows, HUD/menu design, player journeys, wireframes, and usability review. | +| `accessibility-specialist` | Accessibility risks, input alternatives, readability, audio/visual cues, and inclusive design. | + +## QA, localization, and operations + +| Role | Use it for | +| --- | --- | +| `qa-playtester` | Test plans, playtest notes, bug-risk reviews, and acceptance criteria. | +| `localization-lead` | Localization planning, string risks, culturalization, and translation handoff. | +| `live-ops-designer` | Events, retention loops, progression cadence, and live-service content planning. | +| `community-manager` | Community-facing messaging, feedback triage, and communication plans. | + +## Choosing a role + +- Use `producer` when the question is priority, milestone, or scope. +- Use `creative-director` or `senior-game-designer` when the question changes the player promise. +- Use an engine specialist when the implementation depends on Godot, Unity, or Unreal details. +- Use `qa-playtester` or `release-manager` before trusting a feature as shippable. +- Use `studio-orchestrator` only for bounded cross-role slices; do not use it as a general autonomous manager. + +See the [User Guide](user-guide.md) for `run ` usage and inspection flags. diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000..7bf41e4 --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,180 @@ +# 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. It writes game-project workspaces under `projects//` 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 ` 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 ` 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 --project projects/my-game +./codex-game-studio validate --project projects/my-game +``` + +## 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 --project projects/my-game +./codex-game-studio resume --project projects/my-game +``` + +`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 --project projects/my-game +./codex-game-studio ship-check --project projects/my-game +``` + +Workflow shortcuts render focused prompts. They do not launch Codex unless you explicitly use `run ` or a task execution command. + +### Run a studio role + +```sh +./codex-game-studio run producer --project projects/my-game \ + "Create the initial market overview." +``` + +Inspect first when the task is risky or broad: + +```sh +./codex-game-studio run producer --project projects/my-game \ + "Create the initial market overview." --dry-run + +./codex-game-studio run producer --project projects/my-game \ + "Create the initial market overview." --print-prompt +``` + +`run ` 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 --project projects/my-game +``` + +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` | Create a project under `projects//`. | +| `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 ` | Print a packaged template. | +| `run ` | 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 ` | 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 ` 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 ` 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.