mirror of
https://github.com/merlinhu1/codex-game-studio.git
synced 2026-08-25 07:54:34 +02:00
docs: reorganize README into docs guide
This commit is contained in:
MerlinH
@@ -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)
|
||||
[](package.json)
|
||||
[](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/<slug>/`. |
|
||||
| Codex-native role prompts | Generates `.codex/prompts/<role>.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 <role>` 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 <role>` and full validation.
|
||||
Requirements: Node.js 24 or newer. The Codex CLI is required for `run <role>`.
|
||||
|
||||
```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/<slug>/`. |
|
||||
| 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 <role>` 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 <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.
|
||||
|
||||
### 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/<slug>/`. |
|
||||
| `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. |
|
||||
| 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/<slug>/`: 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-<slug>/`: 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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+2
-31
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,88 @@
|
||||
# Project Anatomy
|
||||
|
||||
Codex Game Studio projects are ordinary directories under `projects/<slug>/`. 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-<slug>/`;
|
||||
- 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-<slug>/` | 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.
|
||||
@@ -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 <role>` には 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/<slug>/` に決定的なゲームワークスペースを作成します。 |
|
||||
| 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) を参照してください。
|
||||
@@ -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 <role>`에는 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/<slug>/` 아래에 결정적인 게임 워크스페이스를 만듭니다. |
|
||||
| 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)를 참조하세요.
|
||||
@@ -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 <role>` 需要 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/<slug>/` 下创建确定性的游戏工作区。 |
|
||||
| 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)。
|
||||
+3
-1
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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 <role>`.
|
||||
|
||||
## 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 <role>` usage and inspection flags.
|
||||
@@ -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/<slug>/` 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.
|
||||
|
||||
```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 <role>` 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 <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 --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/<slug>/`. |
|
||||
| `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.
|
||||
Reference in New Issue
Block a user