diff --git a/AGENTS.md b/AGENTS.md index fe42042..c391a46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,4 +12,4 @@ Do not load all agents or all templates for a single role task. `src/agents.ts` is the single owner for generated project `AGENTS.md`. -Direct Codex execution is a first-class path via `open-gamestudio run --exec`. Telemetry, planner/next, ownership enforcement, and parallel orchestration are future-only. +Direct Codex execution is the default path via `open-gamestudio run `. `--dry-run` and `--print-prompt` are inspection-only paths. Telemetry, planner/next, ownership enforcement, and parallel orchestration are future-only. diff --git a/README.md b/README.md index aa9afd2..175da49 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Open GameStudio -Open GameStudio is a Node/TypeScript CLI package for creating and managing local, agent-assisted game projects. It provides project scaffolding, engine-aware configuration, base agent prompts, reusable templates, bounded prompt packets, and validation gates that keep generated project artifacts predictable. +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. -The package is a Codex-first agent workflow layer for game making. It keeps project state local and inspectable while integrating directly with `codex exec` for role-specific work. The CLI prepares bounded prompt packets, invokes Codex when requested, and preserves deterministic validation gates around generated artifacts. +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. ## Why This Exists @@ -15,7 +15,7 @@ Claude Game Studio deserves real kudos for proving that role-based game-developm - 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 can be executed directly with `--exec`. +- 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. 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. @@ -24,6 +24,7 @@ The goal is not to clone another tool. The goal is to make the workflow contract - Node.js 20 or newer. - npm. +- Codex CLI for normal execution and repository validation. ## Install @@ -80,16 +81,16 @@ Run a project agent through Codex: ```sh npm run build --silent -node dist/cli.js run market_analyst --project projects/my-game --task "Create the initial market overview." --exec +node dist/cli.js run producer --project projects/my-game "Create the initial market overview." ``` Inspect the generated prompt packet without executing Codex: ```sh -node dist/cli.js run market_analyst --project projects/my-game --task "Create the initial market overview." --dry-run +node dist/cli.js run producer --project projects/my-game "Create the initial market overview." --dry-run ``` -The `run` command writes a bounded prompt packet and, with `--exec`, immediately invokes `codex exec` in the project root. Use `--dry-run` or `--print-prompt` when you want to inspect the exact Codex context first. +The `run` command writes a bounded prompt packet and immediately invokes `codex exec` in the project root. Use `--dry-run` or `--print-prompt` when you want to inspect the exact Codex context first. ## CLI Commands @@ -100,14 +101,23 @@ The `run` command writes a bounded prompt packet and, with `--exec`, immediately - `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 project agent; add `--exec` to invoke `codex exec` immediately. +- `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. ## Project Layout Repository assets: - `src/`: TypeScript CLI implementation. -- `agents/base/`: base role prompts packaged with the CLI. +- `src/roles.ts`: Codex role packages compiled into the CLI. - `templates/`: reusable document and setup templates. - `engine_configs/`: engine overlays for Godot, Unity, and Unreal. - `docs/`: setup, migration, validation, and example notes. @@ -116,11 +126,13 @@ Repository assets: Generated project artifacts: - `projects//`: the project root created by `init`. -- `project.gamestudio.json`: project metadata and workflow state. -- `AGENTS.md`: generated project instructions owned by `src/agents.ts`. +- `AGENTS.md`: primary generated Codex project instructions, owned by `src/agents.ts`. +- `.codex/studio.json`: authoritative project metadata 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. - `source/project-/`: engine project location contract. -- `.gamestudio/runs/`: prepared prompt packets and run metadata. ## Development diff --git a/agents/base/data_scientist.md b/agents/base/data_scientist.md deleted file mode 100644 index ac62476..0000000 --- a/agents/base/data_scientist.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Define analytics, metrics, events, and experiment-readiness for the project. - -# Inputs - -Project config, core loop, target audience, and analytics template. - -# Outputs - -Analytics plan, event taxonomy, metric definitions, and validation notes. - -# Output Paths - -Use `documentation/technical/analytics/analytics-plan.md`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Map instrumentation ideas to the selected engine. - -# Rules - -Do not add telemetry for this toolkit; discuss only game analytics artifacts. diff --git a/agents/base/game_feel_developer.md b/agents/base/game_feel_developer.md deleted file mode 100644 index a5adb08..0000000 --- a/agents/base/game_feel_developer.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Improve responsiveness, feedback, controls, camera, and tuning. - -# Inputs - -Project config, mechanics notes, engine overlay, and playtest observations. - -# Outputs - -Game-feel tuning notes, implementation tasks, and validation criteria. - -# Output Paths - -Use `documentation/design/feel/` and selected engine source paths. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Map feedback and tuning work to engine-specific systems. - -# Rules - -Keep changes measurable and playtest-oriented. diff --git a/agents/base/market_analyst.md b/agents/base/market_analyst.md deleted file mode 100644 index 08d2169..0000000 --- a/agents/base/market_analyst.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Analyze audience, positioning, competitors, and monetization fit. - -# Inputs - -Project config, competitor names, audience, genre, platform, and market template. - -# Outputs - -Market overview, competitor comparison, positioning risks, and recommended research questions. - -# Output Paths - -Use `resources/market-research/market-analysis.md`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Relate market risks to engine/platform constraints. - -# Rules - -Do not generate eager per-competitor reports unless the task asks for them. diff --git a/agents/base/master_orchestrator.md b/agents/base/master_orchestrator.md deleted file mode 100644 index 4b50aad..0000000 --- a/agents/base/master_orchestrator.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Coordinate the game-studio workflow, sequence work, and keep scope aligned with project goals. - -# Inputs - -Project config, current task, selected engine notes, and relevant handoff material. - -# Outputs - -Coordination notes, next role recommendation, and explicit artifact paths. - -# Output Paths - -Use `documentation/handoffs/` for handoffs and reference project artifacts instead of embedding them. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Adapt sequencing to the selected engine overlay. - -# Rules - -Use bounded context. Do not run Codex, telemetry, planner, parallel orchestration, or ownership enforcement. diff --git a/agents/base/mechanics_developer.md b/agents/base/mechanics_developer.md deleted file mode 100644 index 912274d..0000000 --- a/agents/base/mechanics_developer.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Design and implement gameplay mechanics plans within the selected engine contract. - -# Inputs - -Project config, engine setup notes, feature spec, and current task. - -# Outputs - -Mechanics implementation notes, source-path guidance, and validation checks. - -# Output Paths - -Use `source/project-/` and `documentation/technical/`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Use the selected engine overlay for folder and project-file expectations. - -# Rules - -Respect the `source/project-/` contract. diff --git a/agents/base/mid_game_designer.md b/agents/base/mid_game_designer.md deleted file mode 100644 index 1c2cd91..0000000 --- a/agents/base/mid_game_designer.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Elaborate features, levels, content, and moment-to-moment design details. - -# Inputs - -Project config, senior design direction, feature template, and current task. - -# Outputs - -Feature notes, content lists, and playtest-ready acceptance criteria. - -# Output Paths - -Use `documentation/design/features/`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Keep implementation detail compatible with the selected engine. - -# Rules - -Do not load unrelated templates unless the task requires them. diff --git a/agents/base/producer_agent.md b/agents/base/producer_agent.md deleted file mode 100644 index 2d69f53..0000000 --- a/agents/base/producer_agent.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Own production planning, milestones, status summaries, and project delivery rhythm. - -# Inputs - -Project config, milestones, timeline, current task, and validation state. - -# Outputs - -Production plan updates, risks, and clear next validation gates. - -# Output Paths - -Use `documentation/production/` and update config only when explicitly requested. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Account for engine-specific setup and build risks. - -# Rules - -Keep operational status separate from generated guidance hashes. diff --git a/agents/base/qa_agent.md b/agents/base/qa_agent.md deleted file mode 100644 index a9b0b57..0000000 --- a/agents/base/qa_agent.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Review validation readiness, test plans, acceptance criteria, and regressions. - -# Inputs - -Project config, task details, validation command, and selected artifacts. - -# Outputs - -QA plan, failure risks, reproduction steps, and validation checklist. - -# Output Paths - -Use `documentation/qa/`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Check engine-specific project-file and source-root requirements. - -# Rules - -Do not run agents or broad orchestration; report manual next commands. diff --git a/agents/base/sr_game_artist.md b/agents/base/sr_game_artist.md deleted file mode 100644 index e915df8..0000000 --- a/agents/base/sr_game_artist.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Own art direction, visual targets, asset priorities, and style consistency. - -# Inputs - -Project config, audience, design goals, engine overlay, and art task. - -# Outputs - -Art direction notes, asset lists, and production-ready briefs. - -# Output Paths - -Use `documentation/art/` and engine asset folders under `source/project-/`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Consider import paths and asset conventions for the selected engine. - -# Rules - -Do not create unrelated assets without explicit task scope. diff --git a/agents/base/sr_game_designer.md b/agents/base/sr_game_designer.md deleted file mode 100644 index ad9f26c..0000000 --- a/agents/base/sr_game_designer.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Own senior design direction, core loop quality, systems fit, and feature specs. - -# Inputs - -Project config, GDD, feature request, engine notes, and design template. - -# Outputs - -Design decisions, GDD updates, feature specs, and acceptance criteria. - -# Output Paths - -Use `documentation/design/gdd.md` and `documentation/design/features/`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Adapt designs to selected engine affordances. - -# Rules - -Prefer scoped design artifacts over broad rewrites. diff --git a/agents/base/technical_artist.md b/agents/base/technical_artist.md deleted file mode 100644 index 1c865fe..0000000 --- a/agents/base/technical_artist.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Bridge art and engineering for shaders, pipelines, import settings, and performance. - -# Inputs - -Project config, art direction, engine overlay, and technical constraints. - -# Outputs - -Pipeline notes, technical art tasks, and validation checks. - -# Output Paths - -Use `documentation/art/technical/` and engine source asset paths. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Use engine-specific material, shader, and import conventions. - -# Rules - -Keep pipeline guidance reproducible. diff --git a/agents/base/ui_ux_agent.md b/agents/base/ui_ux_agent.md deleted file mode 100644 index 6e01b46..0000000 --- a/agents/base/ui_ux_agent.md +++ /dev/null @@ -1,27 +0,0 @@ -# Role - -Design UI flows, HUDs, menus, accessibility notes, and interaction ergonomics. - -# Inputs - -Project config, audience, platform, engine overlay, and UI task. - -# Outputs - -UI specs, screen flows, HUD requirements, and validation criteria. - -# Output Paths - -Use `documentation/design/ui-ux/`. - -# Validation - -Run `npm run validate -- --project `. - -# Engine Notes - -Map UI recommendations to selected engine UI systems. - -# Rules - -Protect gameplay readability and avoid broad unrelated context. diff --git a/docs/development-rules.md b/docs/development-rules.md index 554cca5..698994b 100644 --- a/docs/development-rules.md +++ b/docs/development-rules.md @@ -15,4 +15,4 @@ npm run validate Keep generated projects under `projects//`. -The first build includes direct Codex execution through `run --exec`. It still intentionally excludes planner commands, telemetry, parallel orchestration, changed-file tracking, and ownership enforcement. +The current build invokes Codex by default through `run `. Use `--dry-run` or `--print-prompt` for inspection-only paths. It still intentionally excludes planner commands, telemetry, parallel orchestration, changed-file tracking, and ownership enforcement. diff --git a/docs/examples.md b/docs/examples.md index 16dfe22..7b9def1 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,28 +1,35 @@ # Examples -Create and validate a project: +Create and validate a project from this repository: -```bash -npm exec open-gamestudio -- init --name "My Game" --engine godot --mode prototype --non-interactive --competitor "Mini Metro" --competitor "Dorfromantik" -npm exec open-gamestudio -- status --project projects/my-game -npm exec open-gamestudio -- validate --project projects/my-game +```sh +npm run build +npm run init -- --name "Rogue Core" --engine godot --mode prototype --non-interactive --competitor "Mini Metro" --competitor "Dorfromantik" +npm run manage -- --project projects/rogue-core +npm run validate -- --project projects/rogue-core ``` -Run a role agent directly through Codex: +Run a studio role directly through Codex: -```bash -npm exec open-gamestudio -- run market_analyst --project projects/my-game --task "Create the initial market overview." --exec +```sh +npm run build && node dist/cli.js run producer --project projects/rogue-core "Create the initial market overview." ``` -Inspect the bounded Codex prompt packet first: +Inspect prompts without launching Codex: -```bash -npm exec open-gamestudio -- run market_analyst --project projects/my-game --task "Create the initial market overview." --dry-run +```sh +npm run build && node dist/cli.js run producer --project projects/rogue-core "Create the initial market overview." --dry-run +npm run build && node dist/cli.js market --project projects/rogue-core --dry-run +npm run build && node dist/cli.js analytics --project projects/rogue-core --dry-run +npm run build && node dist/cli.js handoff --project projects/rogue-core --dry-run +npm run build && node dist/cli.js design-spec --project projects/rogue-core --dry-run +npm run build && node dist/cli.js feel-review --project projects/rogue-core --dry-run +npm run build && node dist/cli.js ui-review --project projects/rogue-core --dry-run ``` -Discover templates: +Discover packaged templates: -```bash -npm exec open-gamestudio -- templates list -npm exec open-gamestudio -- templates show market_analysis +```sh +npm run templates -- list +npm run templates -- show market_analysis ``` diff --git a/docs/known-upstream-differences.md b/docs/known-upstream-differences.md index 136e98e..de9cbfa 100644 --- a/docs/known-upstream-differences.md +++ b/docs/known-upstream-differences.md @@ -10,8 +10,18 @@ Legacy Unreal naming used multiple labels. This port normalizes `Unreal`, `Unrea Legacy validation depended on Python and shell assumptions. This port is TypeScript/Node only. +Role roster coverage is preserved through Codex-native IDs: `studio-orchestrator`, `market-analyst`, `data-scientist`, senior design/art roles, game-feel, UI/UX, QA, release, and implementation roles. Legacy underscore aliases such as `producer_agent`, `qa_agent`, and `master_orchestrator` are intentionally not valid role IDs. + +Generated projects materialize project-specific `.codex/prompts/.md` files for every role. `AGENTS.md` remains the primary generated Codex instruction surface and is owned by `src/agents.ts`. + +Market and analytics are first-class renderable workflows owned by dedicated roles. Their prompts inline the selected package template bodies instead of pointing Codex at project-relative template paths. + +Studio orchestration is provided by the `studio-orchestrator` role and the render-only `handoff` workflow shortcut, not by a generated `project_orchestrator.md`. + +Richer workflows exist for design specs, game-feel review, art direction, UI/UX review, production milestones, review, ship-check, playtest, bugfix, vertical slice, market, analytics, and handoff. Shortcut workflow commands render prompts only; executable workflow lifecycle support remains future-only. + Intentional omissions for the first build: no interactive `menu`, no `startover`, no generated `project_orchestrator.md`, no exact `template_info.md`, no eager competitor reports during init, and no upstream license/authorship/citation parity documents. -Codex-native difference: `run --exec` invokes `codex exec` directly against the generated bounded prompt packet instead of requiring a separate manual command. +Codex-native difference: `run ` invokes `codex exec` by default against the generated bounded prompt packet. `--dry-run` and `--print-prompt` are the non-executing inspection paths. Future-only features are not implemented in this build: planner/`next`, telemetry, parallel orchestration, changed-file tracking, prompt-size metrics, and hard output-ownership enforcement. diff --git a/docs/migration-from-claude.md b/docs/migration-from-claude.md index 6f50a6f..d3c3a85 100644 --- a/docs/migration-from-claude.md +++ b/docs/migration-from-claude.md @@ -4,10 +4,10 @@ Use the canonical TypeScript CLI with direct Codex execution: ```bash npm exec open-gamestudio -- init --name "My Game" --engine godot --mode prototype --non-interactive --competitor "Mini Metro" -npm exec open-gamestudio -- run market_analyst --project projects/my-game --task "Create the initial market overview." --exec +npm exec open-gamestudio -- run producer --project projects/my-game "Create the initial market overview." ``` -For inspection-only runs, omit `--exec` or add `--dry-run` to view the generated Codex prompt packet and metadata path before execution. +For inspection-only runs, add `--dry-run` or `--print-prompt` to view the generated Codex prompt packet and metadata path before execution. Intentional differences: no interactive menu, no `startover`, no exact `template_info.md`, no eager competitor reports during init, and no generated `project_orchestrator.md`. diff --git a/docs/plans/2026-05-28-codex-game-studio-functionality-gap-pass.md b/docs/plans/2026-05-28-codex-game-studio-functionality-gap-pass.md new file mode 100644 index 0000000..87cce43 --- /dev/null +++ b/docs/plans/2026-05-28-codex-game-studio-functionality-gap-pass.md @@ -0,0 +1,1394 @@ +# Codex Game Studio Functionality Gap Pass Implementation Plan + +> **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, push commits, or rename the package/repo unless Merlin explicitly asks. + +**Goal:** Fill the five major functionality gaps versus the Claude Game Studio baseline while preserving the Codex-native architecture: role roster parity, project-specific role materialization, market/analytics workflows, studio orchestration, and richer studio workflow depth. + +**Architecture:** Keep `.codex/studio.json` authoritative and `AGENTS.md` as the primary Codex instruction surface. Add richer Codex-native role packages and workflow specs rather than restoring legacy `.gamestudio` state, legacy agent aliases, or `project_orchestrator.md`. Keep the implementation file-backed, deterministic, package-friendly, and test-driven; telemetry, planner/`next`, hard ownership enforcement, and parallel orchestration remain future-only unless explicitly introduced by a later plan. + +**Tech Stack:** TypeScript, NodeNext ESM, npm CLI package, Vitest, Codex CLI, file-backed JSON/Markdown project state. + +--- + +## Scope + +This pass addresses the first five functionality gaps identified in the Claude Game Studio comparison: + +1. **Agent roster parity:** add missing specialized studio functions in Codex-native form. +2. **Project-specific agent materialization:** generate project-aware role prompt files, not just generic prompt stubs. +3. **Market/analytics workflows:** make market and analytics first-class renderable workflow prompts and role-owned inspection loops, not just templates selected by producer tasks. Workflow shortcut commands remain render-only in this pass; executable workflow lifecycle support is explicitly deferred. +4. **Studio orchestration:** add a Codex-native orchestration role/workflow without restoring legacy `project_orchestrator.md`. +5. **Workflow depth:** expand workflow files and CLI surfaces from thin prompt renderers into practical studio operating loops. + +## Non-Goals + +- Do not restore legacy `.gamestudio/*` state. +- Do not make `project-config.json` authoritative again. +- Do not add backwards-compatible legacy role aliases such as `producer_agent` or `qa_agent`. +- Do not generate `project_orchestrator.md`. +- Do not add interactive `menu` or `startover`. +- Do not add database-backed task storage. +- Do not add parallel orchestration. +- Do not add `open-gamestudio next`, telemetry, changed-file tracking, or hard output-ownership enforcement in this pass. +- Do not eagerly generate full competitor reports during `init`; full reports belong to the market workflow. + +## Design Decisions + +### Role IDs + +Decision: use the expanded 16-role Codex-native superset and retain the existing `narrative-designer` role for compatibility and story/content coverage. This yields 17 total roles: the 16-role functionality-gap superset plus the retained current Codex-native narrative role. + +Keep Codex-native role IDs, but expand coverage to preserve the upstream functional roles while avoiding a silent compatibility cut: + +```ts +export const studioRoleIds = [ + "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", + "release-manager" +] as const; +``` + +Rationale: + +- This keeps existing Codex-native IDs where they already make sense. +- It adds explicit equivalents for upstream `master_orchestrator`, `market_analyst`, `data_scientist`, `game_feel_developer`, `sr_game_artist`, and `ui_ux_agent`. +- It splits senior/implementation design coverage without restoring underscore legacy names. +- It retains the existing Codex-native `narrative-designer` role so current projects, tests, and story/content workflows do not lose a first-class owner. +- It keeps existing `creative-director`, `engine-programmer`, `tools-programmer`, and `release-manager` as Codex-native value-add roles. + +### Parity Crosswalk and Legacy Alias Cut + +Decision: document functional parity as a role/function crosswalk, not as legacy role-ID compatibility. The implementation must reject representative legacy underscore aliases with clear guidance instead of silently accepting them. + +| Upstream / baseline function | Codex-native owner(s) | Compatibility decision | +|---|---|---| +| `master_orchestrator` / studio routing | `studio-orchestrator` | No `master_orchestrator` or `project_orchestrator.md`; use `handoff` workflow. | +| `producer_agent` / production planning | `producer`, `studio-orchestrator` | No `producer_agent` alias; use `producer`. | +| market research / competitor analysis | `market-analyst` | First-class renderable `market-analysis` workflow and `market` shortcut. | +| analytics / metrics / experiments | `data-scientist` | First-class renderable `analytics-setup` workflow and `analytics` shortcut. | +| creative direction | `creative-director` | Keep Codex-native hyphenated ID. | +| senior systems / economy / progression design | `senior-game-designer` | New explicit senior design owner. | +| feature / acceptance design | `game-designer` | Keep as implementation-level design owner. | +| story / world / content | `narrative-designer` | Retained Codex-native compatibility role. | +| game feel / controls / juice | `game-feel-designer` | New explicit feel owner. | +| gameplay implementation | `gameplay-programmer` | Keep Codex-native hyphenated ID. | +| engine/platform implementation | `engine-programmer` | Keep Codex-native value-add role. | +| internal tools/editor automation | `tools-programmer` | Keep Codex-native value-add role. | +| senior art direction / asset quality bar | `senior-game-artist` | New explicit senior art owner. | +| technical art / pipeline constraints | `technical-artist` | Keep Codex-native value-add role. | +| UI/UX / onboarding / accessibility | `ui-ux-designer` | New explicit UI/UX owner. | +| `qa_agent` / playtest / QA review | `qa-playtester` | No `qa_agent` alias; use `qa-playtester`. | +| release / ship readiness | `release-manager` | Keep Codex-native value-add role. | + +Acceptance tests must verify the Codex-native role IDs exist and representative legacy aliases such as `producer_agent`, `qa_agent`, and `master_orchestrator` are not treated as valid `StudioRoleId` values. + +### Active Roles by Mode + +Use functional parity with the upstream mode intent, adapted to Codex-native IDs: + +```ts +always: + studio-orchestrator + producer + market-analyst + data-scientist + +design: + creative-director + senior-game-designer + game-designer + narrative-designer + senior-game-artist + ui-ux-designer + +prototype: + senior-game-designer + game-designer + game-feel-designer + gameplay-programmer + qa-playtester + +development: + senior-game-designer + game-designer + game-feel-designer + gameplay-programmer + engine-programmer + tools-programmer + qa-playtester + senior-game-artist + technical-artist + ui-ux-designer + release-manager +``` + +### Authoritative Studio State Contract + +Decision: `.codex/studio.json` must distinguish the full available roster from mode-active roles. Keep `roles` as the full expanded role roster for discoverability, add an explicit `activeRoles` field for `activeAgentsForMode(mode)`, and populate `workflows` from `Object.keys(workflowRegistry)` after the canonical registry exists. + +Use this generated state contract or an equivalent typed shape: + +```ts +export type StudioProjectState = { + // existing fields omitted + roles: StudioRoleId[]; // full available Codex-native roster + activeRoles: StudioRoleId[]; // mode-active roles from activeAgentsForMode(mode) + workflows: WorkflowId[]; // generated from workflowRegistry keys +}; +``` + +`statusProject` should print `activeRoles` as active roles, not the full roster. Project validation must assert `roles` equals `studioRoleIds`, `activeRoles` equals `activeAgentsForMode(studio.mode)`, and `workflows` equals the canonical workflow registry keys. + +### Project Prompt Materialization + +Generated projects should contain project-aware prompt files: + +```text +projects// + AGENTS.md + .codex/ + studio.json + prompts/ + studio-orchestrator.md + producer.md + market-analyst.md + data-scientist.md + creative-director.md + senior-game-designer.md + game-designer.md + narrative-designer.md + game-feel-designer.md + gameplay-programmer.md + engine-programmer.md + tools-programmer.md + senior-game-artist.md + technical-artist.md + ui-ux-designer.md + qa-playtester.md + release-manager.md + workflows/ + vertical-slice.md + bugfix.md + playtest.md + market-analysis.md + analytics-setup.md + design-spec.md + game-feel-tuning.md + art-direction.md + ui-ux-review.md + production-milestone.md + handoff.md + review.md + ship-check.md +``` + +Only `src/agents.ts` owns generated project `AGENTS.md`. Project-specific prompt body generation may live in `src/agents.ts` or a new helper imported by it; do not put `AGENTS.md` body text in `src/projects.ts`. + +### Template Delivery for Workflow Prompts + +Decision: keep package templates as the source of truth and inline only the selected template bodies into rendered workflow prompts. Do not rely on project-relative `templates/...` paths unless a future customization feature deliberately materializes project-local template overrides. + +Use this contract: + +- Project context files remain project-relative and listed as context files, for example `AGENTS.md`, `.codex/studio.json`, `.codex/workflows/.md`, `documentation/design/gdd.md`, and `resources/market-research/market-overview.md`. +- Workflow templates are package assets selected by deterministic template IDs such as `market_analysis`, `analytics_setup`, `feature_spec`, and `handoff`. +- `renderWorkflowPrompt` must append a `## Workflow Templates` section containing only the selected template IDs and bodies. +- Each inlined template section must include both the template ID and package source path, for example: + +```markdown +## Workflow Templates + +### Template: market_analysis +Source: package:templates/market_analysis_template.md + +