diff --git a/README.md b/README.md index f56bc1e..30bd3ee 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # Codex Game Studio +**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. + [![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) -Codex Game Studio is a Codex-native command line studio for making games with AI agents without hiding the workflow in a black box. - -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`. - ```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" @@ -18,90 +18,89 @@ Create a local game project, generate Codex-ready role prompts, hand focused wor ./codex-game-studio validate --project projects/signal-cartographer ``` -## Why developers use it +## Why this exists -Codex Game Studio gives game teams a repeatable way to work with Codex across design, production, engineering, art, QA, and release tasks. +Working with one general-purpose AI coding session is powerful, but game development needs more structure than a blank chat box: -- 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. +- 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. -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. +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. -## The studio loop +## What you get -```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 -``` +| 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. | -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. +## Quick start from a source checkout -## Requirements +Requirements: - Node.js 24 or newer. -- Codex CLI available on `PATH` for normal `run ` execution and full validation. - -## Use from source checkout - -Codex Game Studio uses the normal source-checkout path: clone the repo, install dependencies, build TypeScript, then run the local CLI wrapper. The repository does not commit generated bundled CLI artifacts. +- 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 -./codex-game-studio init --name "My Game" --engine godot --mode prototype --non-interactive ``` -For package use after publishing, installing, or linking the package: - -```sh -npm exec codex-game-studio -- --help -npm exec codex-game-studio -- templates list -``` - -For contributor development on Codex Game Studio itself, use npm scripts. They install developer dependencies, rebuild TypeScript output, and run validation: - -```sh -npm install -npm run build -npm run typecheck -npm test -npm run validate -``` - -## Quick start - -### 1. Create a project +Create and validate 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 ``` -Codex 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`. +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`. -### 2. Inspect the project +## 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] + 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. + +## Daily workflow + +### 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. -### 3. Choose a template or workflow +### 2. Use templates and workflow prompts ```sh ./codex-game-studio templates list @@ -110,16 +109,16 @@ Codex Game Studio creates `projects/my-game/` with engine markers, starter docs, ./codex-game-studio ship-check --project projects/my-game ``` -Workflow shortcuts render prompts only. They do not launch Codex. +Workflow shortcuts render focused prompts. They do not launch Codex unless you explicitly use `run ` or a task execution command. -### 4. Run a studio role through Codex +### 3. Run a studio role ```sh ./codex-game-studio run producer --project projects/my-game \ "Create the initial market overview." ``` -Want to see exactly what Codex will receive first? +Inspect first when the task is risky or broad: ```sh ./codex-game-studio run producer --project projects/my-game \ @@ -129,16 +128,16 @@ Want to see exactly what Codex will receive first? "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. +`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. -### 5. Validate before relying on output +### 4. Validate before trusting output ```sh ./codex-game-studio validate ./codex-game-studio validate --project projects/my-game ``` -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. +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 @@ -147,103 +146,118 @@ Validation exits nonzero on failure. It checks package contracts, template avail | `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` and its freshness metadata after selected context files change. | +| `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` by default. | -| `task create` / `task run` / `task orchestrate` | Manage file-backed `.codex/tasks.json` tasks and run explicit local bounded orchestration. | -| `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. | -| `workflow create-tasks ` | Create explicit file-backed tasks from supported workflow recipes such as `vertical-slice`, `bugfix`, `ui-ux-review`, and `release-checklist`. | +| `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. | ## Studio roles -Codex Game Studio ships a Codex-native role roster with hyphenated IDs: - | 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` | +| 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` | -Legacy underscore role IDs are intentionally rejected. `narrative-designer` is a first-class story and content owner. +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`: Codex role packages compiled into the CLI. -- `templates/`: reusable design, production, art, QA, release, analytics, and engine templates. +- `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. -- `docs/`: migration, validation, truth, and compatibility notes. -- `tests/`: Vitest coverage for project workflow, templates, agents, runner prompts, validation, and engine behavior. +- `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. -Project artifacts: +Generated project assets: - `projects//`: generated project root. -- `AGENTS.md`: primary generated Codex project instructions, owned by `src/agents.ts`. +- `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/`: prepared prompt packets, per-task orchestration output, and run metadata from non-dry role or orchestration runs. -- `.codex/locks/`: transient file-backed locks for bounded parallel task orchestration. -- `.codex/tasks.json`: file-backed task state when you use `task create`, `task run`, workflow task recipes, or `task orchestrate`. +- `.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. New project validation compares those files against the current renderer and flags stale, malformed, or manually tampered surfaces. +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. -## Current boundaries +## Design boundaries -Codex Game Studio is intentionally narrow right now. +Codex Game Studio is a local workflow layer, not a game engine and not an autonomous studio manager. -Implemented: +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; -- explicit local task orchestration with bounded `--max-concurrency` and file-backed locks; +- file-backed tasks and bounded local orchestration; - workflow task recipes for selected high-value workflows; -- curated CCGS adaptation registry for role/skill/workflow translation decisions; -- bounded review, verification, and fix-pass options; +- curated CCGS adaptation decisions; - hard-failing repository and project validation. -Future-only, not exposed as working features: +Not exposed as working features: -- planner/`next`; +- planner or `next` command; - telemetry; - changed-file tracking; - hosted/background orchestration; - unbounded parallelism; - hard output-ownership enforcement; -- legacy `.gamestudio` compatibility; - generated `CODEX.md` or `project_orchestrator.md` surfaces. -Explicit local task orchestration is now inside the product boundary, but user-facing runtime claims require implementation, tests, and docs. +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. -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. +## 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 run test +npm test npm run validate ``` -The project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include the emitted `.js` specifier. +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) + ## License Codex Game Studio is released under the MIT License. See [`LICENSE`](LICENSE). diff --git a/docs/truthmark/engineering/contracts/cli-and-validation.md b/docs/truthmark/engineering/contracts/cli-and-validation.md index 67e4ec4..33797a2 100644 --- a/docs/truthmark/engineering/contracts/cli-and-validation.md +++ b/docs/truthmark/engineering/contracts/cli-and-validation.md @@ -37,7 +37,7 @@ It does not own project scaffolding internals, role prompt content, or Codex run - Package name: `codex-game-studio`. - Package bin: `codex-game-studio` points to `./dist/cli.js`. -- Package bin also keeps `opengamestudio` as a compatibility alias to the same built entrypoint. +- No legacy package bin aliases are exposed. - Primary scripts include `build`, `typecheck`, `test`, `validate`, `init`, `manage`, and `templates`. - Source checkout usage requires `npm install && npm run build`, then goes through `./codex-game-studio`. - Public command groups include initialization and status commands. diff --git a/opengamestudio b/opengamestudio deleted file mode 100755 index 32fd2c4..0000000 --- a/opengamestudio +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env sh -set -eu -SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) -if [ ! -f "$SCRIPT_DIR/dist/cli.js" ]; then - echo "Codex Game Studio needs a built checkout. Run: npm install && npm run build" >&2 - exit 1 -fi -exec node "$SCRIPT_DIR/dist/cli.js" "$@" diff --git a/package-lock.json b/package-lock.json index 96c1a7f..92bd8d6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13,8 +13,7 @@ "zod": "^3.25.76" }, "bin": { - "codex-game-studio": "dist/cli.js", - "opengamestudio": "dist/cli.js" + "codex-game-studio": "dist/cli.js" }, "devDependencies": { "@types/node": "^24.13.2", diff --git a/package.json b/package.json index 1be9c0b..51a3ba9 100644 --- a/package.json +++ b/package.json @@ -15,8 +15,7 @@ "templates/" ], "bin": { - "codex-game-studio": "./dist/cli.js", - "opengamestudio": "./dist/cli.js" + "codex-game-studio": "./dist/cli.js" }, "scripts": { "build": "tsc -p tsconfig.build.json", diff --git a/research/codex-port-design.md b/research/codex-port-design.md index 7abffa9..b28f8ff 100644 --- a/research/codex-port-design.md +++ b/research/codex-port-design.md @@ -15,7 +15,7 @@ This document is split into three scopes: ## Ground Rules - Build the port as TypeScript/Node only. -- Use `open-gamestudio` as the canonical CLI. +- Use `codex-game-studio` as the canonical CLI. - Preserve upstream user-facing capabilities unless explicitly documented as an intentional known difference. - Do not copy legacy source during the research/design phase. - Do not preserve Python internals, Python package metadata, or shell alias assumptions. @@ -29,10 +29,10 @@ The port may intentionally regress upstream implementation or UX details that ad Allowed differences: -- **No duplicate script-wrapper implementation.** Upstream-style script wrappers are not part of the core parity promise. The port should preserve npm/package discoverability and the canonical `opengamestudio` CLI, but it does not need separate wrapper files such as `scripts/init_project.mjs` or `scripts/project_manager.mjs` unless they are demonstrably useful. If wrappers are added, they must be thin pass-throughs to the canonical CLI and must not own logic. +- **No duplicate script-wrapper implementation.** Upstream-style script wrappers are not part of the core parity promise. The port should preserve npm/package discoverability and the canonical `codex-game-studio` CLI, but it does not need separate wrapper files such as `scripts/init_project.mjs` or `scripts/project_manager.mjs` unless they are demonstrably useful. If wrappers are added, they must be thin pass-throughs to the canonical CLI and must not own logic. - **No interactive menu.** Do not port upstream's interactive `menu` flow. It creates a second UI surface with extra state and terminal complexity. Non-interactive CLI commands are the supported interface. - **No `project_orchestrator.md` file parity.** Preserve the orchestration and handoff behavior through project `AGENTS.md`, the materialized `master_orchestrator` agent, and handoff templates/docs. Do not generate a separate upstream-style `project_orchestrator.md` file. -- **No exact `template_info.md` parity.** Replace the static upstream template-info document with a machine-readable template registry and/or `opengamestudio templates` commands. Generated docs may exist later, but exact file parity is not required. +- **No exact `template_info.md` parity.** Replace the static upstream template-info document with a machine-readable template registry and/or `codex-game-studio templates` commands. Generated docs may exist later, but exact file parity is not required. - **No eager competitor report generation during init.** Initialization should record competitor names in config and create a market overview/seed document. Full competitor analysis reports should be created by the market analyst workflow when requested, not as init clutter. - **No upstream license/authorship/citation doc parity.** This is a port/rewrite with project-owned licensing. Do not copy upstream license, authorship, or citation docs as parity artifacts. Use only this repository's chosen license outside the parity contract. - **No `startover` command.** Do not implement upstream `startover`; the name is ambiguous and encourages destructive semantics. If revision/reset workflows are needed later, design them under explicit non-destructive names. @@ -191,7 +191,7 @@ development: ## Project Initialization -`opengamestudio init` must preserve upstream project-creation outcomes while using a cleaner Node implementation. +`codex-game-studio init` must preserve upstream project-creation outcomes while using a cleaner Node implementation. Required initialization outputs: @@ -275,7 +275,7 @@ The port must preserve upstream template categories: - `market_analysis` -> `market_analysis_template.md` - `project_config` -> `project_config_template.json` -The TypeScript port may rename files only if the migration is documented and validation knows the new paths. Do not preserve exact `template_info.md` file parity; expose template discoverability through a typed registry and/or `opengamestudio templates` commands. +The TypeScript port may rename files only if the migration is documented and validation knows the new paths. Do not preserve exact `template_info.md` file parity; expose template discoverability through a typed registry and/or `codex-game-studio templates` commands. Template selection must be deterministic and bounded: `market_analyst` selects `market_analysis`, `data_scientist` selects `analytics_setup`, designer/spec tasks select `gdd`/`feature_spec`, engine/project setup tasks select `engine_setup`/`project_config`, and `handoff` is selected only for handoff/coordination tasks. QA does not load all templates by default. @@ -297,13 +297,13 @@ The port must preserve useful upstream project-management capabilities while int Canonical CLI commands should include equivalents for: ```bash -opengamestudio status [--project projects/my-game] -opengamestudio new -opengamestudio resume --project projects/my-game -opengamestudio freeze --project projects/my-game +codex-game-studio status [--project projects/my-game] +codex-game-studio new +codex-game-studio resume --project projects/my-game +codex-game-studio freeze --project projects/my-game ``` -`opengamestudio init` may be the canonical implementation behind `new`. +`codex-game-studio init` may be the canonical implementation behind `new`. Interactive `menu` behavior is intentionally not implemented. Users should rely on documented non-interactive commands. @@ -346,7 +346,7 @@ Required package metadata excerpt: } ``` -Separate thin Node wrappers such as `scripts/init_project.mjs`, `scripts/project_manager.mjs`, and `scripts/validate.mjs` are optional known differences. Prefer package scripts that call the built CLI via `node dist/cli.js`, plus explicit smoke tests for the canonical `opengamestudio` binary through `npm exec opengamestudio -- ...` after build/link/install. Do not rely on a bare self-bin name inside the package's own npm scripts before install/link. If wrappers exist, they must call the same command handlers as the canonical CLI and must not fork logic. +Separate thin Node wrappers such as `scripts/init_project.mjs`, `scripts/project_manager.mjs`, and `scripts/validate.mjs` are optional known differences. Prefer package scripts that call the built CLI via `node dist/cli.js`, plus explicit smoke tests for the canonical `codex-game-studio` binary through `npm exec codex-game-studio -- ...` after build/link/install. Do not rely on a bare self-bin name inside the package's own npm scripts before install/link. If wrappers exist, they must call the same command handlers as the canonical CLI and must not fork logic. The build config must keep the package bin stable: `tsconfig.json` may typecheck both `src/**/*.ts` and `tests/**/*.ts`, but `tsconfig.build.json` must emit `src/cli.ts` to `dist/cli.js` rather than `dist/src/cli.js`. Relative TypeScript imports must use emitted `.js` specifiers under NodeNext, for example `import { loadConfig } from "./config.js"`. @@ -358,7 +358,7 @@ Package shipping must be tested, not assumed. `npm pack --json` must include the Validation is a first-class product surface, not a copied legacy behavior. -`opengamestudio validate` must: +`codex-game-studio validate` must: - return exit code `0` only when all selected checks pass; - return non-zero when any selected check fails; @@ -417,7 +417,7 @@ The clean parity contract is satisfied when all are true: - TypeScript package builds. - Typecheck passes. - Tests pass. -- `opengamestudio init` can create Godot, Unity, and Unreal projects. +- `codex-game-studio init` can create Godot, Unity, and Unreal projects. - Each generated engine project validates. - All 12 base agents exist and can be materialized for a project. - Materialized prompts include the selected engine's prompt-overlay content, not just generic engine text. @@ -437,31 +437,31 @@ These are improvements over upstream that are useful for a Codex-native port, bu ## Canonical TypeScript CLI -`opengamestudio` is the canonical public interface. Npm scripts should call into it. Separate script wrappers are optional and should be avoided unless they provide clear compatibility value. +`codex-game-studio` is the canonical public interface. Npm scripts should call into it. Separate script wrappers are optional and should be avoided unless they provide clear compatibility value. Recommended core commands: ```bash -opengamestudio init -opengamestudio status -opengamestudio resume --project projects/my-game -opengamestudio freeze --project projects/my-game -opengamestudio validate -opengamestudio run --project projects/my-game --task "..." +codex-game-studio init +codex-game-studio status +codex-game-studio resume --project projects/my-game +codex-game-studio freeze --project projects/my-game +codex-game-studio validate +codex-game-studio run --project projects/my-game --task "..." ``` ## Codex Runner Upstream relies on users manually telling an AI CLI which project and agent files to read. The Codex-native port should add a bounded runner that assembles a structured prompt packet for one agent and one task. -Default `opengamestudio run --project --task ` behavior: +Default `codex-game-studio run --project --task ` behavior: - assemble one structured prompt packet; - write prompt cache and minimal metadata; - print the exact prompt path and next manual/Codex command; - not execute Codex or modify project artifacts beyond the prompt cache. -`opengamestudio run` should: +`codex-game-studio run` should: - load one selected agent; - load the project config summary; @@ -535,7 +535,7 @@ Project `AGENTS.md` must be a compact index and rules file, not a full prompt bu Generated files must include provenance markers so validation can prove they came from the generator: ```md - + ``` @@ -561,11 +561,11 @@ Bounded-context validation should check the generated prompt packet, not only so # Part 3: Future Optional Layer -These features are not present upstream and are not required for the initial implementation. They should stay out of the first build unless explicitly requested later. First-build validation/docs must include explicit absence checks: no `opengamestudio next`, no `run --exec`, no telemetry command/files, no parallel orchestration surface, and no hard ownership-enforcement behavior. +These features are not present upstream and are not required for the initial implementation. They should stay out of the first build unless explicitly requested later. First-build validation/docs must include explicit absence checks: no `codex-game-studio next`, no `run --exec`, no telemetry command/files, no parallel orchestration surface, and no hard ownership-enforcement behavior. ## Planner / `next` -A real `opengamestudio next` can be useful, but it is easy to overbuild and easy to make stale recommendations. +A real `codex-game-studio next` can be useful, but it is easy to overbuild and easy to make stale recommendations. Until project state, validation, run metadata, and handoff summaries are mature, the CLI should print simple static next-step suggestions rather than pretending to have a planner. @@ -658,7 +658,7 @@ hard-failing validation ## Add as Bounded Codex Improvements ```text -canonical open-gamestudio CLI +canonical codex-game-studio CLI project AGENTS.md bounded run command prompt cache diff --git a/src/generated-surfaces.ts b/src/generated-surfaces.ts index 47d739b..3b16c70 100644 --- a/src/generated-surfaces.ts +++ b/src/generated-surfaces.ts @@ -37,7 +37,7 @@ export function hashGeneratedBody(bodyWithoutMetadata: string): string { export function stripGeneratedMetadata(body: string): string { return body.replace( - /^\n\n\n/, + /^\n\n\n/, "" ); } @@ -59,10 +59,10 @@ export function parseGeneratedSurfaceMetadata(body: string): GeneratedSurfaceMet } export function parseGeneratedSurfaceMetadataParts(body: string): GeneratedSurfaceMetadataParts { - const generated = /^\n/.exec(body); - const source = /^\n\n/.exec(body); - const rendered = /^\n\n\n/.exec(body); - const hasAnyMarker = /^$/m.test(body) || /^$/m.test(body) || /^$/m.test(body); + const generated = /^\n/.exec(body); + const source = /^\n\n/.exec(body); + const rendered = /^\n\n\n/.exec(body); + const hasAnyMarker = /^$/m.test(body) || /^$/m.test(body) || /^$/m.test(body); return { generated: generated ? { surface: generated[1], id: generated[2], role: generated[3], schema: generated[4] } : undefined, sourceInputSha256: source?.[1], diff --git a/src/paths.ts b/src/paths.ts index 278ae94..1246ef9 100644 --- a/src/paths.ts +++ b/src/paths.ts @@ -8,7 +8,7 @@ export function packageRoot(metaUrl: string = import.meta.url): string { const manifest = path.join(current, "package.json"); if (existsSync(manifest)) { const parsed = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string }; - if (parsed.name === "codex-game-studio" || parsed.name === "open-gamestudio") return current; + if (parsed.name === "codex-game-studio") return current; } const parent = path.dirname(current); if (parent === current) { diff --git a/src/validation.ts b/src/validation.ts index e946934..febe66d 100644 --- a/src/validation.ts +++ b/src/validation.ts @@ -229,9 +229,9 @@ export async function validateRepo(root = process.cwd()): Promise=24") ? pass("package.node", "node 24 floor declared") : fail("package.node", "node >=24 must be declared", pkgPath)); for (const file of ["dist/", "engine_configs/", "engine_reference/", "templates/"]) { diff --git a/tests/validation.test.ts b/tests/validation.test.ts index c768890..2e02627 100644 --- a/tests/validation.test.ts +++ b/tests/validation.test.ts @@ -30,8 +30,7 @@ describe("validation", () => { const pkg = JSON.parse(readFileSync(path.join(process.cwd(), "package.json"), "utf8")) as { name?: string; bin?: Record }; expect(pkg.name).toBe("codex-game-studio"); expect(pkg.bin?.["codex-game-studio"]).toBe("./dist/cli.js"); - expect(pkg.bin?.opengamestudio).toBe("./dist/cli.js"); - expect(pkg.bin?.["open-gamestudio"]).toBeUndefined(); + expect(Object.keys(pkg.bin ?? {})).toEqual(["codex-game-studio"]); }); test("source checkout wrapper uses built dist output instead of a generated bundle", () => {