From b9275b809a01a8a75f9fb8c7d5a59bd5dbc5608e Mon Sep 17 00:00:00 2001 From: MerlinH Date: Sun, 31 May 2026 01:16:00 +0000 Subject: [PATCH] docs: polish Open Game Studio README --- README.md | 222 ++++++++++++------ docs/architecture/flows/README.md | 2 +- .../flows/validation-and-repository-truth.md | 10 +- docs/architecture/repository-structure.md | 2 +- .../codex-game-studio-deep-integration.md | 4 +- docs/truth/codex/roles-and-workflows.md | 2 +- docs/truth/repository/overview.md | 6 +- 7 files changed, 164 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 7b417cf..38f8663 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,75 @@ -# Open GameStudio +# Open Game Studio -Codex Game Studio is a Node/TypeScript CLI package for creating and managing local, Codex-assisted game projects. It provides project scaffolding, engine-aware Codex context, role prompts, reusable templates, file-backed tasks, and validation gates that keep generated project artifacts predictable. +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json) +[![TypeScript](https://img.shields.io/badge/TypeScript-NodeNext-3178c6.svg)](tsconfig.json) -The package is a Codex-native workflow layer for game making. It keeps project state local and inspectable under `.codex/`, invokes `codex exec` by default for role-specific work, and uses `--dry-run` or `--print-prompt` for non-executing inspection. +Open Game Studio is a Codex-native command line studio for making games with AI agents without hiding the workflow in a black box. -## Why This Exists +Create a local game project, generate Codex-ready role prompts, hand focused work to a studio role, then validate the project artifacts before you trust them. The state lives in your repository under `.codex/`; generated games live under `projects//`; normal execution goes through `codex exec`. -Open GameStudio started as a port motivated by a simple need: make the game-studio workflow open, portable, local-first, scriptable, and usable outside a single assistant environment. +```sh +npm run init -- --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ + --concept "A compact puzzle game about routing trains through haunted switchyards" -Claude Game Studio deserves real kudos for proving that role-based game-development workflows can be practical and useful. Open GameStudio is inspired by that idea, but it is an independent implementation with different priorities: +node dist/cli.js run producer --project projects/signal-cartographer \ + "Create the initial market overview." -- CLI and package first, with deterministic npm scripts for local development. -- Codex-native by default, with direct `codex exec` integration for role-specific work. -- Generated game projects live under `projects//`. -- Engine configs, templates, and base agents are package assets. -- Validation is explicit and hard-failing instead of advisory. -- Prompt packets are optimized for Codex and execute by default through `run `. -- Telemetry, planner/`next`, ownership enforcement, changed-file tracking, and parallel orchestration are future-only. +npm run validate -- --project projects/signal-cartographer +``` -The goal is not to clone another tool. The goal is to make the workflow contract inspectable, portable, and easy to run in normal developer tooling. +## Why developers use it + +Open Game Studio gives game teams a repeatable way to work with Codex across design, production, engineering, art, QA, and release tasks. + +- Local-first project state. No hosted planner, hidden queue, or opaque database. +- Codex-native instructions in generated `AGENTS.md` and `.codex/prompts/.md` files. +- Role-specific context packets instead of dumping every template into every task. +- Hard-failing validation for generated prompts, workflows, package assets, and project contracts. +- Inspection paths with `--dry-run` and `--print-prompt` before Codex touches the workspace. +- Engine scaffolding for Godot, Unity, and Unreal projects. + +This is not a game engine and it is not a replacement for human creative direction. It is a workflow layer: a small, inspectable CLI that turns studio roles and production documents into bounded Codex work. + +## The studio loop + +```mermaid +flowchart LR + A[init project] --> B[projects/slug] + B --> C[.codex studio state] + C --> D[generated role prompts] + D --> E[run role with Codex] + E --> F[review, fix, verify] + F --> G[validate project] + G --> D +``` + +A generated project contains the working contract Codex needs: project summary, engine context, role prompts, workflow prompts, starter production docs, and validation metadata. Role runs prepare a bounded prompt packet under `.codex/runs/` and invoke `codex exec` from the project root. ## Requirements - Node.js 20 or newer. - npm. -- Codex CLI for normal execution and repository validation. +- Codex CLI available on `PATH` for normal `run ` execution and full validation. -## Install +## Install from source -For package use after installation or linking: +```sh +git clone git@github.com:merlinhu1/open-gamestudio.git +cd open-gamestudio +npm install +npm run build +node dist/cli.js --help +``` + +For package use after installing or linking the package: ```sh npm exec open-gamestudio -- --help npm exec open-gamestudio -- templates list ``` -For local development from this repository, use the npm scripts. They build first and then exercise the built CLI through `node dist/cli.js`: +For local development from this checkout, prefer the npm scripts. They build first and exercise the built CLI through `node dist/cli.js`: ```sh npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive @@ -44,106 +78,150 @@ npm run templates -- list npm run validate -- --project projects/my-game ``` -## Quick Start +## Quick start -Create a project: +### 1. Create a project ```sh -npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive --concept "A compact puzzle game about routing trains" +npm run init -- --name "My Game" --engine godot --mode prototype --non-interactive \ + --concept "A compact puzzle game about routing trains" ``` -Inspect project status: +Open Game Studio creates `projects/my-game/` with engine markers, starter docs, `.codex/studio.json`, generated role prompts, generated workflow prompts, and a project-level `AGENTS.md`. + +### 2. Inspect the project ```sh npm run manage -- --project projects/my-game +node dist/cli.js resume --project projects/my-game ``` -List templates: +`status` and `resume` are read-only. `freeze` is the explicit command that changes project status. + +### 3. Choose a template or workflow ```sh npm run templates -- list +npm run templates -- show gdd +node dist/cli.js market --project projects/my-game +node dist/cli.js ship-check --project projects/my-game ``` -Show a template: +Workflow shortcuts render prompts only. They do not launch Codex. + +### 4. Run a studio role through Codex ```sh -npm run templates -- show gdd +npm run build --silent +node dist/cli.js run producer --project projects/my-game \ + "Create the initial market overview." ``` -Validate the repository or a generated project: +Want to see exactly what Codex will receive first? + +```sh +node dist/cli.js run producer --project projects/my-game \ + "Create the initial market overview." --dry-run + +node dist/cli.js run producer --project projects/my-game \ + "Create the initial market overview." --print-prompt +``` + +`run ` inlines the generated project role prompt from `.codex/prompts/.md` and only the package templates selected for that role and task. `--allow-broad-context` adds bounded discovery for existing project artifacts such as the GDD, production timeline, market overview, `AGENTS.md`, and `.codex/studio.json`; it does not recursively load the whole project. + +### 5. Validate before relying on output ```sh npm run validate npm run validate -- --project projects/my-game ``` -Run a project agent through Codex: +Validation exits nonzero on failure. It checks package contracts, template availability, forbidden future surfaces, build output, project state, generated-surface freshness metadata, rendered-body hashes, and stale or tampered generated prompt/workflow files. -```sh -npm run build --silent -node dist/cli.js run producer --project projects/my-game "Create the initial market overview." -``` +## Commands -Inspect the generated prompt packet without executing Codex: +| 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. | +| `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` by default. | +| `task create` / `task run` | Manage file-backed `.codex/tasks.json` tasks. | +| `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff` | Render focused workflow prompts. | +| `review`, `ship-check` | Render baseline review and release-check prompts. | -```sh -node dist/cli.js run producer --project projects/my-game "Create the initial market overview." --dry-run -``` +## Studio roles -The `run` command writes a bounded prompt packet and immediately invokes `codex exec` in the project root. The packet inlines the generated project role prompt from `.codex/prompts/.md` and only the package templates selected for that role and task. `--fix` uses the same generated role prompt and selected templates as the primary implementation prompt. Use `--dry-run` or `--print-prompt` when you want to inspect the exact Codex context first. +Open Game Studio ships a Codex-native role roster with hyphenated IDs: -`--allow-broad-context` adds bounded project artifact discovery for existing files such as the GDD, production timeline, market overview, `AGENTS.md`, and `.codex/studio.json`; it does not recursively load every prompt, workflow, or template. +| 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`, `game-feel-designer` | +| Engineering | `gameplay-programmer`, `engine-programmer`, `tools-programmer` | +| Art and interface | `senior-game-artist`, `technical-artist`, `ui-ux-designer` | +| Quality | `qa-playtester` | -## CLI Commands +Legacy underscore role IDs are intentionally rejected. `narrative-designer` is a first-class story and content owner. -- `init` / `new`: create a project under `projects//`. -- `status`: print project phase, status, engine, and next validation command. -- `resume`: print a read-only continuation summary. -- `freeze`: mark a project as frozen. -- `validate`: run repository or project validation and exit nonzero on failure. -- `templates list`: list packaged template IDs. -- `templates show `: print a packaged template. -- `run `: prepare one bounded Codex prompt packet for a studio role and invoke `codex exec` by default. -- `task create` / `task run`: manage file-backed `.codex/tasks.json` tasks. -- `review`, `ship-check`: render existing baseline Codex workflow prompts. -- `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff`: render workflow prompts only; these shortcuts do not launch Codex. - -## Studio Roles - -The Codex-native role roster is `studio-orchestrator`, `producer`, `market-analyst`, `data-scientist`, `creative-director`, `senior-game-designer`, `game-designer`, `narrative-designer`, `game-feel-designer`, `gameplay-programmer`, `engine-programmer`, `tools-programmer`, `senior-game-artist`, `technical-artist`, `ui-ux-designer`, `qa-playtester`, and `release-manager`. - -This preserves Claude Game Studio functional coverage without legacy underscore role IDs. `narrative-designer` remains a first-class Codex-native story/content owner. - -Supported aliases remain intentional: `new` is an alias for `init`, and registered workflow shortcuts render their prompts. Unsupported upstream or legacy underscore role IDs are rejected. - -## Project Layout +## What gets generated Repository assets: - `src/`: TypeScript CLI implementation. - `src/roles.ts`: Codex role packages compiled into the CLI. -- `templates/`: reusable document and setup templates. +- `templates/`: reusable design, production, art, QA, release, analytics, and engine templates. - `engine_configs/`: engine overlays for Godot, Unity, and Unreal. -- `docs/`: setup, migration, validation, and example notes. +- `docs/`: migration, validation, truth, and compatibility notes. - `tests/`: Vitest coverage for project workflow, templates, agents, runner prompts, validation, and engine behavior. -Generated project artifacts: +Project artifacts: -- `projects//`: the project root created by `init`. +- `projects//`: generated project root. - `AGENTS.md`: primary generated Codex project instructions, owned by `src/agents.ts`. -- `.codex/studio.json`: authoritative project metadata and workflow state. +- `.codex/studio.json`: project metadata, role roster, workflow IDs, and workflow state. - `.codex/prompts/`: generated role prompts. - `.codex/workflows/`: generated workflow prompts. -- `.codex/runs/`: prepared prompt packets and run metadata. -- `documentation/`: generated game-design and workflow documents. +- `.codex/runs/`: prepared prompt packets and run metadata from non-dry role runs. +- `.codex/tasks.json`: file-backed task state when you use `task create` or `task run`. +- `documentation/`: starter game-design and production documents. - `source/project-/`: engine project location contract. -Generated role prompts and workflow files include deterministic freshness metadata and rendered-body hashes. Project validation checks new generated surfaces for stale registry inputs or manual body tampering, and reports legacy generated files without metadata as regeneration-needed skip diagnostics rather than silently treating them as fresh. +Generated role prompts and workflow files carry deterministic freshness metadata and rendered-body hashes. New project validation compares those files against the current renderer and flags stale, malformed, or manually tampered surfaces. + +## Current boundaries + +Open Game Studio is intentionally narrow right now. + +Implemented: + +- deterministic project scaffolding; +- generated Codex role and workflow surfaces; +- direct `codex exec` role execution; +- dry-run and prompt-print inspection; +- file-backed tasks; +- bounded review, verification, and fix-pass options; +- hard-failing repository and project validation. + +Future-only, not exposed as working features: + +- planner/`next`; +- telemetry; +- parallel orchestration; +- changed-file tracking; +- hard output-ownership enforcement; +- legacy `.gamestudio` compatibility; +- 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 the detailed migration contract. ## Development -Use the repository scripts: - ```sh npm run build npm run typecheck @@ -151,8 +229,10 @@ npm run test npm run validate ``` -This project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include the emitted `.js` specifier. +The project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include the emitted `.js` specifier. + +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. ## License -Open GameStudio is released under the MIT License. See `LICENSE`. +Open Game Studio is released under the MIT License. See [`LICENSE`](LICENSE). diff --git a/docs/architecture/flows/README.md b/docs/architecture/flows/README.md index 1a33be8..27dce29 100644 --- a/docs/architecture/flows/README.md +++ b/docs/architecture/flows/README.md @@ -12,7 +12,7 @@ source_of_truth: ## Purpose -These Architecture Flow Guides document Open GameStudio's important runtime scenarios, branching logic, failure paths, and code/truth-doc traceability. They are Markdown docs-as-code runtime views: readable in GitHub/VS Code, reviewable in pull requests, and detailed enough to guide humans and agents through the system. +These Architecture Flow Guides document Open Game Studio's important runtime scenarios, branching logic, failure paths, and code/truth-doc traceability. They are Markdown docs-as-code runtime views: readable in GitHub/VS Code, reviewable in pull requests, and detailed enough to guide humans and agents through the system. ## Professional Framing diff --git a/docs/architecture/flows/validation-and-repository-truth.md b/docs/architecture/flows/validation-and-repository-truth.md index 7f4f80c..03198df 100644 --- a/docs/architecture/flows/validation-and-repository-truth.md +++ b/docs/architecture/flows/validation-and-repository-truth.md @@ -13,9 +13,9 @@ source_of_truth: ## Purpose -This architecture flow guide documents the validation path around Open GameStudio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates. +This architecture flow guide documents the validation path around Open Game Studio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates. -Validation is an Open GameStudio CLI/package behavior. Truthmark is an injected repository-truth workflow/tooling layer for documentation authority, routing, and agent workflow surfaces; it is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior. +Validation is an Open Game Studio CLI/package behavior. Truthmark is an injected repository-truth workflow/tooling layer for documentation authority, routing, and agent workflow surfaces; it is not an Open Game Studio runtime feature unless product code explicitly implements Truthmark-facing behavior. ## Scope @@ -28,7 +28,7 @@ The guide ends when validation/truth checks have either passed or produced diagn ## Boundaries -Repository validation is an Open GameStudio package behavior implemented by the CLI and validation modules. Truthmark checks are an injected repository-truth workflow/tooling layer for documentation authority and generated agent surfaces, not an Open GameStudio runtime feature. +Repository validation is an Open Game Studio package behavior implemented by the CLI and validation modules. Truthmark checks are an injected repository-truth workflow/tooling layer for documentation authority and generated agent surfaces, not an Open Game Studio runtime feature. ## Entry Points @@ -107,7 +107,7 @@ flowchart TD | Condition | Branch | Required action | Output/diagnostic | Owner | | --- | --- | --- | --- | --- | -| Source/package behavior changed | Functional validation branch | Run relevant tests and `npm run validate`. | Failing package/project check if contract is broken. | Open GameStudio repo | +| Source/package behavior changed | Functional validation branch | Run relevant tests and `npm run validate`. | Failing package/project check if contract is broken. | Open Game Studio repo | | Generated project behavior changed | Project validation branch | Validate generated-project contracts. | Missing/invalid generated surface diagnostic. | `src/validation.ts` and scaffold owners | | Public CLI claim changed | CLI contract branch | Update contract truth doc and validation/readme claims together. | Validation or doc drift if missed. | `docs/truth/contracts/cli-and-validation.md` | | Behavior claim changed | Truth sync branch | Update owning bounded truth doc. | Truthmark may flag stale/unmapped surfaces. | Truthmark docs workflow | @@ -140,7 +140,7 @@ flowchart TD ## Product Decisions - `npm run validate` remains the readiness gate before repository parity claims. -- Truthmark checks validate repository-truth routing and generated workflow surfaces without redefining Open GameStudio runtime behavior. +- Truthmark checks validate repository-truth routing and generated workflow surfaces without redefining Open Game Studio runtime behavior. - Markdown truth docs remain canonical; generated portal HTML remains non-canonical presentation. ## Rationale diff --git a/docs/architecture/repository-structure.md b/docs/architecture/repository-structure.md index 9069a95..7985713 100644 --- a/docs/architecture/repository-structure.md +++ b/docs/architecture/repository-structure.md @@ -11,7 +11,7 @@ source_of_truth: ## Purpose -Open GameStudio is a Node/TypeScript CLI package that installs and operates Codex-native game studio project workflows. +Open Game Studio is a Node/TypeScript CLI package that installs and operates Codex-native game studio project workflows. ## Scope diff --git a/docs/plans/codex-game-studio-deep-integration.md b/docs/plans/codex-game-studio-deep-integration.md index f0b8fdd..bd572c9 100644 --- a/docs/plans/codex-game-studio-deep-integration.md +++ b/docs/plans/codex-game-studio-deep-integration.md @@ -2,7 +2,7 @@ > **For Hermes:** Do not implement this plan until Merlin explicitly approves it. When approved, use subagent-driven-development skill to implement this plan task-by-task. Do not rewrite git history or push commits unless Merlin explicitly asks. -**Goal:** Reorient Open GameStudio into a Codex-native game-development workflow layer, even if that reduces compatibility with Claude Code, OpenCode, or generic agent backends. +**Goal:** Reorient Open Game Studio into a Codex-native game-development workflow layer, even if that reduces compatibility with Claude Code, OpenCode, or generic agent backends. **Architecture:** Codex becomes the required runtime spine rather than an optional `--exec` backend. The CLI routes studio roles and workflows through a structured Codex session model, generated projects gain Codex-native instruction/state files, and validation checks Codex readiness plus prompt/workflow rendering. Keep the first implementation file-backed and package-friendly; defer databases, parallel orchestration, and broad backend abstractions until they are proven necessary. @@ -210,7 +210,7 @@ Add tests for: - `resolveCodexCommand()` uses `CODEX_BIN` if provided. - `resolveCodexCommand()` defaults to `codex`. -- `resolveCodexCommand()` does not read legacy Open GameStudio env names. +- `resolveCodexCommand()` does not read legacy Open Game Studio env names. - `buildCodexExecArgs()` uses `exec`, `--cd `, sandbox args, and stdin/file prompt mode. - `checkCodexAvailability()` returns structured diagnostics for tests and error messages. - normal execution and `validate` fail hard when Codex is unavailable or unauthenticated. diff --git a/docs/truth/codex/roles-and-workflows.md b/docs/truth/codex/roles-and-workflows.md index 9b4aac9..c394317 100644 --- a/docs/truth/codex/roles-and-workflows.md +++ b/docs/truth/codex/roles-and-workflows.md @@ -11,7 +11,7 @@ source_of_truth: ## Purpose -Codex roles and workflows provide the role-specific prompt contracts, context boundaries, templates, and render-only workflow shortcuts that make Open GameStudio a Codex-native game-development layer. +Codex roles and workflows provide the role-specific prompt contracts, context boundaries, templates, and render-only workflow shortcuts that make Open Game Studio a Codex-native game-development layer. ## Scope diff --git a/docs/truth/repository/overview.md b/docs/truth/repository/overview.md index 36cd44c..e61f890 100644 --- a/docs/truth/repository/overview.md +++ b/docs/truth/repository/overview.md @@ -12,7 +12,7 @@ source_of_truth: ## Purpose -Open GameStudio exists as a Codex-native workflow layer for game-development projects. The repository packages a TypeScript CLI that scaffolds game projects, renders role/workflow prompts for Codex, executes bounded Codex run lifecycles, and validates both repository and generated-project contracts. +Open Game Studio exists as a Codex-native workflow layer for game-development projects. The repository packages a TypeScript CLI that scaffolds game projects, renders role/workflow prompts for Codex, executes bounded Codex run lifecycles, and validates both repository and generated-project contracts. ## Scope @@ -32,7 +32,7 @@ This bounded leaf truth doc summarizes the repository-level behavior surface. Mo - Repository behavior is grouped by behavior ownership rather than by mechanically mirroring every source file. - Generated project instruction contracts use Codex-native `AGENTS.md`; the repository does not introduce `CODEX.md` as a primary instruction contract. - Runtime execution is explicit: dry-run and print-prompt modes are inspection paths, while non-dry runs write prompt/run metadata before executing Codex. -- Truthmark is an injected repository-truth workflow/tooling layer for agent surfaces and documentation routing. It is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior. +- Truthmark is an injected repository-truth workflow/tooling layer for agent surfaces and documentation routing. It is not an Open Game Studio runtime feature unless product code explicitly implements Truthmark-facing behavior. ## Flows And States @@ -58,7 +58,7 @@ Architecture runtime walkthroughs live under `docs/architecture/flows/**`; they ## Rationale -The repository combines scaffolding, prompt generation, runtime execution, and validation in one package. Keeping those surfaces bounded makes the architecture easier to reason about and prevents generated agent workflow scaffolding from being mistaken for user-facing Open GameStudio product behavior. +The repository combines scaffolding, prompt generation, runtime execution, and validation in one package. Keeping those surfaces bounded makes the architecture easier to reason about and prevents generated agent workflow scaffolding from being mistaken for user-facing Open Game Studio product behavior. ## Non-Goals