diff --git a/README.md b/README.md index 9f11032..f721ad2 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,265 @@ -# Codex Game Studio +

+

Codex Game Studio

+

+ Turn a Codex session into a structured, local-first game studio. +
+ 38 agents. 79 skills. 31 workflows. One Git-reviewable studio template. +

+

-**Turn a Codex session into a structured, local-first game studio.** +

+ MIT License + 38 Agents + 79 Skills + 31 Workflows + Node.js >=24 + Built for Codex +

-[🇺🇸 English](README.md) | [🇨🇳 简体中文](docs/readmes/README.zh.md) | [🇯🇵 日本語](docs/readmes/README.ja.md) | [🇰🇷 한국어](docs/readmes/README.ko.md) +

+ 🇺🇸 English | + 🇨🇳 简体中文 | + 🇯🇵 日本語 | + 🇰🇷 한국어 +

-[![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 TypeScript CLI for running game-development work through Codex with a studio-shaped workspace: roles, workflow prompts, project files, task state, and validation live in ordinary Git-reviewable files. +## Why This Exists -It is not a game engine and not a hosted project manager. It gives Codex a clearer contract for production, design, engineering, QA, art, audio, localization, and release work while leaving creative decisions and review with you. +A blank AI coding chat is flexible, but game development needs repeatable studio structure. Someone has to protect the vision, keep milestones visible, review technical choices, validate gameplay changes, check accessibility, prepare release notes, and make sure decisions are not trapped in chat history. -## Quick start +**Codex Game Studio** gives a Codex session the shape of a game studio without turning it into a hosted project manager or game engine. You get tracked agents, skills, workflows, project state, and validation in ordinary files that humans can inspect in Git. -Requirements: Node.js 24 or newer. The Codex CLI is required for `run `. +The template is deliberately clone-first: the visible `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, and `.agents/skills/*/SKILL.md` files are the studio surface. `init` records project state; it does not regenerate or overwrite the studio template. -```sh -git clone git@github.com:merlinhu1/codex-game-studio.git signal-cartographer -cd signal-cartographer -npm install -npm run build +--- -./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \ - --concept "A compact puzzle game about routing trains through haunted switchyards" +## Table of Contents -./codex-game-studio status -./codex-game-studio validate +- [What's Included](#whats-included) +- [Studio Hierarchy](#studio-hierarchy) +- [Skills](#skills) +- [Workflows](#workflows) +- [Getting Started](#getting-started) +- [Project Structure](#project-structure) +- [How It Works](#how-it-works) +- [Model Routing](#model-routing) +- [Documentation](#documentation) +- [Project Status](#project-status) +- [License](#license) + +--- + +## What's Included + +| Category | Count | Description | +|----------|-------|-------------| +| **Agents** | 38 | Codex custom agents across production, design, programming, art, audio, narrative, QA, localization, live ops, release, and engine support | +| **Skills** | 79 | Reusable studio actions under `.agents/skills/*/SKILL.md`, from onboarding and design through QA, release, team orchestration, and standards | +| **Workflows** | 31 | Tracked prompt workflows for market review, specs, stories, sprints, QA, security, release, hotfixes, vertical slices, and handoffs | +| **Engine Tracks** | 3 | Godot, Unity, and Unreal specialist context with engine references and validation checks | +| **Templates** | 31 | Packaged document templates for GDDs, ADRs, technical designs, playtests, releases, postmortems, risk registers, pitch docs, and more | +| **Validation** | built in | Hard-failing checks for package assets, template surfaces, project state, metadata, engine references, and future-only CLI drift | + +## Studio Hierarchy + +Agents are organized like a small game studio: directors own vision and technical coherence, leads own domain direction, and specialists handle focused execution. + +```text +Tier 1 — Direction + creative-director technical-director producer + studio-orchestrator + +Tier 2 — Department Leads + game-designer senior-game-designer senior-game-artist + audio-director localization-lead release-manager + market-analyst narrative-designer + +Tier 3 — Specialists + gameplay-programmer engine-programmer ai-programmer + network-programmer tools-programmer ui-programmer + systems-designer level-designer economy-designer + game-feel-designer technical-artist sound-designer + writer world-builder ui-ux-designer + qa-playtester accessibility-specialist performance-analyst + devops-engineer security-engineer data-scientist + community-manager live-ops-designer ``` -To inspect a role prompt before launching Codex: +### Engine Specialists -```sh -./codex-game-studio run producer \ - "Create the initial market overview." --print-prompt +| Engine | Lead Agent | Focus | +|--------|------------|-------| +| **Godot 4** | `godot-specialist` | GDScript, scenes, nodes, resources, signals, plugins, and Godot-specific validation | +| **Unity** | `unity-specialist` | C#, packages, scenes, prefabs, UI Toolkit, Addressables, Cinemachine, and DOTS/ECS context | +| **Unreal Engine 5** | `unreal-specialist` | C++, Blueprints, GAS, replication, UMG/CommonUI, plugins, and Unreal project conventions | + +## Skills + +Skills are tracked under `.agents/skills/*/SKILL.md`. They are the reusable studio actions Codex can apply while working inside the template. + +**Onboarding & Navigation** +`cgs-start` `cgs-help` `cgs-project-stage-detect` `cgs-setup-engine` `cgs-adopt` `cgs-onboard` + +**Game Design** +`cgs-brainstorm` `cgs-map-systems` `cgs-design-system` `cgs-quick-design` `cgs-review-all-gdds` `cgs-propagate-design-change` `cgs-balance-check` + +**Art & Assets** +`cgs-art-bible` `cgs-asset-spec` `cgs-asset-audit` + +**UX & Interface** +`cgs-ux-design` `cgs-ux-review` `cgs-ui-ux-review` + +**Architecture & Technical Planning** +`cgs-create-architecture` `cgs-architecture-decision` `cgs-architecture-review` `cgs-create-control-manifest` + +**Stories & Sprints** +`cgs-create-epics` `cgs-create-stories` `cgs-dev-story` `cgs-sprint-plan` `cgs-sprint-status` `cgs-story-readiness` `cgs-story-done` `cgs-estimate` `cgs-vertical-slice` + +**Reviews & Analysis** +`cgs-design-review` `cgs-code-review` `cgs-scope-check` `cgs-perf-profile` `cgs-tech-debt` `cgs-gate-check` `cgs-consistency-check` `cgs-security-audit` `cgs-content-audit` + +**QA & Testing** +`cgs-qa-plan` `cgs-smoke-check` `cgs-soak-test` `cgs-regression-suite` `cgs-test-setup` `cgs-test-helpers` `cgs-test-evidence-review` `cgs-test-flakiness` `cgs-skill-test` `cgs-skill-improve` + +**Production** +`cgs-milestone-review` `cgs-retrospective` `cgs-bug-report` `cgs-bug-triage` `cgs-bugfix` `cgs-reverse-document` `cgs-playtest-report` + +**Release** +`cgs-release-checklist` `cgs-launch-checklist` `cgs-changelog` `cgs-patch-notes` `cgs-hotfix` `cgs-day-one-patch` + +**Creative & Content** +`cgs-prototype` `cgs-localize` + +**Team Orchestration** +`cgs-team-combat` `cgs-team-narrative` `cgs-team-ui` `cgs-team-release` `cgs-team-polish` `cgs-team-audio` `cgs-team-level` `cgs-team-live-ops` `cgs-team-qa` + +**Path Standards** +`cgs-standards-gameplay` `cgs-standards-prototype` `cgs-standards-tests` `cgs-standards-ui` + +## Workflows + +Workflow prompts live under `.codex/workflows/*.md`. They are inspection-friendly prompt surfaces; shortcut commands render prompts and do not launch Codex unless you explicitly run a role or task. + +| Phase | Workflows | +|-------|-----------| +| **Discovery** | `brainstorm`, `market-analysis`, `analytics-setup`, `onboard` | +| **Design** | `design-spec`, `game-feel-tuning`, `art-direction`, `localization-plan`, `ui-ux-review` | +| **Architecture** | `architecture-decision`, `architecture-review`, `security-audit`, `perf-profile` | +| **Planning** | `create-epics`, `create-stories`, `sprint-plan`, `sprint-status`, `story-readiness` | +| **Implementation** | `vertical-slice`, `prototype`, `bugfix`, `hotfix`, `story-done` | +| **QA & Review** | `qa-plan`, `regression-suite`, `playtest`, `review`, `handoff` | +| **Release** | `production-milestone`, `release-checklist`, `ship-check` | + +## Getting Started + +### Prerequisites + +- [Git](https://git-scm.com/) +- Node.js 24 or newer +- Codex CLI on `PATH` for `run ` and full validation + +### Setup + +1. **Clone the template repository**: + + ```sh + git clone git@github.com:merlinhu1/codex-game-studio.git signal-cartographer + cd signal-cartographer + ``` + +2. **Install and build the CLI**: + + ```sh + npm install + npm run build + ``` + +3. **Initialize project state**: + + ```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" + ``` + +4. **Inspect and validate**: + + ```sh + ./codex-game-studio status + ./codex-game-studio validate + ./codex-game-studio run producer \ + "Create the initial market overview." --print-prompt + ``` + +## Project Structure + +```text +AGENTS.md # Game-facing Codex instructions +codex-game-studio # Source-checkout CLI wrapper +.codex/ + agents/ # 38 Codex custom agents + workflows/ # 31 tracked workflow prompts + studio.json # Project state written by init + tasks.json # File-backed task state + runs/ # Runtime metadata for role/task runs + locks/ # Local orchestration locks +.agents/ + skills/ # 79 reusable studio skills +engine_configs/ # Engine setup metadata +engine_reference/ # Godot, Unity, Unreal reference packs +templates/ # Document templates used by workflows +production/ # Timeline, milestones, session state +docs/ # Small user/docs support surface +src/ # TypeScript CLI source +tests/ # Repository validation and behavior tests ``` -For command-by-command usage, see the [User Guide](docs/user-guide.md). +## How It Works -## Why this exists +### Template First -A blank AI coding chat is flexible, but game development needs repeatable studio structure: +The clone is the studio. Agents, workflows, skills, and instruction files are committed template surfaces, not hidden generated output. `init` records project state and engine choices without copying the studio back into itself. -- Producers need milestones, handoffs, and release checks. -- Designers need GDDs, systems specs, player journeys, and tuning loops. -- Engineers need bounded implementation prompts and validation gates. -- Artists, QA, audio, localization, and live-ops work need their own context. -- Reviewers need files they can inspect in Git, not decisions trapped in chat history. +### Codex-Native Execution -Codex Game Studio keeps that structure in clone-visible template files that Codex can read and humans can review. +`run ` assembles a bounded prompt packet from the selected role, task, project state, tracked templates, and relevant context. Use `--dry-run` or `--print-prompt` to inspect before execution. -## What you get +### Reviewable State -| Capability | What it means | -| --- | --- | -| Template repository surfaces | Tracks game-facing `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, and `.agents/skills/*/SKILL.md` directly in Git. | -| Codex-native studio roles | Provides focused role contracts for production, design, engineering, art, QA, localization, and release work. | -| Workflow prompts | Provides tracked reusable workflows for market review, analytics, specs, handoffs, ship checks, UI review, and more. | -| Engine overlays | Adds Godot, Unity, or Unreal context without turning this project into an engine wrapper. | -| File-backed task state | Stores explicit tasks, locks, and run metadata under `.codex/**`. | -| Inspection before execution | Supports dry-run and prompt-print paths before Codex touches a project. | -| Hard-failing validation | Detects missing template surfaces, malformed project state, missing assets, and future-only CLI drift. | +Tasks, approvals, locks, context manifests, and run metadata live under `.codex/**`. The workflow favors ordinary Git review over opaque chat memory. -## The studio loop +### Strict Validation -```mermaid -flowchart LR - A[Clone template] --> B[Init project state] - B --> C[Tracked studio files] - C --> D[Inspect prompt] - D --> E[Run Codex role] - E --> F[Review output] - F --> G[Validate] - G --> C -``` +`./codex-game-studio validate` checks package assets, template surfaces, role/workflow metadata, project state, engine references, and hidden future-only surfaces before readiness claims. -The cloned template is the contract. It contains game-facing instructions, agents, workflows, and skills; `init` records project state, starter docs, engine references, and runtime metadata without rewriting those template surfaces. +## Model Routing -## Where details live +Prompt surfaces declare exact Codex model policy in tracked files: -| Need | Start here | -| --- | --- | +| Work type | Model | +|-----------|-------| +| Complex design, architecture, production, and release gates | `gpt-5.5` | +| Moderate implementation, QA, docs, bugfix, and bounded workflows | `gpt-5.4` | +| Simple help, status, classification, checklist, and lookup work | `gpt-5.4-mini` | + +Runtime dry-runs and run metadata expose the selected model and reasoning effort. Codex execution receives the exact selected model instead of a generic tier name. + +## Documentation + +| Need | Start Here | +|------|------------| | Install, commands, workflows, validation | [User Guide](docs/user-guide.md) | -| Role catalog and when to use each role | [Studio Roles](docs/studio-roles.md) | -| Template tree and file ownership | [Project Anatomy](docs/project-anatomy.md) | | Realistic usage scenarios | [Examples](docs/examples/README.md) | -| Contributor workflow and checks | [Development](docs/development.md) | | Full documentation map | [Docs Index](docs/README.md) | | Product boundaries and non-goals | [Product Boundary](docs/architecture/product-boundary.md) | -| Differences from Claude Code Game Studios | [Migration from Claude](docs/migration-from-claude.md) | -## Project status +## Project Status -Codex Game Studio currently supports deterministic project scaffolding, Codex role execution, workflow prompt rendering, file-backed task orchestration, and repository/project validation. +Codex Game Studio currently supports template-repository setup, Codex role execution, workflow prompt rendering, file-backed task orchestration, and repository/project validation. -The project deliberately does not expose a planner or `next` command, telemetry, hosted orchestration, unbounded parallelism, hard output-ownership enforcement, or generated `CODEX.md` / `project_orchestrator.md` surfaces. See [Known Upstream Differences](docs/known-upstream-differences.md) for migration details. +It deliberately does **not** expose a planner or `next` command, telemetry, hosted orchestration, unbounded parallelism, hard output-ownership enforcement, or generated `CODEX.md` / `project_orchestrator.md` surfaces. ## License Codex Game Studio is released under the MIT License. See [`LICENSE`](LICENSE). - -## Codex prompt model routing - -Prompt surfaces declare exact Codex model policy in tracked template files. Complex design, architecture, production, and release-gate surfaces use `gpt-5.5`; moderate implementation, QA, docs, bugfix, and bounded workflow surfaces use `gpt-5.4`; simple help, status, classification, checklist, and lookup surfaces use `gpt-5.4-mini`. Runtime dry-runs and run metadata expose the selected model and reasoning effort, and Codex execution receives the exact selected model instead of a generic tier name. diff --git a/docs/README.md b/docs/README.md index b225c43..32a70e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,73 +1,35 @@ # Codex Game Studio Docs -## Purpose +This directory is intentionally small. Keep durable user-facing guidance here and keep game-studio operating surfaces in the tracked template files: -This directory keeps detailed usage, product, architecture, validation, and repository-truth material out of the root README. +- `AGENTS.md` +- `.codex/agents/*.toml` +- `.codex/workflows/*.md` +- `.agents/skills/*/SKILL.md` -The root [README](../README.md) is the concise human storefront. Use this index when you need the next layer of detail. - -## Audience split - -### For users +## Start here | Doc | Purpose | | --- | --- | -| [User Guide](user-guide.md) | Installation, commands, role runs, workflows, tasks, validation, and troubleshooting. | -| [Setup](setup.md) | Short setup commands for source checkouts and package-bin smoke checks. | -| [Examples](examples/README.md) | Scenario-based examples inspired by the CCGS example-index style. | -| [Studio Roles](studio-roles.md) | Role catalog, role groups, and guidance for choosing the right Codex role. | -| [Project Anatomy](project-anatomy.md) | Template repository tree, file ownership, and validation-sensitive artifacts. | +| [User Guide](user-guide.md) | Installation, commands, role runs, workflow prompts, tasks, validation, and troubleshooting. | +| [Examples](examples/README.md) | Scenario-based examples for common local workflows. | +| [Product Boundary](architecture/product-boundary.md) | Implemented scope, non-goals, and boundaries. | -### For contributors +## Repository support docs | Doc | Purpose | | --- | --- | -| [Development](development.md) | Build, test, validation, package, and documentation-maintenance workflow. | -| [Workflow Validation](workflow-validation.md) | What repository and project validation check. | -| [Prompt Quality Standard](prompt-quality.md) | Source of truth for improving tracked agents, skills, and workflows. | -| [Known Upstream Differences](known-upstream-differences.md) | Intentional differences from the CCGS inspiration project. | -| [Migration from Claude](migration-from-claude.md) | Migration notes from Claude-oriented game-studio workflows. | -| [Product Boundary](architecture/product-boundary.md) | Implemented behavior, non-goals, and architecture boundaries. | +| [Repo Rules](ai/repo-rules.md) | Repository rules mirrored for agent discovery. | +| [Documentation Governance](standards/documentation-governance.md) | Rules for keeping docs concise and linked. | +| [Default Principles](standards/default-principles.md) | General project documentation principles. | -### For agents +## Truthmark support -| Doc | Purpose | -| --- | --- | -| [AGENTS.md](../AGENTS.md) | Agent entry point and repository instructions. | -| [Repo Rules](ai/repo-rules.md) | Mirrored repository-wide rules for Truthmark authority discovery. | -| [Truthmark routes](truthmark/routes/areas.md) | Route map for canonical truth docs. | -| [Product truth](truthmark/product/README.md) | Product capability promises and acceptance criteria. | -| [Engineering truth](truthmark/engineering/README.md) | Current implementation contracts, workflows, and operations. | - -## Recommended reading order - -### New user - -1. [README](../README.md) -2. [User Guide](user-guide.md) -3. [Examples](examples/README.md) -4. [Project Anatomy](project-anatomy.md) - -### Project maintainer - -1. [README](../README.md) -2. [Development](development.md) -3. [Workflow Validation](workflow-validation.md) -4. [Product Boundary](architecture/product-boundary.md) -5. Relevant Truthmark product or engineering docs - -### Agent changing behavior - -1. [AGENTS.md](../AGENTS.md) -2. [Repo Rules](ai/repo-rules.md) -3. [Product Boundary](architecture/product-boundary.md) -4. [Truthmark routes](truthmark/routes/areas.md) -5. The nearest owning product or engineering truth doc +Truthmark support files under `docs/truthmark/` are retained only where they match the Truthmark support surface. Do not add broad product-specific truth-doc sprawl here; use tracked template files, tests, and the README/user guide first. ## Update rules -- Keep the root README concise. Move command reference, role catalog, generated-file detail, and contributor workflow detail into subdocs. -- When the root README changes materially, update localized README variants under `docs/readmes/` in the same change or state why they intentionally differ. -- When a command, workflow, generated artifact, role, or validation behavior changes, update the nearest user-facing doc and the owning Truthmark doc if it is behavior-bearing. -- Do not keep parallel current-state docs for the same subject. Link to the owning doc instead of duplicating details. -- Keep scenario examples concrete and outcome-oriented, not exhaustive command dumps. +- Do not add dated plans or one-off implementation notes under `docs/`. +- Do not duplicate the agent, workflow, or skill catalogs in prose docs. +- Keep the root README concise and link here only for durable guidance. +- Prefer deleting stale docs over maintaining parallel current-state descriptions. diff --git a/docs/architecture/flows/README.md b/docs/architecture/flows/README.md deleted file mode 100644 index 99fc4c1..0000000 --- a/docs/architecture/flows/README.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -status: active -doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-05-30 -source_of_truth: - - ../repository-structure.md - - ../../truthmark/engineering/repository/overview.md ---- - -# Architecture Flow Guides - -## Purpose - -These Architecture Flow Guides document Codex 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 - -This folder uses established software-architecture documentation patterns: - -- **arc42 Runtime View**: documents concrete behavior, interactions between building blocks, important scenarios, operational flows, and error/exception scenarios. -- **C4 dynamic views**: describe how architecture elements interact at runtime when a static structure view is not enough. -- **Diátaxis explanation/how-to separation**: these guides explain and navigate flows; Truthmark truth docs remain the canonical reference layer. -- **Mermaid in Markdown**: sequence and flowchart diagrams are embedded directly in Markdown so the diagrams stay close to the walkthrough text. - -## Relationship To Truthmark Truth Docs - -Truthmark truth docs own canonical behavior claims. Architecture flow guides own comprehension. - -| Layer | Purpose | Example | -| --- | --- | --- | -| Truth docs | Bounded, canonical behavior/reference claims | `docs/truthmark/engineering/codex/runtime-and-tasks.md` | -| Flow guides | Cross-cutting runtime scenarios, branches, and debugging paths | `docs/architecture/flows/role-run-lifecycle.md` | -| Portal | Generated non-canonical presentation | `docs/truthmark/generated/portal/` | - -If a flow guide conflicts with source code or a truth doc, the source code and owning truth doc win. Update the owning truth doc first, then update the affected flow guide. - -## Flow Index - -| Flow guide | Scenario | Primary truth docs | -| --- | --- | --- | -| [Project Initialization](project-initialization.md) | `init` / `new` creates a deterministic generated game project. | `docs/truthmark/engineering/projects/project-scaffolding.md` | -| [Role Run Lifecycle](role-run-lifecycle.md) | `run ` renders, executes, verifies, reviews, and optionally fixes a Codex role run. | `docs/truthmark/engineering/codex/runtime-and-tasks.md`, `docs/truthmark/engineering/codex/roles-and-workflows.md` | -| [Workflow Prompt Rendering](workflow-prompt-rendering.md) | Workflow shortcut commands render deterministic prompts without executing Codex. | `docs/truthmark/engineering/codex/roles-and-workflows.md` | -| [Validation And Repository Truth](validation-and-repository-truth.md) | Repository/project validation and injected Truthmark repository-truth workflows around behavior changes. | `docs/truthmark/engineering/contracts/cli-and-validation.md`, `docs/truthmark/engineering/repository/overview.md` | - -## Guide Template - -Each flow guide should include: - -1. Purpose and scenario boundary. -2. Entry points. -3. Preconditions and inputs. -4. Happy path sequence. -5. Branch map. -6. Decision table. -7. Failure modes and debugging cues. -8. Code traceability. -9. Truth sources and verification. - -## Maintenance Rules - -- Keep these guides focused on architecturally relevant scenarios, not every internal helper call. -- Do not use flow guides to introduce new behavior claims that are absent from source and truth docs. -- When behavior changes, update the owning truth doc and then any impacted flow guide. -- Keep Truthmark framed as an injected repository-truth workflow/tooling layer unless product code explicitly implements Truthmark-facing runtime behavior. diff --git a/docs/architecture/flows/project-initialization.md b/docs/architecture/flows/project-initialization.md deleted file mode 100644 index 76bf663..0000000 --- a/docs/architecture/flows/project-initialization.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -status: active -doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-06-29 -source_of_truth: - - ../../truthmark/engineering/projects/project-scaffolding.md - - ../../truthmark/engineering/repository/overview.md - - ../repository-structure.md ---- - -# Project Initialization Flow Guide - -## Purpose - -This architecture flow guide documents `codex-game-studio init` and `codex-game-studio new`. - -Both commands use the same initialization path to configure project-specific state in the current repository root. - -## Scope - -This flow starts when a user invokes `init` or `new` with required project options. - -It ends when the repository root has engine markers, `.codex` project state, starter docs, and selected engine references. - -It does not create, copy, or overwrite tracked template instruction files. - -It does not execute Codex and does not own task lifecycle persistence after project creation. - -## Boundaries - -Project initialization owns project-state creation and initial `.codex` state. - -Tracked template surfaces are clone-time repository files, not init outputs. - -Codex run execution, task lifecycle persistence, and verification/review behavior are owned by separate runtime flows and truth docs. - -## Entry Points - -| Entry point | Role in flow | Code | -| --- | --- | --- | -| `codex-game-studio init` | Primary project initialization command. | `src/cli.ts` | -| `codex-game-studio new` | Alias that delegates to the same initialization path. | `src/cli.ts` | -| `initProject(...)` | Creates project config, directories, state, docs, and engine references. | `src/projects.ts` | - -## Preconditions - -- The user supplies `--name`, `--engine`, `--mode`, and `--non-interactive`. -- The selected engine is known by the engine registry. -- The target root either has no `.codex/studio.json` or is force-refreshed for the same project intent. -- Same-parent project slug and Unreal class-name collision checks pass. -- Game-facing template files are expected to exist because the user cloned the template repository. - -## Inputs - -| Input | Source | Required | Notes | -| --- | --- | ---: | --- | -| Project name | `--name` | yes | Used for config and slug derivation. | -| Engine | `--engine` | yes | Must resolve to a supported engine registry entry. | -| Mode | `--mode` | yes | Selects active project/studio mode. | -| Non-interactive flag | `--non-interactive` | yes | Enforces deterministic scaffolding. | -| Concept/genre/platform/audience/etc. | Optional CLI flags | no | Written into starter planning artifacts where applicable. | -| Engine version override | `--engine-version` | no | Overrides default engine context. | - -## Happy Path Sequence - -```mermaid -sequenceDiagram - actor User - participant CLI as src/cli.ts - participant Projects as src/projects.ts - participant Config as src/config.ts - participant Engines as src/engines.ts - participant FS as Project files - - User->>CLI: init/new --name --engine --mode --non-interactive - CLI->>Projects: initProject(options) - Projects->>Config: normalize project config and slug - Projects->>Projects: reject target/collision conflicts - Projects->>Engines: resolve engine scaffold - Projects->>FS: create project and engine folders - Projects->>FS: write .codex/studio.json and .codex/runs/ - Projects->>FS: write starter docs and selected engine references - Projects->>FS: write context manifest and project config - Projects-->>CLI: project root and config - CLI-->>User: Created at -``` - -## Branch Map - -```mermaid -flowchart TD - A[User runs init or new] --> B{Required options present?} - B -- no --> B1[Commander reports missing required option] - B -- yes --> C{--non-interactive present?} - C -- no --> C1[Fail: deterministic non-interactive mode required] - C -- yes --> D[Normalize config and derive slug] - D --> E{Engine known?} - E -- no --> E1[Fail: invalid engine] - E -- yes --> F{Target or same-parent collision?} - F -- yes --> F1[Fail before writing project files] - F -- no --> G{Unreal class-name collision?} - G -- yes --> G1[Fail before writing project files] - G -- no --> H[Create engine/project folders] - H --> I[Write .codex state and run directory] - I --> J[Write starter docs and context manifest] - J --> K[Return created project path] -``` - -## Decision Table - -| Condition | Branch | Behavior | User-visible result | Owning code/truth | -| --- | --- | --- | --- | --- | -| Required option missing | CLI parse failure | Stop before initialization. | Commander error. | `src/cli.ts`; `docs/truthmark/engineering/contracts/cli-and-validation.md` | -| `--non-interactive` missing | Determinism guard | Stop before writing. | Required option error. | `src/cli.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | -| Engine is unknown | Engine registry guard | Stop before writing. | Invalid engine/lookup failure. | `src/engines.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | -| Target path exists | Collision guard | Stop before mutating target. | Existing project/path error. | `src/projects.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | -| Collision checks pass | Happy path | Write project state and starter assets. | `Created at `. | `src/projects.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | - -## Init Outputs - -The successful flow creates or writes: - -- `.codex/studio.json` -- `.codex/runs/` -- `.codex/approvals.json` -- `.codex/studio/config.json` -- `.codex/context-manifest.json` -- `.codex/context-manifest.meta.json` -- starter design/production/market documents -- selected engine reference files -- engine-specific marker files and source folders - -The successful flow does not write: - -- `AGENTS.md` -- `.codex/agents/*.toml` -- `.codex/workflows/*.md` -- `.agents/skills/*/SKILL.md` -- `.codex/prompts/**` - -Forbidden generated project surfaces remain forbidden: `CODEX.md`, `project_orchestrator.md`, and `.gamestudio/runs`. - -## Failure Modes And Debugging Cues - -| Failure | Likely cause | Inspect | -| --- | --- | --- | -| Required-option failure | CLI command missing required flags. | `src/cli.ts` command definitions. | -| Invalid engine | Engine value not recognized or engine registry changed. | `src/engines.ts`, `engine_configs/**`. | -| Target collision | Root `.codex/studio.json` belongs to a different project. | Project state loading in `src/projects.ts`. | -| Project state missing in validation | Scaffolding contract drift. | `src/projects.ts`, `src/validation.ts`. | -| Template surface missing in validation | Clone/template surface drift. | `AGENTS.md`, `.codex/agents/**`, `.codex/workflows/**`, `.agents/skills/**`, `src/validation.ts`. | - -## Code Traceability - -| Behavior | Code | -| --- | --- | -| Command wiring and required options | `src/cli.ts` | -| Project creation and collision checks | `src/projects.ts` | -| Config normalization | `src/config.ts` | -| Engine-specific scaffold | `src/engines.ts`, `engine_configs/**` | -| Runtime role metadata | `src/agents.ts`, `src/roles.ts` | -| Path/slug helpers | `src/paths.ts` | -| Project validation checks | `src/validation.ts` | - -## Product Decisions - -- Project creation remains deterministic and non-interactive for reproducible Codex project setup. -- Template instructions use tracked Codex-native `AGENTS.md`, `.codex/agents`, `.codex/workflows`, and `.agents/skills` files. -- This flow does not introduce `CODEX.md` as a primary project instruction contract. -- This flow does not generate `.codex/prompts/**` mirrors. - -## Rationale - -A bounded initialization flow gives users and agents stable project state without implying that scaffolding also executes Codex, manages planner state, owns later runtime task transitions, or regenerates template instructions. - -## Truth Sources - -- `docs/truthmark/engineering/projects/project-scaffolding.md` -- `docs/truthmark/engineering/repository/overview.md` -- `docs/truthmark/engineering/contracts/cli-and-validation.md` -- `docs/truthmark/routes/areas/repository.md` - -## Verification - -For behavior changes in this flow, run the relevant project workflow, engine-system, template-surface, and validation tests. - -For repository-wide readiness claims, run: - -```bash -npm run validate -truthmark check --json -``` diff --git a/docs/architecture/flows/role-run-lifecycle.md b/docs/architecture/flows/role-run-lifecycle.md deleted file mode 100644 index b8cdbfe..0000000 --- a/docs/architecture/flows/role-run-lifecycle.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -status: active -doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-05-30 -source_of_truth: - - ../../truthmark/engineering/codex/runtime-and-tasks.md - - ../../truthmark/engineering/codex/roles-and-workflows.md - - ../../truthmark/engineering/contracts/cli-and-validation.md ---- - -# Role Run Lifecycle Flow Guide - -## Purpose - -This architecture flow guide documents the runtime scenario for `codex-game-studio run `. The flow prepares a deterministic Codex prompt, optionally returns inspection output, and otherwise executes a bounded implementation/verification/review/fix lifecycle. - -## Scope - -This flow starts when a user invokes `run ... --project `. It ends when the CLI reports `done` or `blocked`, or when an inspection-only branch returns prompt/dry-run output without side effects. - -This flow consumes role/workflow prompt contracts but does not own the content of each role package. - -## Boundaries - -The role run lifecycle owns runtime preparation, prompt inspection branches, Codex availability checks, implementation execution, optional verification, review, and bounded fix passes. Role definitions, generated workflow prompt contents, and project scaffolding are owned by adjacent truth docs and flows. - -## Entry Points - -| Entry point | Role in flow | Code | -| --- | --- | --- | -| `codex-game-studio run ` | Public CLI command for role execution. | `src/cli.ts` | -| `prepareRun(...)` | Resolves project, validates role/task input, renders prompt, builds cache paths and Codex command. | `src/runner.ts` | -| `checkCodexAvailability(...)` | Confirms Codex can be executed before non-dry runs. | `src/codex-runtime.ts` | -| `executeRunLifecycle(...)` | Runs implementation, verification, review, and bounded fix passes. | `src/runner.ts` | - -## Preconditions - -- `--project ` points to a valid generated project with `.codex/studio.json`. -- The requested role is a canonical studio role ID. -- The task/objective is non-empty, either from positional objective text or `--task`. -- Codex availability is required only for non-dry, non-print execution. - -## Inputs - -| Input | Source | Required | Notes | -| --- | --- | ---: | --- | -| Role ID | positional `` | yes | Must be a canonical hyphenated studio role ID. | -| Objective/task | positional objective or `--task` | yes | Drives prompt body. | -| Project path | `--project` | yes | Resolves `.codex/studio.json`. | -| Included artifacts | `--include-artifact` | no | Adds explicit project artifacts to context. | -| Broad context flag | `--allow-broad-context` | no | Allows broader context discovery. | -| Verification command | `--verify-command`, `--verify-arg` | no | Runs after implementation when configured. | -| Review flag | `--review` | no | Adds read-only review pass. | -| Fix flag/count | `--fix`, `--max-fix-passes` | no | Enables bounded fix passes when blocked. | -| Inspection flags | `--print-prompt`, `--dry-run` | no | Non-mutating inspection branches. | - -## Happy Path Sequence - -```mermaid -sequenceDiagram - actor User - participant CLI as src/cli.ts - participant Runner as src/runner.ts - participant Prompts as Prompt rendering - participant Runtime as src/codex-runtime.ts - participant Verification as src/verification.ts - participant FS as .codex/runs - - User->>CLI: run objective --project - CLI->>Runner: prepareRun(role, options) - Runner->>Prompts: render role/session prompt - Prompts-->>Runner: prompt, context files, command - Runner-->>CLI: prepared output and Codex command - CLI->>Runtime: checkCodexAvailability(command) - Runtime-->>CLI: available - CLI->>Runner: executeRunLifecycle(prepared) - Runner->>FS: write prompt and metadata cache - Runner->>Runtime: execute implementation prompt - Runtime-->>Runner: implementation result - Runner->>Verification: run verification when configured - Verification-->>Runner: verification result - Runner-->>CLI: final status done or blocked - CLI-->>User: lifecycle summary -``` - -## Branch Map - -```mermaid -flowchart TD - A[run role command] --> B{Project valid?} - B -- no --> B1[Fail before prompt execution] - B -- yes --> C{Role valid?} - C -- no --> C1[Unknown role error with canonical role IDs] - C -- yes --> D{Task/objective non-empty?} - D -- no --> D1[Fail before prompt execution] - D -- yes --> E[Render deterministic prompt and context] - E --> F{--print-prompt?} - F -- yes --> F1[Print prompt only; no mutation] - F -- no --> G{--dry-run?} - G -- yes --> G1[Print context and command only; no mutation] - G -- no --> H{Codex available?} - H -- no --> H1[Report Codex unavailable; exit non-zero] - H -- yes --> I[Write prompt and metadata cache] - I --> J[Execute implementation prompt] - J --> K{Implementation succeeded?} - K -- no --> K1[Blocked] - K -- yes --> L{Verification configured?} - L -- yes --> M[Run verification] - L -- no --> N{Review requested?} - M --> M1{Verification passed?} - M1 -- no --> O[Blocked] - M1 -- yes --> N - N -- yes --> P[Run read-only review] - N -- no --> R[Done] - P --> Q{Review blockers?} - Q -- no --> R - Q -- yes --> S{Fix requested and passes remain?} - S -- no --> O - S -- yes --> T[Run workspace-write fix pass] - T --> L -``` - -## Decision Table - -| Condition | Branch | Behavior | User-visible result | Side effects | -| --- | --- | --- | --- | --- | -| Invalid project | Project resolution failure | Stop before execution. | Error from project/task resolution. | No run cache. | -| Unknown role | Role validation failure | Stop before execution. | Message points to canonical role IDs. | No run cache. | -| `--print-prompt` | Prompt inspection | Render and print prompt body. | Prompt text. | No prompt cache, metadata, task state, or run directory writes. | -| `--dry-run` | Command/context inspection | Print selected context and Codex command. | Dry-run summary. | No prompt cache, metadata, task state, or run directory writes. | -| Codex unavailable | Runtime guard | Stop before lifecycle execution. | Availability/authentication error. | No lifecycle execution. | -| Verification fails | Verification blocker | Mark lifecycle blocked unless fix passes clear it. | Final status `blocked`. | Non-dry cache already written. | -| Review blockers found | Review blocker | Run bounded fix passes only when requested and available. | `blocked` or subsequent `done`. | Review uses read-only sandbox; fix uses workspace-write sandbox. | -| All required passes clear | Happy path | Report completion. | Final status `done`. | Non-dry run cache exists. | - -## State And Mutation Rules - -- `--print-prompt` and `--dry-run` are inspection-only and do not write prompt cache, metadata, task state, or run directories. -- Non-dry runs write prompt and metadata before executing Codex. -- Implementation and fix passes use a workspace-write Codex sandbox. -- Review passes use a read-only Codex sandbox. -- Final lifecycle status is `done` or `blocked`. - -## Failure Modes And Debugging Cues - -| Failure | Likely cause | Inspect | -| --- | --- | --- | -| Unknown role | Role ID typo or role registry drift. | `src/roles.ts`, `docs/truthmark/engineering/codex/roles-and-workflows.md`. | -| Empty objective | User omitted objective and `--task`. | `src/cli.ts`, `src/runner.ts`. | -| Codex unavailable | CLI missing, unauthenticated, or command path invalid. | `src/codex-runtime.ts`. | -| Verification timeout/failure | Verification command failed or exceeded timeout. | `src/verification.ts`, command output. | -| Malformed review JSON | Review pass did not produce expected schema. | `src/runner.ts`, review prompt contract. | -| Repeated blocked status | Implementation, verification, or review blockers not cleared by bounded fix passes. | Run lifecycle output and `.codex/runs/` metadata. | - -## Code Traceability - -| Behavior | Code | -| --- | --- | -| CLI option parsing and inspection branch exit | `src/cli.ts` | -| Run preparation, prompt/cache metadata, lifecycle orchestration | `src/runner.ts` | -| Role IDs and unknown-role message | `src/roles.ts` | -| Prompt/session rendering inputs | `src/codex-session.ts`, `src/codex-prompts.ts` | -| Codex availability and command execution | `src/codex-runtime.ts` | -| Verification command execution and timeout behavior | `src/verification.ts` | -| File-backed task mutation when running tasks | `src/tasks.ts` | - -## Product Decisions - -- `--print-prompt` and `--dry-run` stay inspection-only and do not mutate run state. -- Non-dry role runs explicitly execute Codex and report a final `done` or `blocked` status. -- Review is read-only; fix passes are bounded and workspace-write. - -## Rationale - -Separating inspection, implementation, verification, review, and fix branches makes the Codex lifecycle auditable without inventing hidden planner, telemetry, ownership enforcement, hosted/background orchestration, or unbounded parallel behavior. - -## Truth Sources - -- `docs/truthmark/engineering/codex/runtime-and-tasks.md` -- `docs/truthmark/engineering/codex/roles-and-workflows.md` -- `docs/truthmark/engineering/contracts/cli-and-validation.md` -- `docs/truthmark/routes/areas/repository.md` - -## Verification - -For behavior changes in this flow, run runner, task, verification, Codex runtime, role, and prompt/session tests as relevant. For repository-wide readiness claims, run: - -```bash -npm run validate -npx truthmark check --json -``` diff --git a/docs/architecture/flows/validation-and-repository-truth.md b/docs/architecture/flows/validation-and-repository-truth.md deleted file mode 100644 index 7cdc2cf..0000000 --- a/docs/architecture/flows/validation-and-repository-truth.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -status: active -doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-05-30 -source_of_truth: - - ../../truthmark/engineering/contracts/cli-and-validation.md - - ../../truthmark/engineering/repository/overview.md - - ../../truthmark/routes/areas/repository.md ---- - -# Validation And Repository Truth Flow Guide - -## Purpose - -This architecture flow guide documents the validation path around Codex Game Studio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates. - -Validation is an Codex 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 Codex Game Studio runtime feature unless product code explicitly implements Truthmark-facing behavior. - -## Scope - -This guide covers two related but separate flows: - -1. `codex-game-studio validate` / `npm run validate` checks package and generated-project contracts. -2. `npx truthmark check --json` checks repository-truth routing and generated Truthmark surfaces. - -The guide ends when validation/truth checks have either passed or produced diagnostics that identify the broken contract. - -## Boundaries - -Repository validation is an Codex 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 Codex Game Studio runtime feature. - -## Entry Points - -| Entry point | Role in flow | Code / owner | -| --- | --- | --- | -| `codex-game-studio validate` | Public CLI validation command. | `src/cli.ts`, `src/validation.ts` | -| `npm run validate` | Repository readiness gate that builds/tests/validates through package scripts. | `package.json` | -| `npx truthmark check --json` | Injected repository-truth consistency check. | Truthmark tooling, `.truthmark/config.yml` | -| Truthmark route files | Map code surfaces to bounded truth docs. | `docs/truthmark/routes/areas.md`, `docs/truthmark/routes/areas/repository.md` | -| Truth docs | Canonical bounded behavior/reference docs. | `docs/truthmark/engineering/**` | - -## Preconditions - -- Repository validation expects package metadata, source files, templates, engine configs, and build output to match the package contract. -- Project validation expects a generated project with valid `.codex/studio.json` when `--project ` is supplied. -- Truthmark checks expect `.truthmark/config.yml` and configured route/truth docs to remain internally consistent when present. - -## Inputs - -| Input | Source | Required | Notes | -| --- | --- | ---: | --- | -| Repository files | Worktree | yes | Package metadata, source, templates, engine configs, generated surfaces. | -| Project path | `--project` | no | Adds generated-project validation checks. | -| Truthmark config | `.truthmark/config.yml` | for Truthmark checks | Configures doc roots, routes, and generated surfaces. | -| Route docs | `docs/truthmark/routes/areas*.md` | for Truthmark checks | Map code/doc surfaces to bounded truth docs. | -| Truth docs | `docs/truthmark/engineering/**` | for Truthmark checks | Canonical behavior/reference claims. | - -## Happy Path Sequence - -```mermaid -sequenceDiagram - actor Contributor - participant Repo as Git worktree - participant Validate as src/validation.ts - participant Truth as Truthmark check - participant Docs as docs/truth and docs/architecture - - Contributor->>Repo: change code or docs - Contributor->>Validate: npm run validate / codex-game-studio validate - Validate->>Repo: check package, source, templates, build, generated project contracts - Validate-->>Contributor: all checks pass - alt behavior claim changed - Contributor->>Docs: update owning truth doc first - Contributor->>Docs: update affected flow guide if runtime scenario changed - end - Contributor->>Truth: npx truthmark check --json - Truth->>Docs: check config, routes, truth visibility, generated surfaces - Truth-->>Contributor: no diagnostics -``` - -## Branch Map - -```mermaid -flowchart TD - A[Repository change] --> B{Functional behavior changed?} - B -- yes --> C[Run relevant tests and npm run validate] - B -- no --> D{Docs/truth/routing changed?} - C --> E{Validation passed?} - E -- no --> E1[Fix package/project contract diagnostics] - E -- yes --> F{Truth claim affected?} - F -- yes --> G[Update owning Truthmark truth doc] - F -- no --> H[No truth-doc change needed] - G --> I{Runtime scenario comprehension affected?} - H --> I - D -- yes --> J[Run npx truthmark check --json] - D -- no --> K[No validation gate beyond normal review] - I -- yes --> L[Update architecture flow guide] - I -- no --> J - L --> J - J --> M{Truthmark diagnostics?} - M -- yes --> M1[Repair routing/truth/generated-surface issue] - M -- no --> N[Reviewable] -``` - -## Decision Table - -| 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. | Codex Game Studio repo | -| Template/project behavior changed | Project validation branch | Validate template and project-state contracts. | Missing/invalid template or project-state 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/truthmark/engineering/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 | -| Flow comprehension changed | Runtime-view branch | Update affected architecture flow guide after truth doc. | Stale walkthrough if missed. | `docs/architecture/flows/**` | -| Truthmark generated surface changed | Injected workflow branch | Preserve managed blocks and run Truthmark check/init only when appropriate. | Generated surface diagnostic. | Truthmark tooling layer | - -## Failure Modes And Debugging Cues - -| Failure | Likely cause | Inspect | -| --- | --- | --- | -| Validation check fails | Package metadata, source, templates, build output, or project scaffold drift. | `src/validation.ts`, failing check ID. | -| Future-surface guard fails | CLI/docs exposed unimplemented planner/telemetry/parallel/ownership surface. | `src/cli.ts`, README/docs, validation tests. | -| Truthmark reports route/topology issue | Code or docs moved outside bounded route ownership. | `docs/truthmark/routes/areas.md`, `docs/truthmark/routes/areas/repository.md`. | -| Truth doc and flow guide diverge | Flow guide was updated without updating canonical truth or vice versa. | Owning `docs/truthmark/engineering/**` file and affected `docs/architecture/flows/**` file. | -| Portal output stale | Generated non-canonical site not refreshed after Markdown changes. | `docs/truthmark/generated/portal/` and portal provenance. | - -## Code And Document Traceability - -| Behavior / concern | Owner | -| --- | --- | -| CLI validation command wiring | `src/cli.ts` | -| Validation checks and project contract diagnostics | `src/validation.ts` | -| Package scripts/bin/files contract | `package.json`, `docs/truthmark/engineering/contracts/cli-and-validation.md` | -| Truthmark config and generated workflow surfaces | `.truthmark/config.yml`, generated agent files | -| Truth routing | `docs/truthmark/routes/areas.md`, `docs/truthmark/routes/areas/repository.md` | -| Bounded canonical behavior docs | `docs/truthmark/engineering/**` | -| Cross-cutting runtime scenario explanations | `docs/architecture/flows/**` | -| Generated presentation output | `docs/truthmark/generated/portal/` | - -## 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 Codex Game Studio runtime behavior. -- Markdown truth docs remain canonical; generated portal HTML remains non-canonical presentation. - -## Rationale - -Keeping validation and repository-truth checks adjacent but distinct prevents injected Truthmark workflow scaffolding from being mistaken for product functionality while still making documentation authority auditable. - -## Truth Sources - -- `docs/truthmark/engineering/contracts/cli-and-validation.md` -- `docs/truthmark/engineering/repository/overview.md` -- `docs/truthmark/routes/areas/repository.md` -- `.truthmark/config.yml` - -## Verification - -For behavior changes, run relevant tests and: - -```bash -npm run validate -``` - -For repository-truth docs/routing/generated-surface changes, run: - -```bash -npx truthmark check --json -``` - -When both behavior and truth docs change, run both gates. diff --git a/docs/architecture/flows/workflow-prompt-rendering.md b/docs/architecture/flows/workflow-prompt-rendering.md deleted file mode 100644 index 210c7b3..0000000 --- a/docs/architecture/flows/workflow-prompt-rendering.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -status: active -doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-05-30 -source_of_truth: - - ../../truthmark/engineering/codex/roles-and-workflows.md - - ../../truthmark/engineering/contracts/cli-and-validation.md ---- - -# Workflow Prompt Rendering Flow Guide - -## Purpose - -This architecture flow guide documents render-only workflow shortcut commands such as `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff`, `review`, and `ship-check`. - -These commands produce deterministic Codex prompts for workflow scenarios without launching Codex or implying hidden orchestration. - -## Scope - -This flow starts when a user invokes a workflow shortcut with `--project `. It ends when the CLI prints the rendered workflow prompt. - -This flow does **not** execute Codex, does **not** write run cache metadata, and does **not** create a planner/next queue. - -## Boundaries - -Workflow prompt rendering owns deterministic prompt text for workflow shortcut commands. It does not own Codex runtime execution, task status mutation, generated project scaffolding, or future-only planner/telemetry/orchestration surfaces. - -## Entry Points - -| Entry point | Role in flow | Code | -| --- | --- | --- | -| Workflow CLI aliases | Public render-only commands for selected workflow IDs. | `src/cli.ts`, `src/workflows.ts` | -| `review` and `ship-check` commands | Render prompts for explicit workflow IDs without requiring a role run. | `src/cli.ts` | -| `renderWorkflowPrompt(...)` | Resolves project state and renders workflow prompt content. | `src/workflows.ts` | -| Template registry | Supplies optional template bodies when a workflow needs them. | `src/templates.ts`, `templates/**` | - -## Preconditions - -- `--project ` resolves to a valid generated project. -- `.codex/studio.json` contains engine/project context required by the workflow prompt. -- The requested workflow ID or alias exists in the workflow registry. -- Any required template body is present and valid. - -## Inputs - -| Input | Source | Required | Notes | -| --- | --- | ---: | --- | -| Workflow alias/ID | CLI command | yes | Maps to a workflow registry entry. | -| Project path | `--project` | yes | Provides project and engine context. | -| Dry-run flag | `--dry-run` | no | Accepted as render-only wording; command already does not launch Codex. | -| Template bodies | package assets | no/conditional | Appended when selected by workflow/template rules. | - -## Happy Path Sequence - -```mermaid -sequenceDiagram - actor User - participant CLI as src/cli.ts - participant Tasks as src/tasks.ts - participant Workflows as src/workflows.ts - participant Templates as src/templates.ts - participant FS as Project/package files - - User->>CLI: workflow-alias --project - CLI->>Tasks: resolveTaskProject(project) - Tasks-->>CLI: project root - CLI->>Workflows: renderWorkflowPrompt(projectRoot, workflowId) - Workflows->>FS: read .codex/studio.json - Workflows->>Workflows: look up workflow registry entry - Workflows->>Templates: select/read applicable template bodies - Templates-->>Workflows: template content - Workflows-->>CLI: rendered prompt - CLI-->>User: prompt text -``` - -## Branch Map - -```mermaid -flowchart TD - A[User runs workflow shortcut] --> B{Project path valid?} - B -- no --> B1[Fail before rendering] - B -- yes --> C[Read project state] - C --> D{Workflow alias/ID exists?} - D -- no --> D1[Unknown workflow/command path] - D -- yes --> E[Create workflow session context] - E --> F{Templates required or applicable?} - F -- no --> G[Render base workflow prompt] - F -- yes --> H{Template bodies valid?} - H -- no --> H1[Fail validation/rendering] - H -- yes --> I[Append template bodies] - G --> J[Print prompt only] - I --> J -``` - -## Decision Table - -| Condition | Branch | Behavior | User-visible result | Side effects | -| --- | --- | --- | --- | --- | -| Project invalid | Project resolution failure | Stop before rendering. | Error from project resolution. | None. | -| Workflow command exists | Happy path | Render workflow prompt for configured workflow ID. | Prompt text. | None. | -| Applicable template exists | Template append branch | Add template content to prompt. | Prompt text includes template body. | None. | -| Template invalid/missing | Template validation/render failure | Stop or fail validation depending on call path. | Error or validation failure. | None. | -| User expects execution | Non-goal branch | Command still only renders prompt. | Prompt text only. | Codex is not launched. | - -## Render-Only Rules - -- Workflow shortcut commands render prompts and return text. -- They do not call Codex. -- They do not write `.codex/runs/` cache files. -- They do not mutate `.codex/studio.json` or `.codex/tasks.json`. -- They do not expose hidden planner, telemetry, ownership enforcement, hosted/background orchestration, or unbounded parallel behavior. Explicit task orchestration belongs in task/run lifecycle commands, not render-only shortcut output. - -## Failure Modes And Debugging Cues - -| Failure | Likely cause | Inspect | -| --- | --- | --- | -| Project resolution failure | Missing or invalid `.codex/studio.json`. | `src/tasks.ts`, generated project state. | -| Alias drift | CLI alias and workflow registry diverged. | `src/cli.ts`, `src/workflows.ts`. | -| Missing template content | Package asset drift or template registry error. | `src/templates.ts`, `templates/**`, package files. | -| Prompt claim overstates automation | Documentation or prompt text implies unimplemented planner/execution behavior. | `src/workflows.ts`, `docs/truthmark/engineering/codex/roles-and-workflows.md`. | - -## Code Traceability - -| Behavior | Code | -| --- | --- | -| Workflow command registration | `src/cli.ts` | -| Workflow registry and prompt rendering | `src/workflows.ts` | -| Project path validation used by workflow commands | `src/tasks.ts` | -| Template lookup, rendering, and required-section validation | `src/templates.ts`, `templates/**` | -| Validation of workflow/prompt contracts | `src/validation.ts` | - -## Product Decisions - -- Workflow shortcut commands remain render-only prompt surfaces. -- Prompt rendering may include templates, but it must not imply unimplemented planner, execution, telemetry, or ownership-enforcement behavior. - -## Rationale - -Keeping workflow commands render-only lets users inspect and hand off workflow prompts while avoiding hidden side effects or undocumented automation. - -## Truth Sources - -- `docs/truthmark/engineering/codex/roles-and-workflows.md` -- `docs/truthmark/engineering/contracts/cli-and-validation.md` -- `docs/truthmark/engineering/repository/overview.md` -- `docs/truthmark/routes/areas/repository.md` - -## Verification - -For behavior changes in this flow, run workflow, template, Codex prompt/session, and validation tests as relevant. For repository-wide readiness claims, run: - -```bash -npm run validate -npx truthmark check --json -``` diff --git a/docs/architecture/product-boundary.md b/docs/architecture/product-boundary.md index f284349..35dcf98 100644 --- a/docs/architecture/product-boundary.md +++ b/docs/architecture/product-boundary.md @@ -1,28 +1,23 @@ --- status: active doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-06-25 +last_reviewed: 2026-06-29 source_of_truth: - ../../README.md - ../../AGENTS.md - - ../truthmark/engineering/repository/overview.md - - ../truthmark/engineering/codex/runtime-and-tasks.md - - ../truthmark/engineering/codex/roles-and-workflows.md - - ../truthmark/engineering/contracts/cli-and-validation.md --- # Codex Game Studio Product Boundary **Audience:** humans and agents designing, planning, or changing Codex Game Studio. -**Use:** read this before creating or revising product designs, implementation plans, OpenSpec changes, role/workflow expansions, approval policy, generated project surfaces, or runtime execution behavior. +**Use:** read this before creating or revising product designs, implementation plans, OpenSpec changes, role/workflow expansions, approval policy, tracked template and project-state surfaces, or runtime execution behavior. ## Mission Codex Game Studio helps developers use Codex as a practical game-development studio inside a local repository. -The product should make it easier to start, plan, build, review, and ship games by providing a package-friendly TypeScript CLI that creates project scaffolds, renders bounded Codex prompts, manages game-studio roles and workflows, records auditable project state, and validates the generated surfaces. +The product should make it easier to start, plan, build, review, and ship games by providing a package-friendly TypeScript CLI that creates project scaffolds, renders bounded Codex prompts, manages game-studio roles and workflows, records auditable project state, and validates the tracked template and project-state surfaces. The product exists to expand what a developer can do with Codex for game creation. It may orchestrate role-scoped Codex work when the plan, state, permissions, and handoffs stay explicit and reviewable. It must not turn game development into mandatory studio ceremony, hide the developer's intent behind an opaque orchestrator, or replace human creative and technical judgment. @@ -32,7 +27,7 @@ Codex Game Studio is: - a local-first CLI and package for game-development repository workflows; - Codex-native in its primary execution path; -- oriented around generated project files such as `AGENTS.md`, `.codex/**`, templates, tasks, and validation output; +- oriented around tracked template files such as `AGENTS.md`, `.codex/**`, templates, tasks, and validation output; - useful for both solo/prototype work and more structured studio-style work; - allowed to provide bounded task orchestration for role-scoped Codex runs when it remains local, explicit, file-backed, policy-gated, and validated; - explicit about when it is rendering prompts, planning tasks, orchestrating task runs, running Codex, mutating project state, or only inspecting planned behavior. @@ -56,7 +51,7 @@ External tools, reference workflows, and comparison projects may inspire improve 3. **Local repository files stay reviewable.** Project state, prompts, tasks, approvals, templates, and validation evidence should be visible in the working tree or deterministic CLI output, not hidden in off-repo services. 4. **Developer control comes first.** Studio depth is optional and mode-controlled. Fast prototype workflows must remain lightweight; orchestration and strict approval flows must be explicit rather than silently imposed on every project. 5. **Project stage and studio strictness are separate.** Lifecycle stage (`design`, `prototype`, `development`) must not be collapsed into process strictness (`fast-prototype`, `guided-studio`, `strict-studio`). -6. **Generated instructions use `AGENTS.md` and `.codex/**`.** Do not add `CODEX.md`, legacy generated-project compatibility shims, or alternate instruction contracts unless a future boundary update explicitly changes this rule. +6. **Tracked instructions use `AGENTS.md` and `.codex/**`.** Do not add `CODEX.md`, legacy generated-project compatibility shims, or alternate instruction contracts unless a future boundary update explicitly changes this rule. 7. **Depth comes from selected context, not prompt bloat.** Registries may contain rich roles, workflows, engine references, and rules, but generated prompts and task packets should include only relevant selected material. 8. **Mutation is policy-gated and visible.** Any design that lets Codex or the CLI mutate files must specify write policy, approval/override behavior, sandbox selection, dry-run diagnostics, and where provenance is recorded. 9. **Future-only surfaces must remain absent until built.** Planner/next, telemetry, hard output-ownership enforcement, hosted orchestration, background autonomous loops, and unbounded parallelism must not appear as user-facing behavior before they have implementation, tests, and docs. diff --git a/docs/architecture/repository-structure.md b/docs/architecture/repository-structure.md deleted file mode 100644 index e480846..0000000 --- a/docs/architecture/repository-structure.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -status: active -doc_type: architecture -truth_kind: architecture -last_reviewed: 2026-05-28 -source_of_truth: - - ../truthmark/routes/areas/repository.md ---- - -# Repository Structure - -## Purpose - -Codex Game Studio is a Node/TypeScript CLI package that installs and operates Codex-native game studio project workflows. - -## Scope - -This architecture note records the top-level repository boundaries needed by Truthmark routing. Product mission and non-goal guardrails live in `docs/architecture/product-boundary.md`. Bounded behavior details live in leaf docs under `docs/truthmark/engineering/**`; cross-cutting runtime scenario walkthroughs live in `docs/architecture/flows/**`. - -## Components - -- CLI command surface: `src/cli.ts`. -- Project scaffolding: `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, `src/paths.ts`, and `engine_configs/**`. -- Codex prompt and workflow surfaces: `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, and `templates/**`. -- Runtime/task execution: `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, and `src/verification.ts`. -- Validation: `src/validation.ts` plus the package metadata and smoke checks it verifies. -- Architecture flow guides: `docs/architecture/flows/**` explain important runtime scenarios, branch logic, and failure paths by linking back to bounded truth docs. - -## Boundaries - -Project scaffolding writes generated project files but does not execute Codex. Codex prompt/workflow modules render instructions but do not persist run state. Runtime/task modules execute or persist Codex runs but consume the prompt surfaces instead of defining role contracts. CLI/validation modules expose and verify the public package contract. - -## Current Structure - -- `src/cli.ts` owns the public CLI command wiring. -- `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, and `src/paths.ts` own project scaffolding and generated project surfaces. -- `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, and `src/templates.ts` own Codex role, prompt, workflow, and template surfaces. -- `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, and `src/verification.ts` own Codex execution, task persistence, runtime checks, and verification processes. -- `src/validation.ts` owns repository and generated-project validation checks. -- `engine_configs/**` and `templates/**` are package runtime assets. -- `tests/**` mirrors those behavior boundaries with node:test coverage. -- `docs/architecture/flows/**` contains Markdown runtime views for project initialization, role runs, workflow prompt rendering, and validation/repository-truth workflows. - -## Product Decisions - -- Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file. -- Decision (2026-05-30): Use Markdown Architecture Flow Guides as arc42-style runtime views for detailed branching/walkthrough documentation; keep bounded Truthmark truth docs as the canonical behavior reference layer. - -## Rationale - -The package has a small source tree but multiple independent behavioral contracts. Truthmark routing keeps project scaffolding, prompt surfaces, runtime/task execution, and CLI/validation contracts separate so future syncs can update bounded docs instead of a catch-all repository overview. - -## Maintenance Notes - -Update this architecture note when source modules move across the behavior boundaries in `docs/truthmark/routes/areas/repository.md`. Update `docs/architecture/flows/**` when an architecturally relevant runtime scenario, branch, or failure path changes. diff --git a/docs/development-rules.md b/docs/development-rules.md deleted file mode 100644 index 069090b..0000000 --- a/docs/development-rules.md +++ /dev/null @@ -1,18 +0,0 @@ -# Development Rules - -This repository is TypeScript/Node only. - -Use `.js` specifiers for all relative TypeScript imports because the package uses NodeNext. - -Run validation before claiming parity: - -```bash -npm run typecheck -npm run build -npm test -npm run validate -``` - -Keep generated game project surfaces in the repository root. - -The current build invokes Codex by default through `run `. Use `--dry-run` or `--print-prompt` for inspection-only paths. Explicit local task orchestration is now inside the product boundary, but runtime claims require implementation and validation. The build still intentionally excludes planner commands, telemetry, changed-file tracking, hosted/background orchestration, unbounded parallelism, and ownership enforcement. diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index aa188c5..0000000 --- a/docs/development.md +++ /dev/null @@ -1,67 +0,0 @@ -# Development - -This document is for contributors working on Codex Game Studio itself. - -For user-facing command usage, see the [User Guide](user-guide.md). For template/project layout, see [Project Anatomy](project-anatomy.md). - -## Setup - -```sh -npm install -npm run build -./codex-game-studio --help -``` - -This project uses ESM TypeScript with `module` and `moduleResolution` set to `NodeNext`. Relative TypeScript imports include emitted `.js` specifiers. - -## Standard checks - -Run these before publishing a change: - -```sh -npm run typecheck -npm test -npm run validate -truthmark check --json -truthmark index --json -``` - -Use focused tests while developing, then run the full gate before committing. - -## Source-checkout wrapper - -The checked-in `./codex-game-studio` wrapper runs the built TypeScript entrypoint at `dist/cli.js`. - -Generated bundled CLI artifacts are not committed. If the wrapper cannot find `dist/cli.js`, run: - -```sh -npm install -npm run build -``` - -## Package-bin smoke - -After build, link, install, or package smoke testing: - -```sh -npm exec codex-game-studio -- --help -npm exec codex-game-studio -- templates show gdd -``` - -The package bin is `codex-game-studio` and points to `dist/cli.js`. - -## Documentation maintenance - -- Keep the root README concise and human-facing. -- Move command detail to [User Guide](user-guide.md). -- Move role detail to [Studio Roles](studio-roles.md). -- Move generated-file detail to [Project Anatomy](project-anatomy.md). -- Move contributor/build detail to this file. -- When the root README changes materially, update localized README storefronts under `docs/readmes/` in the same change or document the intentional deferral. -- Behavior-bearing changes should keep README claims, validation behavior, tests, and Truthmark-backed docs in sync. - -## Truthmark-aware changes - -This repository contains Truthmark-managed docs. Functional behavior changes should update the nearest canonical product or engineering truth doc and then run Truthmark validation. - -Docs-only navigation changes do not require a Truth Sync workflow, but they should still pass `truthmark check` and `truthmark index` before publication. diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 3d3906e..0000000 --- a/docs/examples.md +++ /dev/null @@ -1,5 +0,0 @@ -# Examples - -Examples now live in the scenario index at [docs/examples/README.md](examples/README.md). - -The new index follows the CCGS pattern: each example explains the scenario, complexity, command sequence, and what the reader should learn. diff --git a/docs/examples/README.md b/docs/examples/README.md index 37265c5..6444906 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -18,11 +18,11 @@ Create a local project, inspect its state, and run validation. ```sh ./codex-game-studio init --name "Rogue Core" --engine godot --mode prototype --non-interactive \ --competitor "Mini Metro" --competitor "Dorfromantik" -./codex-game-studio status --project projects/rogue-core -./codex-game-studio validate --project projects/rogue-core +./codex-game-studio status +./codex-game-studio validate ``` -**Learn:** project creation, generated project location, status output, and project validation. +**Learn:** project state, status output, and project validation. --- @@ -34,10 +34,10 @@ Create a local project, inspect its state, and run validation. Inspect the prompt first, then run the producer role through Codex. ```sh -./codex-game-studio run producer --project projects/rogue-core \ +./codex-game-studio run producer \ "Create the initial market overview." --print-prompt -./codex-game-studio run producer --project projects/rogue-core \ +./codex-game-studio run producer \ "Create the initial market overview." ``` @@ -53,12 +53,12 @@ Inspect the prompt first, then run the producer role through Codex. Render workflow prompts without launching Codex. ```sh -./codex-game-studio market --project projects/rogue-core --dry-run -./codex-game-studio analytics --project projects/rogue-core --dry-run -./codex-game-studio handoff --project projects/rogue-core --dry-run -./codex-game-studio design-spec --project projects/rogue-core --dry-run -./codex-game-studio feel-review --project projects/rogue-core --dry-run -./codex-game-studio ui-review --project projects/rogue-core --dry-run +./codex-game-studio market --dry-run +./codex-game-studio analytics --dry-run +./codex-game-studio handoff --dry-run +./codex-game-studio design-spec --dry-run +./codex-game-studio feel-review --dry-run +./codex-game-studio ui-review --dry-run ``` **Learn:** workflow shortcuts are preparation surfaces; they do not launch Codex or create run records. @@ -73,8 +73,8 @@ Render workflow prompts without launching Codex. Turn a supported workflow recipe into explicit project tasks. ```sh -./codex-game-studio workflow create-tasks vertical-slice --project projects/rogue-core -./codex-game-studio validate --project projects/rogue-core +./codex-game-studio workflow create-tasks vertical-slice +./codex-game-studio validate ``` **Learn:** task recipes, `.codex/tasks.json`, and validation after task-state changes. @@ -98,5 +98,3 @@ List templates and inspect one before using it in a role prompt or design sessio ## More detail - [User Guide](../user-guide.md) for command-by-command usage. -- [Studio Roles](../studio-roles.md) for choosing a role. -- [Project Anatomy](../project-anatomy.md) for generated files. diff --git a/docs/known-upstream-differences.md b/docs/known-upstream-differences.md deleted file mode 100644 index aee68cc..0000000 --- a/docs/known-upstream-differences.md +++ /dev/null @@ -1,29 +0,0 @@ -# Known Upstream Differences - -This TypeScript/Node port preserves upstream user-facing outcomes while intentionally avoiding legacy implementation details that caused fragile behavior. - -Legacy engine-system checks only partially passed while still reporting success. This port uses hard-failing validation, where any failed check exits nonzero. - -Legacy folder-structure checks and project-file path expectations differed from the desired `source/project-/` contract. This port uses `source/project-/` for Godot, Unity, and Unreal. - -Legacy Unreal naming used multiple labels. This port normalizes `Unreal`, `Unreal Engine`, `unreal`, and `ue5` to canonical `unreal`, while keeping `Unreal Engine` as the display name. - -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. - -Clone-visible template repositories track `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, and `.agents/skills/*/SKILL.md` directly. `run ` assembles the current runtime prompt packet from tracked custom agents, project state, selected templates, and bounded context instead of materializing `.codex/prompts/.md` mirrors. - -Market and analytics are first-class renderable workflows owned by dedicated roles. Workflow prompts and normal role runs inline selected package template bodies instead of pointing Codex at project-relative template paths or loading every template. - -Studio orchestration is provided through Codex-native roles, file-backed task state, explicit `task orchestrate` execution, selected workflow task recipes, and bounded workflow surfaces, 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. Supported workflow recipes such as `vertical-slice`, `bugfix`, `ui-ux-review`, and `release-checklist` can explicitly create `.codex/tasks.json` task graphs before `task orchestrate` runs them. - -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 ` invokes `codex exec` by default against a bounded runtime prompt packet. `--dry-run` and `--print-prompt` are the non-executing inspection paths. `--allow-broad-context` performs bounded discovery of existing project artifacts rather than recursive ingestion, and `--fix` receives the same runtime role context and selected templates as the primary implementation prompt. - -Tracked template agents, workflows, and skills do not require generated-surface freshness metadata. Validation checks their structure and game-facing placement, while project-specific context metadata remains in `.codex/context-manifest.meta.json`. - -Future-only features still not implemented in this build include planner/`next`, telemetry, changed-file tracking, prompt-size metrics, hard output-ownership enforcement, hosted/background orchestration, unbounded parallelism, legacy `.gamestudio` compatibility, `CODEX.md`, and `project_orchestrator.md`. Explicit local task orchestration is implemented as foreground, bounded, file-backed CLI behavior. diff --git a/docs/migration-from-claude.md b/docs/migration-from-claude.md deleted file mode 100644 index 269bc73..0000000 --- a/docs/migration-from-claude.md +++ /dev/null @@ -1,26 +0,0 @@ -# Migration From Claude-Oriented Game Studio - -Use the canonical TypeScript CLI with direct Codex execution from a cloned template root: - -```bash -npm exec codex-game-studio -- init --name "My Game" --engine godot --mode prototype --non-interactive --competitor "Mini Metro" -npm exec codex-game-studio -- run producer --project . "Create the initial market overview." -``` - -For inspection-only runs, add `--dry-run` or `--print-prompt` to view the bounded Codex prompt packet and metadata path before execution. - -Role runs assemble runtime prompt packets from tracked custom agents, project state, selected templates, and bounded context. - -Workflow shortcuts still render prompts only. - -`--allow-broad-context` performs bounded discovery of existing project artifacts. - -Tracked template agents, workflows, and skills are reviewed through Git instead of generated freshness metadata. - -Intentional differences: no interactive menu, no `startover`, no exact `template_info.md`, no eager competitor reports during init, no generated `project_orchestrator.md`, no `CODEX.md`, no legacy `.gamestudio` compatibility, and no unsupported upstream underscore role IDs. - -Supported aliases such as `new` for `init` remain available. - -Future-only features are not implemented: `codex-game-studio next`, telemetry, changed-file tracking, hosted/background orchestration, unbounded parallelism, and ownership enforcement. - -Explicit local task orchestration is implemented through reviewable `.codex/**` task, lock, and run state. diff --git a/docs/plans/2026-06-25-task-orchestration-bounded-parallelism-ccgs-adaptation.md b/docs/plans/2026-06-25-task-orchestration-bounded-parallelism-ccgs-adaptation.md deleted file mode 100644 index 7bd2930..0000000 --- a/docs/plans/2026-06-25-task-orchestration-bounded-parallelism-ccgs-adaptation.md +++ /dev/null @@ -1,1083 +0,0 @@ -# Task Orchestration, Bounded Parallelism, and Curated CCGS Adaptation Implementation Plan - -> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task. - -**Goal:** Add explicit local task orchestration with bounded parallel execution, and adapt the useful Claude Code Game Studios (CCGS) role/skill/workflow surface into Codex Game Studio without importing Claude-specific machinery or unbounded orchestration. - -**Architecture:** Keep Codex Game Studio local-first and Codex-native. Extend the existing `.codex/tasks.json`, `.codex/runs/**`, role packages, workflow registry, template registry, approvals, and validation systems. Orchestration is a foreground CLI command that plans, locks, executes, verifies, reviews, and records bounded task runs; it is not a daemon, hosted scheduler, hidden planner, or generic workflow DAG engine. - -**Tech Stack:** TypeScript ESM on Node 24, Commander CLI, node:test plus standalone expect, existing Codex runtime, existing project validation, Truthmark-backed docs. - ---- - -## 1. Product Boundary Decisions - -### 1.1 In scope - -- `codex-game-studio task orchestrate --project ` as the primary orchestration entrypoint. -- Bounded task DAG execution using explicit task dependencies. -- Bounded parallelism with an explicit `--max-concurrency` flag and a hard product cap. -- Local reviewable state in `.codex/tasks.json`, `.codex/locks/**`, and `.codex/runs//**`. -- Existing Codex role execution, approval gates, sandbox/write policy, verification, review, and fix-pass behavior reused per task. -- Curated CCGS adaptation as Codex-native roles, workflow recipes, templates, and optional project-local `custom-*` overlays. - -### 1.2 Out of scope - -- Hosted orchestration, accounts, remote queues, remote artifact storage, billing, or server-side scheduling. -- Background autonomous loops or daemon workers. -- Unbounded parallelism. -- Hidden planner/`next` command behavior. -- Generated `CODEX.md`, `.gamestudio/**`, `project_orchestrator.md`, or Claude hook/skill runtime compatibility. -- General workflow DAGs unrelated to game-studio tasks. - -### 1.3 Closed decisions - -1. **Default concurrency is serial.** `task orchestrate` defaults to `--max-concurrency 1`. -2. **Parallelism is opt-in and capped.** The first implementation allows `--max-concurrency 1..3`; values above `3` fail with a clear error. -3. **Parallel mutating tasks require declared write sets.** A task without declared `writeFiles` uses a conservative project-wide write lock when file edits are allowed. -4. **No separate scheduler process.** Orchestration runs in the current foreground CLI process and exits when the bounded run completes. -5. **No hidden task generation.** CCGS workflow adaptation may create task graphs only through explicit commands that show the planned tasks before writing or executing them. -6. **CCGS adaptation is curated, not mirrored.** Use CCGS as source material, but translate into existing Codex-native IDs, bounded context selection, and Codex Game Studio's role/workflow/template contracts. - -### 1.4 Review follow-up constraints - -- Orchestration planning/preflight must be side-effect-free. Do not call any API path that writes `.codex/runs/**`, `.codex/tasks.json`, or `.codex/locks/**` before approvals, dependency validation, and lock planning pass. -- The orchestrator must serialize all `.codex/tasks.json` writes during parallel execution. -- In the first implementation, `writeFiles` are normalized literal project-relative file paths only. Reject globs, directories, `.git`, escaping paths, and control characters. -- Approval matching for mutating task runs is based on `writeFiles`; `files` are read/context inputs only. - ---- - -## 2. Current Repository Baseline - -Relevant existing files: - -- `src/tasks.ts` owns `.codex/tasks.json`, task creation, task status updates, and `task run` integration. -- `src/runner.ts` owns role-run preparation, prompt cache metadata, Codex execution, verification, review, and fix passes. -- `src/codex-runtime.ts` owns Codex CLI command construction and availability checks. -- `src/cli.ts` exposes `run`, `task create`, `task run`, workflow shortcuts, approvals, templates, and validation. -- `src/roles.ts` contains built-in Codex role packages. -- `src/workflows.ts` contains prompt-only workflow registry entries. -- `src/templates.ts` contains package template registry and selection. -- `src/customization.ts` validates extend-only project-local `custom-*` roles, workflows, and templates. -- `src/validation.ts` validates repo/package/project behavior and future-only surfaces. -- `tests/tasks.test.ts`, `tests/runner.test.ts`, `tests/codex-runtime.test.ts`, `tests/functionality-gap-pass.test.ts`, `tests/customization.test.ts`, and `tests/validation.test.ts` are the main test anchors. - -Current constraints to preserve: - -- Every relative TypeScript import must use emitted `.js` specifiers. -- `run ` remains the primary single-role Codex execution path. -- `--dry-run` and `--print-prompt` remain inspection-only. -- Workflow shortcuts remain render-only unless explicitly converted into task-graph creation commands. -- Unknown legacy CCGS underscore role IDs remain invalid public role IDs. - ---- - -## 3. Task Data Model - -### 3.1 Upgrade `.codex/tasks.json` to schema version 2 - -Modify `src/tasks.ts` types and parser so schema v1 stores still read and normalize into schema v2 in memory. - -```ts -export type StudioTaskStatus = "ready" | "running" | "blocked" | "done" | "cancelled" | "skipped"; - -export type StudioTaskDependency = { - taskId: string; - requiredStatus: "done"; -}; - -export type StudioTaskRunPolicy = { - maxFixPasses?: number; - review?: boolean; - constrainedSandbox?: boolean; -}; - -export type StudioTask = { - id: string; - title: string; - role: StudioRoleId; - status: StudioTaskStatus; - files: string[]; - writeFiles: string[]; - dependencies: StudioTaskDependency[]; - workflowId?: string; - groupId?: string; - priority: number; - verification?: VerificationCommand; - runPolicy?: StudioTaskRunPolicy; - notes: string[]; - createdAt: string; - updatedAt: string; - lastRunId?: string; -}; - -export type TaskStore = { - schemaVersion: 2; - tasks: StudioTask[]; -}; -``` - -### 3.2 Migration behavior - -- Existing schema v1 task fields map as: - - `files` remains selected read/context files. - - `writeFiles` becomes `[]`. - - `dependencies` becomes `[]`. - - `priority` becomes `0`. - - `createdAt` and `updatedAt` become a deterministic migration timestamp only when the store is rewritten. -- `readTaskStore()` may return normalized v2 data without rewriting. -- `writeTaskStore()` always writes schema v2. -- Missing `writeFiles` means parallel mutating execution falls back to project-wide lock, not unsafe optimism. - -### 3.3 Task creation CLI additions - -Extend `task create`: - -```bash -codex-game-studio task create --project projects/demo \ - --role gameplay-programmer \ - --file documentation/design/gdd.md \ - --write-file source/project-demo/player.gd \ - --depends-on task-001 \ - --workflow vertical-slice \ - --priority 10 \ - --verify-command npm --verify-arg run --verify-arg validate --verify-arg -- --verify-arg --project --verify-arg projects/demo \ - "Implement player jump" -``` - -Rules: - -- `--file` is context/read input. -- `--write-file` is declared mutation scope and lock input. -- `--depends-on` may repeat. -- `--workflow` records source workflow ID but does not imply hidden execution. -- Unknown dependencies fail before writing. -- Cycles are checked when orchestrating, not when creating one task, so users can assemble a graph incrementally. - ---- - -## 4. Orchestration State and Locking - -### 4.1 Run directory - -Each orchestration invocation creates: - -```text -.codex/runs// - orchestration.json - events.jsonl - tasks// - prompt.md - metadata.json - output.txt -``` - -`orchestration.json` records: - -```ts -type OrchestrationRunMetadata = { - schemaVersion: 1; - product: "codex-game-studio"; - runId: string; - startedAt: string; - finishedAt?: string; - projectRoot: string; - maxConcurrency: number; - requestedTaskIds: string[]; - selectedTaskIds: string[]; - dryRun: boolean; - review: boolean; - fix: boolean; - status: "planned" | "running" | "done" | "blocked" | "cancelled"; - summary: Array<{ taskId: string; status: StudioTaskStatus; runPath?: string; reason?: string }>; -}; -``` - -`events.jsonl` appends deterministic event records: - -- `orchestration.started` -- `task.eligible` -- `task.locked` -- `task.started` -- `task.finished` -- `task.blocked` -- `task.skipped` -- `task.unlocked` -- `orchestration.finished` - -### 4.2 Lock files - -Use a reviewable lock directory: - -```text -.codex/locks/ - .json -``` - -Lock file shape: - -```ts -type TaskLock = { - schemaVersion: 1; - lockKey: string; - taskId: string; - orchestrationRunId: string; - role: string; - writeFile: string; - acquiredAt: string; - expiresAt: string; - releasedAt?: string; -}; -``` - -Implementation details: - -- Derive `lockKey` from canonical project-relative write path or conservative key `__project_write__`. -- Acquire with exclusive create (`fs.openSync(path, "wx")`) so concurrent CLI processes cannot silently share a write lock. -- Release by rewriting the lock with `releasedAt` and then removing it. -- If a stale lock exists past `expiresAt`, fail closed first; add a later explicit `task lock cleanup` command only after the basic orchestrator is stable. -- Read-only tasks do not acquire write locks. -- Mutating tasks with no `writeFiles` acquire `__project_write__`, making them serial with all other mutating tasks. - -### 4.3 Conflict rules - -Two tasks may run together only when all are true: - -- Both have all dependencies satisfied. -- Neither is `running`, `done`, `cancelled`, or `skipped`. -- Their required approval/write-policy checks pass. -- Their lock sets do not conflict. -- The current running count is below `maxConcurrency`. -- They do not require the conservative project-wide write lock at the same time as any other mutating task. - ---- - -## 5. Orchestration Engine - -Create `src/orchestrator.ts`. - -Core API: - -```ts -export type OrchestrateOptions = { - project: string; - taskIds?: string[]; - workflowId?: string; - maxConcurrency?: number; - dryRun?: boolean; - review?: boolean; - fix?: boolean; - maxFixPasses?: number; - approvedByUser?: boolean; - constrainedSandbox?: boolean; - approvalScope?: string[]; - codexBin?: string; -}; - -export type OrchestrationResult = { - runId: string; - status: "planned" | "done" | "blocked"; - selectedTaskIds: string[]; - startedTaskIds: string[]; - blockedTaskIds: string[]; - skippedTaskIds: string[]; - output: string; -}; - -export async function orchestrateTasks(options: OrchestrateOptions): Promise; -``` - -Algorithm: - -1. Resolve project root. -2. Read and normalize task store. -3. Select tasks: - - explicit `taskIds` if provided; - - else tasks matching `workflowId` if provided; - - else all `ready` tasks. -4. Validate graph: - - no unknown dependencies; - - no cycles among selected tasks and their required dependencies; - - no selected task depends on a `blocked`, `cancelled`, or `skipped` task unless user explicitly selected only downstream dry-run inspection; - - no concurrency above hard cap. -5. Prepare every selected task using `prepareRun()` before starting any non-dry run. -6. In strict/guided modes, fail closed before starting any task if required approvals are missing. -7. For dry-run, print planned waves, lock sets, selected context, Codex command previews, and approval diagnostics; write no task/runs/locks state. -8. For execution: - - mark orchestrator run as `running`; - - compute ready wave; - - acquire locks for up to `maxConcurrency` tasks; - - start Codex lifecycle for each task; - - stream or buffer task output into per-task run output; - - update task status to `done` or `blocked`; - - release locks; - - recompute ready wave until no runnable tasks remain. -9. Tasks whose dependencies cannot be satisfied because another task blocked become `skipped` with a note naming the blocker. -10. Final orchestrator status is `done` only if every selected task is `done`; otherwise `blocked`. - ---- - -## 6. Codex Runtime Changes for Parallelism - -Current `executeRunLifecycle()` is `async` but calls synchronous Codex spawning. Parallel orchestration needs real asynchronous execution. - -Modify `src/codex-runtime.ts` to add: - -```ts -export async function executeCodexCommand( - command: { command: string; args: string[] }, - input: string, - options: { cwd: string; timeoutMs?: number } -): Promise; -``` - -Modify `src/runner.ts`: - -- Keep sync helpers only for tests or deprecate them internally. -- Update implementation, review, and fix pass execution to use the async function. -- Preserve existing output formatting and final status semantics. -- Add timeout support later only if a concrete test requires it; do not add global scheduler timeouts in the first pass. - -Testing requirement: - -- Use fake Codex binaries that sleep and write deterministic output to prove `--max-concurrency 2` completes faster than serial without relying on real Codex. -- Do not call hosted LLMs in tests. - ---- - -## 7. CLI Design - -### 7.1 New command - -```bash -codex-game-studio task orchestrate --project [task-id...] -``` - -Options: - -```text ---workflow select ready tasks from one workflow/group ---max-concurrency default 1, allowed 1..3 ---dry-run show plan, locks, approvals, and commands; no mutation ---review run per-task review pass ---fix run bounded per-task fix passes ---max-fix-passes reuse existing task run behavior ---approval-scope repeatable diagnostic/approval scope ---approved-by-user guided-studio local override ---constrained-sandbox use workspace-write instead of full-access sandbox -``` - -Examples: - -```bash -codex-game-studio task orchestrate --project projects/demo --dry-run -codex-game-studio task orchestrate --project projects/demo --max-concurrency 2 --review --fix -codex-game-studio task orchestrate --project projects/demo --workflow vertical-slice --max-concurrency 2 -codex-game-studio task orchestrate --project projects/demo task-001 task-002 task-003 --dry-run -``` - -### 7.2 Help surface guardrails - -- Help may mention `orchestrate` and `--max-concurrency`. -- Help must not expose `next`, `telemetry`, hosted orchestration, daemon mode, or unbounded parallel options. -- Existing future-surface guard tests should be updated from "no parallel at all" to "no unbounded/hosted/background parallelism". - ---- - -## 8. Workflow-to-Task Recipes - -Prompt-only workflows should remain prompt-only. Add explicit recipe commands for workflows that should produce task graphs. - -Create `src/workflow-recipes.ts`. - -```ts -export type WorkflowTaskRecipe = { - workflowId: WorkflowId | string; - title: string; - tasks: Array<{ - title: string; - role: StudioRoleId; - files: string[]; - writeFiles: string[]; - dependencies: string[]; // local recipe keys, not final task IDs - verification?: VerificationCommand; - }>; -}; -``` - -Add CLI: - -```bash -codex-game-studio workflow create-tasks --project --dry-run -codex-game-studio workflow create-tasks --project -``` - -Rules: - -- `--dry-run` prints proposed tasks and dependency graph, writes nothing. -- Non-dry writes tasks to `.codex/tasks.json` with `workflowId` and `groupId`. -- Recipe-local dependency keys are resolved to real task IDs after creation. -- The command does not run Codex. Users run `task orchestrate` explicitly. - -Initial recipe set: - -1. `vertical-slice` - - producer plans slice - - game-designer writes acceptance/spec detail - - gameplay-programmer implements core loop - - technical-artist or sound-designer handles asset/audio hook if declared - - qa-playtester reviews and verifies -2. `bugfix` - - qa-playtester reproduces/records expected behavior - - gameplay-programmer fixes - - qa-playtester verifies -3. `ui-ux-review` - - ui-ux-designer reviews flow - - ui-programmer implements bounded UI fix if needed - - accessibility-specialist reviews accessibility gaps -4. `release-checklist` - - qa-playtester validates evidence - - performance-analyst checks performance risks - - security-engineer checks release/security risks - - release-manager synthesizes ship/no-ship - -Do not create all CCGS team workflows in the first pass. Add recipes only when their lock/dependency/write-set behavior is obvious and testable. - ---- - -## 9. Curated CCGS Adaptation Design - -### 9.1 Source inventory - -Reference source inspected for this design: - -- `Donchitos/Claude-Code-Game-Studios` -- `.claude/agents`: 49 Claude agents -- `.claude/skills`: 73 Claude skills -- `.claude/hooks`: Claude hook runtime files -- `.claude/rules`: Claude-specific rule files - -Important translation principle: CCGS is a rich reference library, not an implementation contract. Codex Game Studio adapts outcomes into local Codex-native primitives. - -### 9.2 Role adaptation policy - -Role decisions use four categories: - -| Decision | Meaning | -|---|---| -| `built-in-existing` | Already represented by an Codex Game Studio role package. Improve prompt depth only if tests show a gap. | -| `built-in-add` | Add a new canonical hyphenated Codex Game Studio role. | -| `specialty-context` | Do not add a role; adapt as engine/module/plugin reference context selected by task keywords. | -| `custom-pack-example` | Keep as project-local `custom-*` example or docs, not built-in product surface. | - -### 9.3 CCGS role mapping - -| CCGS role | Codex Game Studio target | Decision | -|---|---|---| -| `producer` | `producer` | built-in-existing | -| `creative-director` | `creative-director` | built-in-existing | -| `game-designer` | `game-designer` / `senior-game-designer` | built-in-existing | -| `systems-designer` | `systems-designer` | built-in-existing | -| `economy-designer` | `economy-designer` | built-in-existing | -| `level-designer` | `level-designer` | built-in-existing | -| `world-builder` | `world-builder` | built-in-existing | -| `writer` | `writer` | built-in-existing | -| `gameplay-programmer` | `gameplay-programmer` | built-in-existing | -| `ai-programmer` | `ai-programmer` | built-in-existing | -| `network-programmer` | `network-programmer` | built-in-existing | -| `ui-programmer` | `ui-programmer` | built-in-existing | -| `engine-programmer` | `engine-programmer` | built-in-existing | -| `tools-programmer` | `tools-programmer` | built-in-existing | -| `technical-director` | `technical-director` | built-in-existing | -| `devops-engineer` | `devops-engineer` | built-in-existing | -| `security-engineer` | `security-engineer` | built-in-existing | -| `performance-analyst` | `performance-analyst` | built-in-existing | -| `technical-artist` | `technical-artist` | built-in-existing | -| `audio-director` | `audio-director` | built-in-existing | -| `sound-designer` | `sound-designer` | built-in-existing | -| `accessibility-specialist` | `accessibility-specialist` | built-in-existing | -| `localization-lead` | `localization-lead` | built-in-existing | -| `live-ops-designer` | `live-ops-designer` | built-in-existing | -| `community-manager` | `community-manager` | built-in-existing | -| `release-manager` | `release-manager` | built-in-existing | -| `godot-specialist` | active-engine `godot-specialist` | built-in-existing | -| `unity-specialist` | active-engine `unity-specialist` | built-in-existing | -| `unreal-specialist` | active-engine `unreal-specialist` | built-in-existing | -| `analytics-engineer` | `data-scientist` plus analytics templates | built-in-existing, prompt-depth improvement | -| `art-director` | `senior-game-artist` plus art-direction workflow | built-in-existing, maybe rename not needed | -| `narrative-director` | `narrative-designer` plus `world-builder` | built-in-existing, prompt-depth improvement | -| `ux-designer` | `ui-ux-designer` | built-in-existing | -| `qa-lead` | add `qa-lead` only if QA planning/release strategy needs a separate owner | built-in-add candidate | -| `qa-tester` | `qa-playtester`; maybe add `qa-tester` later for test-case execution | defer unless tests show split needed | -| `lead-programmer` | add `lead-programmer` if technical-director is too broad for code review/refactor ownership | built-in-add candidate | -| `prototyper` | keep as `prototype` workflow/recipe, not role | specialty workflow | -| Godot sub-specialists | engine references selected by task keywords | specialty-context | -| Unity sub-specialists | engine references selected by task keywords | specialty-context | -| Unreal sub-specialists | engine references selected by task keywords | specialty-context | - -First role additions, if any, should be only: - -1. `lead-programmer` — code architecture, code review, refactor strategy, programming work assignment. -2. `qa-lead` — QA strategy, bug triage, test plan ownership, release quality gates. - -Do not add every engine sub-specialist as a first-class role. Use active-engine references and templates instead. - -### 9.4 CCGS skill adaptation policy - -Do not generate `.claude/skills` or implement a Claude skill runtime. Convert CCGS skills into one of these Codex Game Studio surfaces: - -| CCGS skill kind | Codex Game Studio surface | -|---|---| -| Planning or review skill | built-in workflow prompt or workflow task recipe | -| Structured output document | package template | -| Team coordination skill | explicit workflow task recipe with dependencies | -| Maintenance skill for Claude skills/hooks | out of scope or project-local example only | -| Hook/rule-driven behavior | explicit CLI option, validation check, or docs; never hidden hook behavior | - -### 9.5 Initial CCGS skill decisions - -Already covered or mostly covered: - -- `architecture-decision` → existing workflow/template. -- `architecture-review` → existing workflow/template. -- `brainstorm` → existing workflow. -- `bug-triage` / `bug-report` → `bugfix` workflow plus future bug-report template if needed. -- `create-epics` → existing workflow. -- `create-stories` → existing workflow. -- `hotfix` → existing workflow. -- `onboard` / `start` → existing workflow aliases. -- `perf-profile` → existing workflow. -- `playtest-report` → `playtest` workflow/template. -- `prototype` → existing workflow, future task recipe. -- `qa-plan` → existing workflow/template. -- `regression-suite` → existing workflow. -- `release-checklist` / `launch-checklist` → existing release workflow; add alias if needed. -- `security-audit` → existing workflow. -- `sprint-plan` → existing workflow. -- `sprint-status` → existing workflow. -- `story-readiness` → existing workflow. -- `story-done` → existing workflow. -- `ux-review` → `ui-ux-review` workflow. -- `vertical-slice` → existing workflow, future task recipe. - -High-value additions: - -- `gate-check` → new workflow for stage readiness verdict. -- `project-stage-detect` → new read-only workflow for repo state audit and recommended next action. -- `scope-check` → new workflow/template for scope risk and feature cut decisions. -- `estimate` → new producer workflow/template for rough schedule/complexity estimates. -- `tech-debt` → new lead-programmer or technical-director workflow/template. -- `smoke-check` → new QA/release workflow with minimal validation checklist. -- `test-evidence-review` → new QA workflow for evidence completeness. -- `asset-audit` → new technical-artist/senior-game-artist workflow/template. -- `asset-spec` → new art-direction template/workflow. -- `balance-check` → new systems/economy design workflow. -- `map-systems` → new systems-design workflow/template. -- `reverse-document` → new documentation workflow that derives missing docs from implementation. -- `propagate-design-change` → new architecture/design impact workflow using traceability docs. -- `create-control-manifest` → new technical-director workflow/template after ADRs are accepted. -- `ux-design` → new UI/UX design workflow distinct from review. - -Team skills become recipes, not prompt-only aliases: - -- `team-combat` → game-designer → gameplay-programmer/ai-programmer/sound-designer → qa-playtester. -- `team-ui` → ui-ux-designer → ui-programmer → accessibility-specialist → qa-playtester. -- `team-audio` → audio-director → sound-designer/technical-artist → gameplay-programmer integration → qa-playtester. -- `team-qa` → qa-lead/qa-playtester split, if `qa-lead` is added. -- `team-release` → release-manager with QA/perf/security dependencies. -- `team-polish` → producer/creative-director triage plus focused UI/audio/perf/QA tasks. -- `team-live-ops` → live-ops-designer/community-manager/data-scientist/release-manager sequence. -- `team-narrative` → narrative-designer/world-builder/writer/localization-lead sequence. -- `team-level` → level-designer/gameplay-programmer/technical-artist/qa-playtester sequence. - -Defer or keep out of product: - -- `adopt`, `help`, `skill-improve`, `skill-test`, `test-helpers` as Claude-skill maintenance concepts. -- Claude hook/rule-only mechanics unless translated into explicit validation or CLI flags. -- Any CCGS skill that depends on persistent Claude memory or hidden hooks. - ---- - -## 10. Implementation Tasks - -### Task 1: Add task schema v2 tests - -**Objective:** Lock the task-store migration contract before changing implementation. - -**Files:** - -- Modify: `tests/tasks.test.ts` -- Later modify: `src/tasks.ts` - -**Steps:** - -1. Add a test that writes a schema v1 `.codex/tasks.json` and expects `readTaskStore()` to return schema v2 with empty dependencies/writeFiles and valid timestamps. -2. Add a test that `writeTaskStore()` writes `schemaVersion: 2`. -3. Run: - ```bash - npm test -- tests/tasks.test.ts -t "task store" - ``` -4. Expected before implementation: failure because schema v2 is not implemented. - -### Task 2: Implement task schema v2 normalization - -**Objective:** Support old task stores while writing the new shape. - -**Files:** - -- Modify: `src/tasks.ts` -- Modify: `tests/tasks.test.ts` - -**Steps:** - -1. Update task types. -2. Add normalization helpers. -3. Preserve v1 parsing behavior. -4. Ensure status validation accepts `cancelled` and `skipped`. -5. Run: - ```bash - npm test -- tests/tasks.test.ts - ``` -6. Expected: pass. - -### Task 3: Extend task creation CLI - -**Objective:** Let users declare dependencies, context files, write files, workflow/group metadata, and priority. - -**Files:** - -- Modify: `src/tasks.ts` -- Modify: `src/cli.ts` -- Modify: `tests/tasks.test.ts` -- Modify: `tests/cli-prompt-surface.test.ts` if CLI help assertions need updates. - -**Steps:** - -1. Add `createTask()` input fields. -2. Add `--file`, `--write-file`, `--depends-on`, `--workflow`, and `--priority` options. -3. Validate project-safe relative paths using the same path rules used by customizations/context selection. -4. Test duplicate dependencies and unknown dependency IDs. -5. Run: - ```bash - npm test -- tests/tasks.test.ts tests/cli-prompt-surface.test.ts - ``` - -### Task 4: Add asynchronous Codex execution - -**Objective:** Make parallel execution possible without blocking the event loop on `spawnSync`. - -**Files:** - -- Modify: `src/codex-runtime.ts` -- Modify: `src/runner.ts` -- Modify: `tests/codex-runtime.test.ts` -- Modify: `tests/runner.test.ts` - -**Steps:** - -1. Add `executeCodexCommand()` using `node:child_process` `spawn`. -2. Preserve `CodexExecutionResult` shape. -3. Update implementation/review/fix passes to await async execution. -4. Keep current output formatting unchanged. -5. Run: - ```bash - npm test -- tests/codex-runtime.test.ts tests/runner.test.ts - ``` - -### Task 5: Add lock acquisition tests - -**Objective:** Define lock behavior before implementation. - -**Files:** - -- Create: `tests/orchestrator-locks.test.ts` -- Create later: `src/orchestrator-locks.ts` - -**Steps:** - -1. Test two tasks with disjoint `writeFiles` can both acquire locks. -2. Test overlapping write file lock acquisition fails for the second task. -3. Test missing `writeFiles` uses `__project_write__`. -4. Test released locks are removed or marked released according to final implementation choice. -5. Run: - ```bash - npm test -- tests/orchestrator-locks.test.ts - ``` -6. Expected before implementation: failure because module does not exist. - -### Task 6: Implement lock store - -**Objective:** Provide atomic file-backed locks for bounded parallel execution. - -**Files:** - -- Create: `src/orchestrator-locks.ts` -- Modify: `tests/orchestrator-locks.test.ts` - -**Steps:** - -1. Implement canonical lock key generation. -2. Implement exclusive lock creation with `fs.openSync(path, "wx")`. -3. Implement release cleanup. -4. Implement stale lock diagnostics but do not auto-clean stale locks yet. -5. Run: - ```bash - npm test -- tests/orchestrator-locks.test.ts - ``` - -### Task 7: Add orchestration graph tests - -**Objective:** Define dependency selection, cycle detection, and skipped-task behavior. - -**Files:** - -- Create: `tests/orchestrator.test.ts` -- Create later: `src/orchestrator.ts` - -**Steps:** - -1. Test ready tasks with dependencies are ordered in waves. -2. Test cycle detection fails before mutation. -3. Test a blocked dependency causes downstream tasks to become `skipped`. -4. Test `--max-concurrency 4` fails because first cap is 3. -5. Run: - ```bash - npm test -- tests/orchestrator.test.ts - ``` - -### Task 8: Implement dry-run orchestration planning - -**Objective:** Add `orchestrateTasks()` dry-run mode without mutation. - -**Files:** - -- Create: `src/orchestrator.ts` -- Modify: `src/tasks.ts` if helper exports are needed. -- Modify: `tests/orchestrator.test.ts` - -**Steps:** - -1. Implement task selection. -2. Implement dependency graph validation. -3. Implement wave planning. -4. Reuse `prepareRun()` to show eligibility and commands. -5. Assert dry-run writes no `.codex/runs/**`, locks, or task status changes. -6. Run: - ```bash - npm test -- tests/orchestrator.test.ts - ``` - -### Task 9: Implement serial orchestration execution - -**Objective:** Make `maxConcurrency: 1` execute selected tasks safely. - -**Files:** - -- Modify: `src/orchestrator.ts` -- Modify: `tests/orchestrator.test.ts` - -**Steps:** - -1. Create orchestration run directory. -2. Write `orchestration.json` and append `events.jsonl`. -3. Execute tasks one at a time using `executeTaskRun()` or a shared lower-level lifecycle helper. -4. Update task status and `lastRunId`. -5. Mark downstream tasks skipped when blockers occur. -6. Run: - ```bash - npm test -- tests/orchestrator.test.ts tests/tasks.test.ts - ``` - -### Task 10: Implement bounded parallel orchestration - -**Objective:** Execute non-conflicting ready tasks concurrently up to the cap. - -**Files:** - -- Modify: `src/orchestrator.ts` -- Modify: `tests/orchestrator.test.ts` - -**Steps:** - -1. Start ready tasks in batches constrained by lock availability and `maxConcurrency`. -2. Await task promises with failure isolation. -3. Release locks in `finally` blocks. -4. Add fake Codex sleep tests proving concurrency without hosted calls. -5. Run: - ```bash - npm test -- tests/orchestrator.test.ts - ``` - -### Task 11: Add CLI command - -**Objective:** Expose orchestration through `codex-game-studio task orchestrate`. - -**Files:** - -- Modify: `src/cli.ts` -- Modify: `tests/cli-prompt-surface.test.ts` -- Modify: `tests/functionality-gap-pass.test.ts` - -**Steps:** - -1. Add command and options. -2. Print dry-run wave plan and execution summary. -3. Set nonzero exit code when orchestrator status is blocked. -4. Update future-surface tests so `parallel` is not blanket-forbidden, but hosted/unbounded/background surfaces remain forbidden. -5. Run: - ```bash - npm test -- tests/cli-prompt-surface.test.ts tests/functionality-gap-pass.test.ts - ``` - -### Task 12: Add workflow recipe tests - -**Objective:** Define explicit workflow-to-task creation without hidden execution. - -**Files:** - -- Create: `tests/workflow-recipes.test.ts` -- Create later: `src/workflow-recipes.ts` - -**Steps:** - -1. Test `vertical-slice` dry-run prints proposed tasks and dependencies without writing. -2. Test non-dry creates tasks with `workflowId`, `groupId`, dependencies, files, and writeFiles. -3. Test recipe creation does not call Codex. -4. Run: - ```bash - npm test -- tests/workflow-recipes.test.ts - ``` - -### Task 13: Implement initial workflow recipes - -**Objective:** Add task graph creation for a small high-value workflow set. - -**Files:** - -- Create: `src/workflow-recipes.ts` -- Modify: `src/cli.ts` -- Modify: `tests/workflow-recipes.test.ts` - -**Steps:** - -1. Implement `vertical-slice`, `bugfix`, `ui-ux-review`, and `release-checklist` recipes. -2. Add `workflow create-tasks ` CLI. -3. Keep workflow shortcut commands render-only. -4. Run: - ```bash - npm test -- tests/workflow-recipes.test.ts tests/functionality-gap-pass.test.ts - ``` - -### Task 14: Add CCGS adaptation registry tests - -**Objective:** Make the curated CCGS adaptation decisions executable and reviewable. - -**Files:** - -- Create: `tests/ccgs-adaptation.test.ts` -- Create later: `src/ccgs-adaptation.ts` - -**Steps:** - -1. Test every listed CCGS role has an adaptation decision. -2. Test no legacy underscore role IDs become built-in role IDs. -3. Test high-value skill additions are categorized as workflow/template/recipe/deferred. -4. Run: - ```bash - npm test -- tests/ccgs-adaptation.test.ts - ``` - -### Task 15: Implement CCGS adaptation registry - -**Objective:** Record curated adaptation decisions in code, not only docs. - -**Files:** - -- Create: `src/ccgs-adaptation.ts` -- Modify: `tests/ccgs-adaptation.test.ts` -- Modify: `src/validation.ts` if validation should report registry coverage. - -**Steps:** - -1. Add role decision table. -2. Add skill decision table. -3. Add helper functions for reporting unmapped/high-value candidates. -4. Optionally add validation diagnostics for registry consistency. -5. Run: - ```bash - npm test -- tests/ccgs-adaptation.test.ts tests/validation.test.ts - ``` - -### Task 16: Add first curated roles only if justified - -**Objective:** Add no more than `lead-programmer` and `qa-lead` as built-ins if tests show current roles cannot own those workflows cleanly. - -**Files:** - -- Modify: `src/roles.ts` -- Modify: `src/config.ts` -- Modify: `src/agents.ts` if generated prompt coverage changes. -- Modify: `tests/roles.test.ts` -- Modify: `tests/functionality-gap-pass.test.ts` - -**Steps:** - -1. Add failing tests for role package presence and active-role selection. -2. Add role packages with concise responsibilities, expected outputs, quality gates, and handoff templates. -3. Do not add engine sub-specialist roles. -4. Run: - ```bash - npm test -- tests/roles.test.ts tests/functionality-gap-pass.test.ts - ``` - -### Task 17: Add high-value CCGS-derived workflows/templates - -**Objective:** Fill real workflow gaps without importing all CCGS skills. - -**Files:** - -- Modify: `src/workflows.ts` -- Modify: `src/templates.ts` -- Add package templates under `templates/` only where structured output is needed. -- Modify: `tests/functionality-gap-pass.test.ts` -- Modify: `tests/agents-templates.test.ts` - -**Steps:** - -1. Add only the first batch: `gate-check`, `project-stage-detect`, `scope-check`, `estimate`, `tech-debt`, `smoke-check`, `test-evidence-review`, `asset-audit`, `balance-check`, `map-systems`, `ux-design`. -2. Add templates only for workflows that need durable structured artifacts. -3. Keep template selection bounded. -4. Run: - ```bash - npm test -- tests/functionality-gap-pass.test.ts tests/agents-templates.test.ts - ``` - -### Task 18: Update validation and future-surface guards - -**Objective:** Validate orchestration without allowing hosted/unbounded drift. - -**Files:** - -- Modify: `src/validation.ts` -- Modify: `src/behavioral-evaluation.ts` -- Modify: `tests/validation.test.ts` -- Modify: `tests/behavioral-evaluation.test.ts` - -**Steps:** - -1. Add validation checks for task schema v2, orchestration command availability, lock directory safety, and recipe registry consistency. -2. Update forbidden drift phrases to forbid hosted/background/unbounded orchestration, not explicit local bounded orchestration. -3. Add absence checks for daemon/hosted/unbounded CLI/help/config surfaces. -4. Run: - ```bash - npm test -- tests/validation.test.ts tests/behavioral-evaluation.test.ts - ``` - -### Task 19: Update docs and generated truth surfaces - -**Objective:** Keep product docs, architecture docs, and Truthmark docs in sync with implemented behavior. - -**Files:** - -- Modify: `README.md` -- Modify: `docs/development-rules.md` -- Modify: `docs/known-upstream-differences.md` -- Modify: `docs/migration-from-claude.md` -- Modify: `docs/workflow-validation.md` -- Modify: `docs/architecture/flows/role-run-lifecycle.md` -- Create: `docs/architecture/flows/task-orchestration.md` -- Modify relevant `docs/truthmark/**` docs after code behavior lands. - -**Steps:** - -1. Document `task orchestrate` and `workflow create-tasks` examples. -2. Document bounded parallelism cap and lock behavior. -3. Document CCGS adaptation as curated translation, not parity-by-copying. -4. Run Truthmark refresh only if `truthmark check` reports stale surfaces: - ```bash - npx truthmark check - npx truthmark index - ``` - -### Task 20: Full verification - -**Objective:** Prove the feature works and product boundaries remain intact. - -Run: - -```bash -npm run typecheck -npm run build -npm test -npm run validate -npx truthmark check -npx truthmark index -git diff --check -``` - -Expected: - -- Typecheck passes. -- Build passes. -- Tests pass. -- Validation reports bounded local orchestration as implemented. -- Validation still reports hosted/background/unbounded orchestration surfaces absent. -- Truthmark check/index pass. -- Diff has no whitespace errors. - ---- - -## 11. Acceptance Criteria - -Implementation is complete when all are true: - -1. Existing `task run` behavior remains compatible. -2. Schema v1 task stores still read correctly. -3. `task create` supports dependencies, read files, write files, workflow IDs, and priority. -4. `task orchestrate --dry-run` writes no files and prints task waves, lock sets, approvals, and commands. -5. `task orchestrate` serial mode runs ready tasks in dependency order. -6. `task orchestrate --max-concurrency 2` runs non-conflicting tasks concurrently in tests. -7. Conflicting write sets do not run concurrently. -8. Tasks without write sets do not run concurrently with mutating tasks. -9. Strict-studio approvals are checked before any non-dry orchestration side effects. -10. Blocked tasks cause dependent tasks to become `skipped` with readable notes. -11. Orchestration run metadata and task outputs are persisted under `.codex/runs/**`. -12. Locks are released on success, failure, and thrown exceptions. -13. Help/validation exposes no hosted, daemon, background loop, or unbounded parallelism surface. -14. CCGS roles and skills have a curated adaptation registry with explicit keep/add/defer decisions. -15. Initial high-value CCGS additions improve OGS coverage without copying Claude-specific hooks/rules/skills wholesale. -16. Docs and Truthmark-backed behavior claims match code. - ---- - -## 12. Explicit Non-Goals for This Implementation - -- No hosted service. -- No remote worker. -- No background daemon. -- No auto-cleaning stale locks in the first pass. -- No generalized arbitrary DAG language. -- No unbounded `--max-concurrency 0` or `--max-concurrency unlimited` behavior. -- No automatic task generation from free-form LLM output without showing/writing reviewable task specs first. -- No import of `.claude/**` files into generated projects. -- No engine sub-specialist role explosion until selected-context references prove insufficient. - ---- - -## 13. Recommended Implementation Order - -1. Task schema v2. -2. CLI task creation enhancements. -3. Async Codex runtime. -4. Lock store. -5. Dry-run orchestration planner. -6. Serial orchestration execution. -7. Bounded parallel execution. -8. CLI command. -9. Workflow recipe creation. -10. CCGS adaptation registry. -11. First curated role/workflow/template additions. -12. Validation and docs. - -This order keeps each step testable and avoids shipping a broad orchestration surface before locking, approvals, and failure behavior are explicit. diff --git a/docs/plans/2026-06-29-scoped-standards-rule-packs.md b/docs/plans/2026-06-29-scoped-standards-rule-packs.md deleted file mode 100644 index acf596f..0000000 --- a/docs/plans/2026-06-29-scoped-standards-rule-packs.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -status: superseded -doc_type: design-index -last_reviewed: 2026-06-29 -superseded_by: - - 2026-06-29-codex-native-agent-skill-surfaces.md ---- - -# Scoped Standards Rule Packs Design - -This draft is superseded by [Codex-Native Agent and Skill Surfaces Implementation Design](2026-06-29-codex-native-agent-skill-surfaces.md). - -Reason: follow-up review of the online Codex documentation showed this draft used the wrong native structure for generated agents and rules. - -Corrected decisions now live in the replacement design: - -- Codex custom agents are `.codex/agents/*.toml`, not `.codex/agents/*.md`. -- Codex repository skills are `.agents/skills//SKILL.md`. -- `AGENTS.md` is the automatic project instruction surface. -- Codex `.codex/rules/*.rules` files are sandbox command permission rules, not coding standards. -- Coding standards should be generated as skills and selected prompt guidance, not Codex permission rules. -- Project hooks are official Codex surfaces but require trust review; they are not part of the first implementation slice. diff --git a/docs/project-anatomy.md b/docs/project-anatomy.md deleted file mode 100644 index 48cc583..0000000 --- a/docs/project-anatomy.md +++ /dev/null @@ -1,114 +0,0 @@ -# Project Anatomy - -Codex Game Studio projects are repository-root template workspaces. The clone-visible template files are the contract between humans, Codex, validation, and later role runs. - -## Template repository tree - -A typical cloned project starts like this: - -```text -open-gamestudio/ - AGENTS.md - .agents/ - skills/ - cgs-start/SKILL.md - cgs-prototype/SKILL.md - ... - .codex/ - agents/ - producer.toml - market-analyst.toml - ... - workflows/ - market-analysis.md - prototype.md - ... - documentation/ - source/ -``` - -After `codex-game-studio init`, project state and runtime files are added beside those tracked template surfaces: - -```text -.codex/ - studio.json - context-manifest.json - context-manifest.meta.json - runs/ - tasks.json - locks/ - studio/ - config.json -source/ - project-/ -``` - -Exact starter files vary by engine, mode, and workflow state. - -## What humans edit - -Humans normally edit: - -- `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, and `.agents/skills/*/SKILL.md` when changing the template behavior; -- `documentation/` game-design and production docs; -- source files under `source/project-/`; -- explicit task descriptions in `.codex/tasks.json` when using task workflows; -- project customization in `.codex/studio/config.json`. - -Do not treat agent, workflow, or skill bodies as generated output. They are tracked template files, and ordinary Git review is the freshness mechanism. - -## What agents read - -Codex roles read bounded context selected for the role and task. A role run may include: - -- project `AGENTS.md`; -- `.codex/studio.json`; -- selected tracked custom agents under `.codex/agents/*.toml`; -- selected tracked workflow files under `.codex/workflows/*.md`; -- relevant repository skills under `.agents/skills/*/SKILL.md`; -- relevant `documentation/` files; -- relevant templates; -- engine context and engine reference snippets. - -Codex Game Studio does not recursively dump the whole project into every prompt. - -## Important files - -| Path | Purpose | -| --- | --- | -| `AGENTS.md` | Tracked game-template instructions for Codex. | -| `.codex/agents/*.toml` | Tracked Codex custom-agent definitions for studio roles. | -| `.codex/workflows/*.md` | Tracked workflow prompts and recipes. | -| `.agents/skills/*/SKILL.md` | Tracked repository skills adapted from the CCGS workflow surface. | -| `.codex/studio.json` | Project metadata, role roster, workflow IDs, workflow state, and validation contract. | -| `.codex/context-manifest.json` | Selected context-file manifest used to keep prompt context explicit. | -| `.codex/runs/` | Prompt packets and run metadata produced by role execution. | -| `.codex/tasks.json` | File-backed task state for explicit task workflows. | -| `.codex/locks/` | Transient locks for bounded local orchestration. | -| `.codex/studio/config.json` | Optional project-local customization overlay. | -| `documentation/` | Starter game-design and production documents. | -| `source/project-/` | Engine project location contract. | - -## Repository assets that feed runtime behavior - -| Repository path | Purpose | -| --- | --- | -| `src/` | TypeScript CLI implementation. | -| `src/roles.ts` | Role-package registry used for CLI help, validation, and runtime prompt packets. | -| `templates/` | Design, production, art, QA, release, analytics, and engine templates. | -| `engine_configs/` | Engine overlays for Godot, Unity, and Unreal. | -| `engine_reference/` | Curated engine reference packs selected by role and task. | -| `docs/` | Setup, migration, validation, architecture, and truth docs. | -| `tests/` | node:test coverage for projects, templates, validation, runner behavior, engine behavior, and orchestration. | - -## Validation-sensitive surfaces - -Validation checks clone-ready template surfaces before project state exists and also validates initialized project state after `init`. - -Template validation checks tracked agents, workflows, and skills for expected structure and for absence of maintenance-only surfaces. Project validation checks starter docs, engine source markers, context manifests, read-only command behavior, forbidden legacy artifacts, and future-only CLI drift. - -See [Workflow Validation](workflow-validation.md) for the full validation contract. - -## Codex prompt model routing - -Prompt surfaces declare exact Codex model policy in tracked template files. Complex design, architecture, production, and release-gate surfaces use `gpt-5.5`; moderate implementation, QA, docs, bugfix, and bounded workflow surfaces use `gpt-5.4`; simple help, status, classification, checklist, and lookup surfaces use `gpt-5.4-mini`. Runtime dry-runs and run metadata expose the selected model and reasoning effort, and Codex execution receives the exact selected model instead of a generic tier name. diff --git a/docs/prompt-quality.md b/docs/prompt-quality.md deleted file mode 100644 index 7382900..0000000 --- a/docs/prompt-quality.md +++ /dev/null @@ -1,352 +0,0 @@ -# Prompt Quality Standard - -## Purpose - -This document is the source of truth for gradually improving Codex Game Studio agents, skills, and workflows. - -Prompt quality means the tracked template surfaces help Codex choose the right owner, load the right context, take bounded action, verify the result, and hand off cleanly. - -Prompt quality does not mean making every prompt longer. Improvements should remove generic boilerplate, add task-specific judgment, and prove better behavior with evaluations. - -## Scope - -This standard applies to tracked prompt surfaces: - -- `.codex/agents/*.toml` -- `.codex/workflows/*.md` -- `.agents/skills/*/SKILL.md` -- supporting references, templates, examples, and evaluation fixtures linked from those surfaces - -Project initialization must not synthesize or overwrite these prompt bodies. Improvements land as reviewable repository changes. - -## Reference basis - -This standard is derived from current major-provider guidance: - -- Anthropic, [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): concise skills, discovery descriptions, progressive disclosure, degrees of freedom, workflows, and evaluation-first iteration. -- Anthropic, [Building effective agents](https://www.anthropic.com/research/building-effective-agents): distinction between predictable workflows and flexible agents, and the recommendation to use the simplest effective agentic system. -- OpenAI, [GPT-4.1 Prompting Guide](https://cookbook.openai.com/examples/gpt4-1_prompting_guide): persistence, tool-use reminders, planning, prompt organization, examples, and conflict reduction. -- OpenAI, [Agents SDK documentation](https://openai.github.io/openai-agents-python/): production agent primitives such as tools, handoffs, guardrails, sessions, tracing, and structured tool behavior. -- Google, [Gemini prompting strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies): clear instructions, few-shot examples, agentic workflow dimensions, persistence, recovery, and risk assessment. -- Microsoft, [Azure OpenAI prompt engineering concepts](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/prompt-engineering): instruction clarity, examples, output priming, and structured prompt components. - -## Quality principles - -### 1. Evaluation before expansion - -Write or update evaluations before adding broad prompt text. - -A prompt improvement should begin with an observed failure or risk: - -- wrong agent or skill selected; -- context loaded too broadly or too narrowly; -- task crosses role ownership without handoff; -- output omits required evidence; -- blocker, warning, and assumption are mixed together; -- model guesses instead of using files or tools; -- workflow advances without entry criteria, exit criteria, or verification. - -Then add the smallest prompt change that fixes the failure. - -### 2. Progressive disclosure - -Main prompt files should be concise entry points. - -Use supporting files when details are useful but not always needed: - -```text -.agents/skills/cgs-prototype/ - SKILL.md - references/examples.md - references/checklist.md - templates/handoff.md -``` - -`SKILL.md` should select and steer the task. Examples, long checklists, style guides, and domain details should live in linked files. - -### 3. Strong discovery metadata - -Descriptions are selection metadata, not labels. - -Weak: - -```toml -description = "Game development Game Designer agent for game-designer tasks in this template repository." -``` - -Better: - -```toml -description = "Owns implementable gameplay mechanics, tuning variables, edge cases, player-facing acceptance criteria, and feature-scope decisions for bounded game-design tasks." -``` - -Every description should answer: - -- What task does this surface own? -- When should Codex select it? -- What does it not own? -- Which keywords should retrieval and selection see? - -### 4. Match freedom to risk - -Use the least restrictive prompt that still protects quality. - -| Freedom | Use for | Prompt shape | -| --- | --- | --- | -| High | Brainstorming, market exploration, early creative ideation | Goals, heuristics, examples, broad output options | -| Medium | Prototype plans, design specs, sprint planning, bounded implementation | Ordered phases, decision gates, output contract | -| Low | Release gates, migrations, security, localization handoff, irreversible edits | Exact checklist, entry criteria, stop conditions, required evidence | - -High-risk workflows need explicit steps and stop conditions. Open-ended roles need judgment boundaries and good examples. - -### 5. Separate agents, skills, and workflows - -Each surface type has a different job. - -| Surface | Owns | Should emphasize | -| --- | --- | --- | -| Agent | Role ownership and judgment | Domain responsibility, allowed tools, handoff rules, stop conditions | -| Skill | How to perform a task well | Trigger, procedure, examples, verification, failure modes | -| Workflow | Repeatable process sequence | Entry criteria, ordered steps, gates, required artifacts, exit criteria | - -Do not make workflows read like role prompts. Do not make skills repeat generic agent policy. - -### 6. Examples over repeated rules - -Use short examples where behavior is ambiguous. - -Good examples include: - -- release blocker vs warning; -- bug reproduction and regression evidence; -- prototype hypothesis and success signal; -- design acceptance criteria; -- localization context notes; -- QA test matrix; -- handoff with changed files and verification. - -Examples should demonstrate the output shape and edge-case judgment. They should not be long tutorials. - -### 7. Tool use and grounding are explicit - -Prompt surfaces should tell Codex when to inspect files, run commands, or stop. - -A good surface distinguishes: - -- required context; -- optional context; -- prohibited broad scans; -- allowed write targets; -- verification commands or manual inspection alternatives; -- conditions that require asking, stopping, or handing off. - -Avoid instructions that encourage guessing. If file contents, project state, or verification evidence matter, the surface should require tool-backed grounding. - -### 8. Guardrails and handoffs are first-class - -Every nontrivial workflow should define: - -- input guardrails: required project state, target files, approvals, write scope; -- tool guardrails: allowed file areas, commands, asset classes, and forbidden operations; -- output guardrails: required sections and evidence; -- handoff rules: target role, handoff payload, and when no handoff is needed; -- traceability: files inspected, commands run, decisions made, blockers left. - -This mirrors production-agent guidance around tools, guardrails, handoffs, and tracing. - -### 9. Prefer consistency without copy-paste sameness - -A common skeleton is useful. Repeated generic content is not. - -If many surfaces share the same paragraph, move the shared rule to `AGENTS.md`, a common reference, or validation logic. Use the surface body for domain-specific judgment. - -Bad repeated text: - -```md -Inspect relevant files. Make the smallest change. Verify. Report evidence. -``` - -Better skill-specific text: - -```md -Before editing a bugfix, reproduce or identify the failing behavior. If reproduction is impossible, state the missing input and stop before speculative edits. After editing, run the narrowest regression test or explain the manual inspection substitute. -``` - -## Required structure by surface - -### Agent TOML - -Agent files should include: - -- strong `description` as discovery metadata; -- exact `model` and `model_reasoning_effort`; -- primary skills; -- allowed tool categories; -- invocation guidance; -- stop conditions; -- role-specific responsibilities; -- inputs to inspect; -- expected outputs; -- quality gates; -- handoff contract. - -Agent prompts should not include long workflow procedures. Link or rely on workflows and skills for process details. - -### Skill `SKILL.md` - -Skills should include: - -- concise frontmatter description with trigger and ownership; -- argument hint; -- model policy; -- primary agent; -- tool policy; -- source reference when adapted from upstream; -- purpose; -- when to use and when not to use; -- compact procedure; -- decision gates; -- output contract; -- verification contract; -- failure modes; -- links to examples or templates when needed. - -Keep the main file short enough that loading it is cheap. Move large examples and checklists into references. - -### Workflow Markdown - -Workflows should include: - -- model policy; -- primary agent; -- linked skills; -- phase and risk; -- argument hint; -- entry criteria; -- required inputs; -- ordered steps; -- decision gates; -- required artifacts; -- verification; -- stop conditions; -- exit criteria; -- handoff contract. - -Workflows are process contracts. They should be more procedural and less persona-like than agents. - -## Evaluation requirements - -Prompt-quality work should include at least one of these evidence types: - -- unit test for metadata, validation, or routing; -- deterministic behavioral evaluation scenario; -- prompt audit output showing improved specificity or reduced duplication; -- manual eval transcript recorded under a reference file; -- before/after failure example with expected behavior. - -Representative eval scenarios should cover: - -- correct surface selection; -- missing required context; -- role handoff boundary; -- output contract adherence; -- verification evidence; -- blocker vs risk separation; -- no generated prompt-body side effects; -- model routing by task complexity. - -## Improvement checklist - -Use this checklist for gradual upgrades. - -```text -Prompt quality pass: -- [ ] Identify the observed failure, weak behavior, or duplicated boilerplate. -- [ ] Add or update an evaluation that would catch it. -- [ ] Strengthen discovery metadata before expanding body text. -- [ ] Remove repeated generic prose or move it to shared guidance. -- [ ] Add task-specific examples where behavior is ambiguous. -- [ ] Add entry criteria, exit criteria, stop conditions, and handoff payloads where needed. -- [ ] Verify exact model routing and reasoning effort. -- [ ] Run validation and prompt-surface tests. -- [ ] Update docs or Truthmark routing if behavior-bearing surfaces changed. -``` - -## Anti-patterns validation should catch - -Validation should flag or warn on: - -- descriptions that only restate the file or role name; -- descriptions without selection triggers; -- missing `model` or non-exact model names; -- missing argument hints for user-invocable skills or workflows; -- high-risk workflows without entry criteria, stop conditions, and verification; -- skill bodies over a size threshold without references; -- near-duplicate sections across many skills; -- examples absent from ambiguous high-impact surfaces; -- workflow files that read like agent personas; -- agent files that contain long process checklists better owned by workflows; -- output contracts without evidence requirements; -- handoff language without a next-owner rule. - -## Prioritized roadmap - -### P0: Discovery metadata rewrite (implemented) - -Discovery metadata now has deterministic validation and audit coverage. Maintain descriptions and argument hints before expanding prompt bodies. - -Targets: - -- `.codex/agents/*.toml` -- `.agents/skills/*/SKILL.md` -- `.codex/workflows/*.md` - -### P1: Behavioral eval suite - -Add evals for: - -- prototype with ambiguous scope; -- bugfix with missing reproduction; -- release checklist with blocker classification; -- vertical slice with task decomposition; -- design-system update with acceptance criteria; -- localization with context and string-freeze constraints. - -### P1: Progressive disclosure split - -For the most important skills, move examples, templates, and long checklists into supporting files. - -Start with: - -- `cgs-prototype` -- `cgs-bugfix` -- `cgs-release-checklist` -- `cgs-vertical-slice` -- `cgs-design-system` -- `cgs-localize` - -### P2: Workflow contract normalization - -Normalize workflow bodies around entry criteria, ordered steps, decision gates, required artifacts, verification, exit criteria, and handoff. - -### P2: Deduplication audit - -Compute prompt similarity and flag repeated generic sections. Keep shared policy in one place; reserve prompt bodies for task-specific judgment. - -### P3: Model-specific quality checks - -Test that simple surfaces work with `gpt-5.4-mini`, moderate surfaces with `gpt-5.4`, and complex surfaces with `gpt-5.5`. - -Lower-capability or cheaper routes need more explicit compact instruction. Higher-capability routes should avoid over-explaining. - -## Definition of done - -A prompt-quality change is done when: - -- the changed surface has a clear owner and selection trigger; -- the main prompt body is concise and not mostly boilerplate; -- task-specific examples or references exist where ambiguity is common; -- entry, exit, stop, verification, and handoff rules are explicit where risk warrants them; -- at least one test, audit, or evaluation proves the improvement; -- repository validation passes; -- this document remains consistent with the implemented standard. diff --git a/docs/readmes/README.ja.md b/docs/readmes/README.ja.md index bb382fc..8a6fe52 100644 --- a/docs/readmes/README.ja.md +++ b/docs/readmes/README.ja.md @@ -63,10 +63,8 @@ Codex Game Studio は、その構造をローカルなプロジェクト成果 | 目的 | ドキュメント | | --- | --- | | インストール、コマンド、ワークフロー、検証 | [User Guide](../user-guide.md) | -| ロールカタログ | [Studio Roles](../studio-roles.md) | -| 生成プロジェクト構造 | [Project Anatomy](../project-anatomy.md) | -| 利用例 | [Examples](../examples/README.md) | -| ドキュメント全体の地図 | [Docs Index](../README.md) | +| 利用シナリオ | [Examples](../examples/README.md) | +| ドキュメント全体 | [Docs Index](../README.md) | ## プロジェクト状態 diff --git a/docs/readmes/README.ko.md b/docs/readmes/README.ko.md index 9dd1529..7dd92a6 100644 --- a/docs/readmes/README.ko.md +++ b/docs/readmes/README.ko.md @@ -63,9 +63,7 @@ Codex Game Studio는 이 구조를 Codex가 읽고 사람이 리뷰할 수 있 | 필요 | 문서 | | --- | --- | | 설치, 명령, 워크플로, 검증 | [User Guide](../user-guide.md) | -| 역할 카탈로그 | [Studio Roles](../studio-roles.md) | -| 생성 프로젝트 구조 | [Project Anatomy](../project-anatomy.md) | -| 사용 예시 | [Examples](../examples/README.md) | +| 사용 시나리오 | [Examples](../examples/README.md) | | 전체 문서 지도 | [Docs Index](../README.md) | ## 프로젝트 상태 diff --git a/docs/readmes/README.zh.md b/docs/readmes/README.zh.md index 797b2fb..1bda550 100644 --- a/docs/readmes/README.zh.md +++ b/docs/readmes/README.zh.md @@ -63,8 +63,6 @@ Codex Game Studio 把这些结构变成本地项目文件，让 Codex 能读取 | 需要 | 文档 | | --- | --- | | 安装、命令、工作流和验证 | [User Guide](../user-guide.md) | -| 角色目录 | [Studio Roles](../studio-roles.md) | -| 生成项目结构 | [Project Anatomy](../project-anatomy.md) | | 使用场景 | [Examples](../examples/README.md) | | 完整文档地图 | [Docs Index](../README.md) | diff --git a/docs/setup.md b/docs/setup.md deleted file mode 100644 index a1c2e53..0000000 --- a/docs/setup.md +++ /dev/null @@ -1,39 +0,0 @@ -# Setup - -This is the short setup reference. For full command usage, see the [User Guide](user-guide.md). - -## Use from source checkout - -Clone the repository, install dependencies, build TypeScript output, and then run the checked-in CLI wrapper. Generated bundled CLI artifacts are not committed. - -```bash -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 --competitor "Mini Metro" --engine-version "4.4.1" -./codex-game-studio templates list -./codex-game-studio validate --project projects/my-game -``` - -## Contributor development - -Contributor workflow lives in [Development](development.md). - -```bash -npm install -npm run typecheck -npm run build -npm test -npm run validate -``` - -## Package install smoke - -After build/link/install, the package bin is available: - -```bash -npm exec codex-game-studio -- --help -npm exec codex-game-studio -- templates show gdd -``` diff --git a/docs/studio-roles.md b/docs/studio-roles.md deleted file mode 100644 index c8246b6..0000000 --- a/docs/studio-roles.md +++ /dev/null @@ -1,88 +0,0 @@ -# Studio Roles - -Codex Game Studio generates Codex-native role prompts for common game-studio disciplines. Role IDs are hyphenated and stable. Unsupported legacy underscore IDs are rejected instead of silently mapped. - -Use this catalog to choose a role before calling `run `. - -## Direction and production - -| Role | Use it for | -| --- | --- | -| `studio-orchestrator` | Coordinating a bounded slice across roles and handoffs. | -| `producer` | Milestones, production planning, priority calls, and market-facing summaries. | -| `release-manager` | Release readiness, ship checks, handoff quality, and launch coordination. | - -## Market and analytics - -| Role | Use it for | -| --- | --- | -| `market-analyst` | Competitor review, positioning, audience fit, store-page risks, and market summaries. | -| `data-scientist` | Telemetry plans, analytics questions, experiment design, and metrics interpretation. | - -## Design and writing - -| Role | Use it for | -| --- | --- | -| `creative-director` | Pillars, tone, experience direction, and cross-discipline creative alignment. | -| `senior-game-designer` | Systems direction, design cohesion, and high-level gameplay decisions. | -| `game-designer` | GDD sections, mechanics, rules, progression, and feature design. | -| `narrative-designer` | Narrative systems, quest structure, story-gameplay integration. | -| `writer` | Dialogue, prose, descriptions, and voice/tone work. | -| `world-builder` | Setting, factions, locations, lore, and world consistency. | -| `level-designer` | Level goals, encounter flow, spatial pacing, and layout specs. | -| `game-feel-designer` | Moment-to-moment feel, tuning targets, juice, responsiveness, and experiential checks. | -| `systems-designer` | Interlocking systems, economies, progression, constraints, and balancing models. | -| `economy-designer` | Currencies, sinks/sources, pricing, reward loops, and economy risks. | - -## Engineering - -| Role | Use it for | -| --- | --- | -| `gameplay-programmer` | Gameplay implementation plans, feature code, and mechanics integration. | -| `ai-programmer` | NPC behavior, decision logic, navigation, perception, and combat AI. | -| `network-programmer` | Multiplayer architecture, synchronization, rollback, replication, and latency concerns. | -| `ui-programmer` | UI implementation, menus, HUD, state binding, and input/accessibility integration. | -| `engine-programmer` | Engine-level systems, performance-sensitive architecture, and low-level integration. | -| `tools-programmer` | Editor tools, pipelines, scripts, importers, and production automation. | -| `technical-director` | Technical architecture, constraints, feasibility reviews, and cross-system decisions. | -| `devops-engineer` | Build, CI, release automation, packaging, and environment workflow. | -| `security-engineer` | Threat models, abuse cases, credential handling, and multiplayer/backend risks. | -| `performance-analyst` | Profiling plans, optimization hypotheses, budgets, and bottleneck analysis. | - -## Engine specialists - -| Role | Use it for | -| --- | --- | -| `godot-specialist` | Godot-specific architecture, APIs, project layout, and version-sensitive guidance. | -| `unity-specialist` | Unity-specific architecture, packages, scenes/prefabs, and C# guidance. | -| `unreal-specialist` | Unreal-specific architecture, modules, Blueprints/C++, plugins, and content workflow. | - -## Art, audio, and UX - -| Role | Use it for | -| --- | --- | -| `senior-game-artist` | Art direction, asset planning, style guides, and visual production constraints. | -| `technical-artist` | Shaders, pipelines, asset integration, VFX, optimization, and DCC-engine bridges. | -| `audio-director` | Audio direction, music/sound strategy, mix priorities, and implementation needs. | -| `sound-designer` | SFX concepts, interactive audio details, event naming, and feedback loops. | -| `ui-ux-designer` | UX flows, HUD/menu design, player journeys, wireframes, and usability review. | -| `accessibility-specialist` | Accessibility risks, input alternatives, readability, audio/visual cues, and inclusive design. | - -## QA, localization, and operations - -| Role | Use it for | -| --- | --- | -| `qa-playtester` | Test plans, playtest notes, bug-risk reviews, and acceptance criteria. | -| `localization-lead` | Localization planning, string risks, culturalization, and translation handoff. | -| `live-ops-designer` | Events, retention loops, progression cadence, and live-service content planning. | -| `community-manager` | Community-facing messaging, feedback triage, and communication plans. | - -## Choosing a role - -- Use `producer` when the question is priority, milestone, or scope. -- Use `creative-director` or `senior-game-designer` when the question changes the player promise. -- Use an engine specialist when the implementation depends on Godot, Unity, or Unreal details. -- Use `qa-playtester` or `release-manager` before trusting a feature as shippable. -- Use `studio-orchestrator` only for bounded cross-role slices; do not use it as a general autonomous manager. - -See the [User Guide](user-guide.md) for `run ` usage and inspection flags. diff --git a/docs/system-verification.md b/docs/system-verification.md deleted file mode 100644 index 07c7109..0000000 --- a/docs/system-verification.md +++ /dev/null @@ -1,27 +0,0 @@ -# System Verification - -Required verification: - -```bash -npm test -- tests/behavioral-evaluation.test.ts tests/customization.test.ts -npm run typecheck -npm run build -npm test -./codex-game-studio --help -./codex-game-studio validate -npm run validate -``` - -`npm run validate` includes the temporary packed-package install smoke for the published `codex-game-studio` bin. - -Engine smoke: - -```bash -./codex-game-studio init --name "Codex Godot Smoke" --engine godot --mode prototype --non-interactive -./codex-game-studio init --name "Codex Unity Smoke" --engine unity --mode design --non-interactive -./codex-game-studio init --name "Codex Unreal Smoke" --engine "Unreal Engine" --mode development --non-interactive -./codex-game-studio validate --project projects/codex-godot-smoke -./codex-game-studio validate --project projects/codex-unity-smoke -./codex-game-studio validate --project projects/codex-unreal-smoke -rm -rf projects/codex-godot-smoke projects/codex-unity-smoke projects/codex-unreal-smoke -``` diff --git a/docs/truthmark/engineering/codex/approval-stores.md b/docs/truthmark/engineering/codex/approval-stores.md deleted file mode 100644 index 1307b8b..0000000 --- a/docs/truthmark/engineering/codex/approval-stores.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -status: active -truth_kind: engineering-behavior -last_reviewed: 2026-06-26 ---- - -# Approval Stores - -## Purpose - -Approval stores preserve auditable authorization records for studio write-gating workflows. - -## Scope - -This leaf doc owns the approval-store data model and helper behavior. - -It covers canonical objective hashing, scope normalization, approval matching, expiry, and revocation. - -It also covers reads, writes, and mutations. It does not own approval CLI syntax, runner/task eligibility, project initialization, or validation diagnostics. - -## Current Implementation Behavior - -- Approval stores are JSON objects. -- Store objects use `schemaVersion: 1`, `product: "codex-game-studio"`, and a `records` array. -- Empty stores contain no approval records and are written deterministically. -- Approval stages are `question`, `options`, `decision`, `draft`, `approved`, `implemented`, `reviewed`, and `blocked`. -- Approval records include an ID, stage, role, and canonical objective SHA-256. -- Records may include normalized objective text, project stage, and studio mode. -- Records include approved glob scope and optional approved file scope. -- Records also include source, approver, approval timestamp, optional expiry, optional revocation, and baseline metadata. -- Approval timestamps use canonical UTC ISO strings in `YYYY-MM-DDTHH:mm:ss.sssZ` form. -- Canonical objective hashes include normalized role ID and normalized objective text. -- They also include normalized approved globs, normalized approved files, project stage, and studio mode. -- Approval matching authorizes only `approved` records. -- Matching requires role, objective hash, glob scope, file scope, project stage, and studio mode to match. -- Expired and revoked records never authorize a run. -- Runtime eligibility consumes approval matching for guided and strict studio mutation paths. -- Strict studio mutation requires a matching approval. -- Guided studio mutation accepts either a matching approval or an explicit local override. -- Revoked and expired approvals remain valid history records. -- Approval mismatch diagnostics report the expected objective hash. -- Diagnostics also list per-record non-authorization reasons. -- Reasons include role, objective, scope, file scope, project stage, studio mode, objective hash, revocation, expiry, and stage mismatches. -- Approval mutation helpers append deterministic `approval-###` records. -- New approval records use source `approval-command`, normalized scopes, approver metadata, baseline metadata, and canonical timestamps. -- Revocation sets `revokedAt` the first time a record is revoked. -- Repeated revocation preserves both the record and the original revocation timestamp. -- Approval grant baseline metadata stores git HEAD and a SHA-256 of the current git diff when git metadata is available. -- When git metadata is unavailable, grants store an explicit unavailable marker and deterministic fallback diff SHA. - -## Core Rules - -- Scope normalization rejects unsafe paths. -- Unsafe paths include absolute paths, parent traversal, control characters, secret-like path segments, and symlink escapes. -- Scope entries normalize Windows separators to POSIX-style separators. -- Scope entries are deduplicated and sorted for deterministic hashing and storage. -- Canonical serialization sorts object keys and omits `undefined` values before hashing. -- Broad approval scope detection treats `.`, `*`, `**`, and `**/*` as repository-wide scopes. -- Approval validation rejects malformed stores. -- Validation reports field-specific errors for invalid records, duplicate approval IDs, and project-root-aware scope failures. - -## Flows And States - -- Store creation creates an empty versioned store. -- Store creation also ensures the `.codex` parent directory exists and writes deterministic JSON to `.codex/approvals.json`. -- Store reads parse `.codex/approvals.json` and validate it against the project root. -- Store reads return a typed store only when validation passes. -- Match flow computes the canonical objective hash for the requested role, objective, scope, stage, and mode. -- Match flow scans approval records and checks stored scope, files, stage, and mode when present. -- Match flow ignores revoked, expired, and non-approved records. -- When no active record matches, match flow returns mismatch reasons. -- List-state flow marks a record as authorizing only when it is approved, unexpired, and not revoked. -- Revoked and expired records remain visible as non-authorizing history. - -## Contracts - -- `src/approvals.ts` exports approval-store helpers. -- Exported helpers cover hashing, scope normalization, matching, mismatch diagnostics, and validation. -- They also cover reads, writes, appends, revocation, broad-scope detection, and list-state classification. -- Approval source values are `draft-workflow`, `approval-command`, and `cli-override`. - -## Product Truth Links - -- docs/truthmark/product/codex-game-studio-cli.md - -## Engineering Decisions - -- Decision (2026-06-13): Keep approval storage independent from runner and task eligibility logic. -- Decision (2026-06-13): Let runtime execution consume approval matching as a simple authorization result. -- Decision (2026-06-13): Include project stage and studio mode in hashes and records when available. -- Decision (2026-06-13): Tie approval intent to both lifecycle stage and policy mode. -- Decision (2026-06-13): Approval grants always store baseline metadata. -- Decision (2026-06-13): Git-backed projects store git HEAD plus diff SHA. -- Decision (2026-06-13): Non-git projects store an explicit unavailable marker. - -## Rationale - -Approval storage stays separate from runtime execution so records remain deterministic and auditable. Runtime gates only need a matching result. - -Hashing normalized role, objective, scope, project stage, and studio mode prevents incidental text or ordering differences from changing authorization intent. - -## Non-Goals - -- This behavior does not define Codex sandbox selection. -- This behavior does not define runtime mutation flow. - -## Maintenance Notes - -- Update this doc when `src/approvals.ts` changes. -- Update this doc when `tests/approval-gates.test.ts` changes. -- Related generated-project claims live in the Project Scaffolding truth doc. -- Related validation claims live in the CLI And Validation Contracts truth doc. - -## Source References - -- ../../routes/areas/repository.md -- ../../../../src/approvals.ts -- ../../../../src/runner.ts -- ../../../../src/tasks.ts -- ../../../../tests/approval-gates.test.ts -- ../../../../tests/runner.test.ts diff --git a/docs/truthmark/engineering/codex/roles-and-workflows.md b/docs/truthmark/engineering/codex/roles-and-workflows.md deleted file mode 100644 index e0b32e8..0000000 --- a/docs/truthmark/engineering/codex/roles-and-workflows.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -status: active -truth_kind: engineering-behavior -last_reviewed: 2026-06-29 ---- - -# Codex Roles And Workflows - -## Purpose - -Codex roles and workflows turn the generic Codex CLI into a bounded game-studio prompt surface. - -They define role contracts, context boundaries, reusable templates, tracked custom agents, tracked workflows, and render-only workflow shortcuts. - -## Scope - -This leaf doc owns role IDs, role package metadata, Codex session prompt rendering, workflow registry entries, workflow template files, repository skills, and template registry behavior. - -It also owns engine-reference prompt selection and runtime prompt packet composition. - -It does not own process execution, task persistence, package installation, or project initialization side effects. - -It does not own init-time generation of agent, workflow, or skill instruction bodies. - -## Current Implementation Behavior - -- Studio role IDs are canonical hyphenated strings. -- Examples include `producer`, `gameplay-programmer`, `network-programmer`, `audio-director`, `accessibility-specialist`, `qa-playtester`, and `studio-orchestrator`. -- The roster covers audio, level, world, content, systems, and economy clusters. -- It also covers live ops, community, localization, accessibility, security, devops, performance, networking, AI, and UI programming clusters. -- Engine specialist role IDs are `godot-specialist`, `unity-specialist`, and `unreal-specialist`. -- The template repository tracks custom-agent files under `.codex/agents/*.toml`. -- Agent descriptions are selection metadata that state role ownership, trigger terms, output class, and handoff boundary. -- The template repository tracks workflow files under `.codex/workflows/*.md`. -- Workflow argument hints request workflow-specific objectives, targets, constraints, and verification or handoff evidence. -- The template repository tracks repository skills under `.agents/skills/*/SKILL.md`. -- Skill descriptions state use triggers, outcomes, verification evidence, changed/proposed files, and handoff boundaries. -- Each role package has a display name, system prompt, context strategy, responsibilities, expected inputs, and expected outputs. -- Role packages may also include an output schema, quality gates, collaboration notes, stop conditions, handoff wording, and review checklist. -- Shared role-contract guidance lives in reusable fragments. -- Fragments cover scope control, verification evidence, write-policy behavior, handoff discipline, and release readiness. -- Role packages select fragments instead of copying the same prose into every role. -- Runtime role prompt packets include role identity, phase, project root, objective, and engine context. -- Runtime role prompt packets include sandbox, write policy, file-edit permission, context files, expected outputs, verification command, review checklist, and completion-report instructions. -- Runtime role prompt packets include selected active-engine references, expected outputs, review checklist, and handoff guidance. -- Runtime role prompt packets are assembled in memory. -- Runtime role prompt packets are not mirrored to `.codex/prompts/**` during initialization. -- When a context contract exists, the prompt includes a `# Context Contract` section. -- The context contract lists selected context, omissions, blockers, project stage, studio mode, phase, write policy, sandbox, and file-edit permission. -- Workflow prompt rendering uses the same phase and studio-mode eligibility fields as role runs. -- Render-only plan, review, and ship workflows stay read-only. -- Eligible implement workflows render with matching write permissions. -- The workflow registry is a curated prompt-only catalog. -- It covers onboarding, discovery, design, architecture, implementation planning, QA, testing, release, hotfix, localization, accessibility, and team coordination. -- Built-in production workflows include vertical-slice, production-milestone, handoff, review, ship-check, release-checklist, and hotfix. -- Built-in discovery and design workflows include market-analysis, analytics-setup, design-spec, game-feel-tuning, art-direction, ui-ux-review, onboard, brainstorm, and prototype. -- Built-in planning workflows include architecture-decision, architecture-review, create-epics, create-stories, sprint-plan, sprint-status, story-readiness, and story-done. -- Built-in QA and operations workflows include playtest, bugfix, qa-plan, regression-suite, security-audit, perf-profile, and localization-plan. -- Selected workflows expose local CLI aliases for render-only shortcuts. -- Template selection is task-, workflow-, role-, and project-pack-sensitive. -- Built-in templates are read from package assets. -- Project-local templates are read from `.codex/studio/config.json` references. -- Only selected templates are embedded into workflow prompts and role-run prompts. -- Behavioral evaluation scenarios render representative prompts locally. -- Scenario checks inspect required obligations, output-contract fields, selected context categories, and required workflow templates. -- They also inspect forbidden templates, forbidden future-only drift, and prompt-size bounds. -- Behavioral evaluation does not use LLM judges, hosted evaluators, telemetry, or hidden memory. -- Workflow scenarios without a project root still append selected built-in workflow templates. -- Project-local customization packs may add `custom-*` role, workflow, and template IDs. -- Custom overlays are extend-only and cannot replace built-in IDs. -- Custom role prompts render visible role ID, context strategy, expected outputs, review checklist, write policy, sandbox, and selected templates. -- Custom role review prompts reuse the built-in QA review surface. -- Custom role fix prompts append the configured custom role prompt. -- Custom workflow prompts use the generic `workflow ` command. -- Custom workflow prompts require the declared workflow Markdown file to exist. -- Custom workflow prompts include that file as selected context and render its body as workflow instructions. -- Custom workflows may target either a built-in role or a project-local custom role. -- Built-in targets render through the standard Codex session prompt and role contract. -- Custom targets append the project-local custom role prompt. -- Tracked workflow files do not require generated-surface source-input or rendered-body hash metadata. -- Tracked repository skills do not require generated-surface source-input or rendered-body hash metadata. - -## Core Rules - -- Unknown role errors point users toward Codex-native hyphenated role IDs. -- Prompt rendering includes role identity, project/session metadata, and a bounded role contract. -- Prompt rendering includes sandbox and write-policy context when available. -- Templates with required Markdown sections must have non-empty required sections. -- Every built-in template records description and role/workflow use hints. -- The project config template must parse as JSON. -- Workflow shortcuts render prompts only. -- `workflow create-tasks` is a separate explicit recipe path that writes file-backed tasks for supported workflows without launching Codex. -- Workflow shortcuts do not imply hidden planner, telemetry, ownership, hosted orchestration, background loops, or unbounded parallel behavior. -- Explicit local task orchestration is provided only through reviewable `.codex/**` task, lock, and run state. -- Custom IDs must use the `custom-*` prefix. -- Custom file references must be project-safe relative paths. -- Custom entries must not replace built-in role, workflow, or template IDs. -- Workflow prompt rendering may append only selected workflow templates. -- Role prompt rendering may list only selected active-engine references. -- The template root may track all engine specialist custom-agent files. -- Runtime project state selects exactly one active engine specialist for a project. -- Init must not generate `.codex/agents/*.toml`, `.codex/workflows/*.md`, `.agents/skills/*/SKILL.md`, or `.codex/prompts/**` mirrors. - -## Flows And States - -- Workflow prompt flow reads project stage, studio mode, and engine from `.codex/studio.json`. -- Workflow prompt flow selects declared context files through the path-safe selector. -- It computes phase and studio-mode eligibility. -- It creates a Codex studio session for the owning role and phase. -- It renders the standard prompt with a context contract and appends selected workflow templates. -- Custom workflow prompt flow resolves the workflow or alias from `.codex/studio/config.json`. -- It accepts a validated built-in role or project-local custom role target. -- It selects the declared workflow file plus other project-safe context files. -- It renders the workflow file body as workflow instructions. -- It renders either the built-in session role contract or the custom role prompt. -- It appends only the custom workflow's selected template IDs. -- Template selection matches role and task text against bounded keyword rules. -- Template selection returns only matching template IDs. - -## Contracts - -- Role IDs are stable strings exported from `src/roles.ts`. -- Role IDs are reused by config validation, project state, prompt rendering, workflow routing, and task creation. -- Role-package structured-contract fields are rendered into standard Codex session prompts. -- Engine reference prompt selection maps role IDs, optional task/workflow keywords, and active project engine to generated project paths under `docs/engine-reference//`. -- Every engine pack includes version, current best practices, deprecated API, breaking-change, gameplay, specialist, module, and plugin references. -- Engine reference assets carry seed-review metadata. -- Workflow IDs map to `.codex/workflows/.md` files, expected context files, taxonomy categories, gap-coverage notes, and optional CLI aliases. -- Repository skill IDs map to `.agents/skills//SKILL.md` template files. -- Prompt-surface discovery metadata validation rejects generic agent descriptions, generic workflow argument hints, and non-actionable skill descriptions. -- The CCGS parity audit inventories reference agents, skills, workflow-catalog steps, templates, and rules into JSON and Markdown matrix reports. -- The parity matrix records source hashes, CGS target paths, target hashes when a tracked target exists, decisions, score fields, rationales, owner paths, test paths, and implementation status. -- The workflow catalog models phase progression, required steps, optional steps, repeatable steps, artifact checks, and next-phase links without importing Claude slash-command runtime behavior. -- Status output includes the next incomplete workflow-catalog phase and required artifact checks. -- Repository skills contain per-skill phases, context files, write targets, quality gates, handoff/report formats, and required marker validation. -- Behavioral scenario IDs map to representative roles or workflows in `src/behavioral-evaluation.ts`. -- Each scenario declares required phrases, forbidden drift phrases, selected-context categories, and workflow template expectations. -- Required template expectations apply to both project-backed and no-project workflow rendering. -- Template IDs map to package paths, project-local paths, descriptions, role/workflow hints, tags, and required-section validation. -- Current built-in templates cover design, analytics, engine setup, market analysis, feel tuning, art direction, UI/UX, production, playtest, and ship checks. -- They also cover ADRs, technical design, traceability, art, audio, UX, accessibility, testing, and sprints. -- Additional templates cover release, postmortems, risk, economy, difficulty, player journeys, and pitches. - -## Product Truth Links - -- docs/truthmark/product/codex-game-studio-cli.md - -## Engineering Decisions - -- Decision (2026-05-28): Use Codex-native hyphenated role IDs as the user- and project-facing role contract. -- Decision (2026-06-26): Workflow shortcut aliases render prompts and do not execute Codex. -- Decision (2026-06-26): Keep planner/next, telemetry, ownership enforcement, hosted orchestration, background loops, and unbounded parallelism absent from role and workflow prompt surfaces. -- Decision (2026-06-26): Keep local task orchestration ownership in runtime/task execution; role and workflow surfaces provide prompt and recipe inputs. -- Decision (2026-06-13): Workflow prompts use the same context-contract renderer as role-run prompts. -- Decision (2026-06-13): Workflow prompts include only selected workflow context. -- Decision (2026-06-14): Add one specialist role ID per supported engine. -- Decision (2026-06-14): Keep engine reference prompt selection scoped to the active engine. -- Decision (2026-06-14): Keep engine specialist IDs canonical. -- Decision (2026-06-17): Expand role coverage through bounded specialist clusters instead of mirroring CCGS file-for-file. -- Decision (2026-06-17): Keep each new role as a renderable package with selected context, expected outputs, and a review checklist. -- Decision (2026-06-17): Expand workflow coverage as a prompt-only catalog with local aliases and metadata. -- Decision (2026-06-17): Do not import slash-command lifecycle machinery. -- Decision (2026-06-17): Expand production templates as package-shipped, metadata-rich templates selected by relevance. -- Decision (2026-06-17): Expand engine reference depth as package-shipped, metadata-validated active-engine assets. -- Decision (2026-06-17): Select module and plugin references by task or workflow keywords. -- Decision (2026-06-17): Expand role prompt depth through compact structured contracts and reusable shared fragments. -- Decision (2026-06-17): Render shared fragments in standard session prompts. -- Decision (2026-06-17): Add deterministic behavioral-evaluation fixtures instead of hosted or LLM-based evaluators. -- Decision (2026-06-17): Add project-local customization as an extend-only overlay for `custom-*` roles, workflows, and templates. -- Decision (2026-06-17): Let custom workflows reuse built-in roles instead of requiring duplicate local role definitions. -- Decision (2026-06-17): Reuse the built-in QA review surface for custom role review passes. -- Decision (2026-06-17): Use the configured custom role prompt for custom fix passes. -- Decision (2026-06-29): Treat `.codex/agents`, `.codex/workflows`, and `.agents/skills` as tracked template repository surfaces. -- Decision (2026-06-29): Validate prompt-surface discovery metadata as selection contracts before further prompt body expansion. -- Decision (2026-06-29): Assemble runtime role prompt packets in memory instead of generating `.codex/prompts/**` mirrors. - -## Rationale - -Tracked template files make the game-studio surface inspectable and reviewable in Git. - -Runtime prompt rendering keeps project-specific context fresh without generating durable instruction mirrors. - -Keeping workflow shortcuts render-only avoids overclaiming automation that is not implemented. - -## Non-Goals - -- This doc does not own whether Codex is installed or authenticated. -- This doc does not own task lifecycle mutations. -- This doc does not own project initialization state writes. -- This doc does not define CI or package publishing. - -## Maintenance Notes - -- Update this doc when role-package fields change. -- Update this doc when workflow registry behavior changes. -- Update this doc when tracked custom-agent, workflow, or skill file expectations change. -- Relevant tests include roles, workflow catalog, workflow recipes, runner, context files, functionality-gap coverage, and template repository surfaces. - -## Source References - -- ../../routes/areas/repository.md -- ../../../../src/roles.ts -- ../../../../src/agents.ts -- ../../../../src/workflows.ts -- ../../../../src/templates.ts -- ../../../../src/runner.ts -- ../../../../src/context-manifest.ts -- ../../../../src/behavioral-evaluation.ts -- ../../../../src/skills.ts -- ../../../../src/ccgs-parity.ts -- ../../../../.codex/agents/** -- ../../../../.codex/workflows/** -- ../../../../.agents/skills/** -- ../../../../tests/roles.test.ts -- ../../../../tests/workflow-recipes.test.ts -- ../../../../tests/runner.test.ts -- ../../../../tests/codex-context-files.test.ts -- ../../../../tests/functionality-gap-pass.test.ts -- ../../../../tests/template-repository-surfaces.test.ts - -## Codex prompt model routing - -Prompt surfaces declare exact Codex model policy in tracked template files. Complex design, architecture, production, and release-gate surfaces use `gpt-5.5`; moderate implementation, QA, docs, bugfix, and bounded workflow surfaces use `gpt-5.4`; simple help, status, classification, checklist, and lookup surfaces use `gpt-5.4-mini`. Runtime dry-runs and run metadata expose the selected model and reasoning effort, and Codex execution receives the exact selected model instead of a generic tier name. diff --git a/docs/truthmark/engineering/codex/runtime-and-tasks.md b/docs/truthmark/engineering/codex/runtime-and-tasks.md deleted file mode 100644 index 5297a7f..0000000 --- a/docs/truthmark/engineering/codex/runtime-and-tasks.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -status: active -truth_kind: engineering-workflow -last_reviewed: 2026-06-26 ---- - -# Runtime And Task Execution - -## Purpose - -Runtime and task execution connects prepared Codex Game Studio prompts to the Codex CLI. - -It also preserves explicit task state and runs bounded verification, review, fix, and local task orchestration loops when task state, locks, approvals, selected context, run metadata, and failures stay reviewable. - -## Scope - -This leaf doc owns `run` preparation and execution, Codex command construction, availability checks, and task-store persistence. - -It also owns review/fix lifecycle behavior, studio policy primitives, sandbox policy, and structured verification command execution. - -It does not own role prompt content, project scaffolding, or public CLI help wording unless runtime behavior depends on those options. - -## Triggers - -- A user invokes `run ... --project ` to render or execute a role prompt. -- A user creates a file-backed task through `task create`. -- A user runs a file-backed task through `task run`. -- A user orchestrates ready file-backed tasks through `task orchestrate`. -- A user creates explicit task graphs through `workflow create-tasks `. -- A run includes structured verification, review, or bounded fix-pass options. - -## Inputs - -- A valid project root with `.codex/studio.json`. -- A valid project root with `.codex/studio/config.json`. -- A generated built-in role prompt or a project-local custom role prompt for the requested role. -- A studio role ID or task ID. -- A non-empty task or objective. -- Optional included artifacts. -- Optional declared write files for task approval and orchestration locks. -- Optional task dependencies, workflow IDs, group IDs, and priority. -- Optional verification command and arguments. -- Optional review flag, fix flag, and max fix-pass count. - -## Current Implementation Behavior - -Runtime execution prepares bounded Codex prompts before side effects. - -It evaluates studio write policy before mutation. - -It records visible run, task, orchestration, verification, review, and fix outcomes in `.codex/**` state for non-inspection paths. - -## Execution Model - -- `prepareRun` resolves the project and reads studio state. -- `prepareRun` assembles runtime role context from tracked custom agents, typed role metadata, project state, and selected package templates. -- `prepareRun` renders a Codex prompt, computes cache paths, and builds Codex execution commands. -- Custom `custom-*` role runs use the configured custom prompt file. -- Custom runs also use configured expected outputs, review checklist, selected local templates, and declared context files. -- Custom runs pass through the same path-safe selector and studio-policy gates as built-in roles. -- `prepareRun` rejects wrong-engine specialist roles before prompt construction. -- For example, a Godot project may run `godot-specialist` but not `unity-specialist`. -- `--print-prompt` and `--dry-run` are inspection-only paths. -- Inspection paths do not write prompt cache, metadata, task state, or run directories. -- Runtime prompt preparation uses the path-safe context selector. -- The selector handles required role context, task-relevant active-engine references, included artifacts, and explicit broad context. -- The selector rejects absolute paths, traversal, control characters, symlink escapes, secret-like paths, generated output, build output, binary entries, and non-file entries. -- Missing required context is recorded as a context-contract omission. -- Missing context never widens reads. -- Context selection gives required entries budget priority. -- Required entries still must pass path safety, generated-output checks, binary checks, per-entry character limits, total character limits, and file-count limits. -- Included artifact bodies are embedded only when the artifact is selected. -- Rejected or omitted artifacts remain visible in context-contract omissions. -- `--allow-broad-context` adds an explicit bounded list of candidate project files. -- Candidates include the GDD, production timeline, and market overview. -- Broad-context candidates still pass through the selector and must resolve under the project root. -- `run ` and `task run` compute one `evaluateStudioRunEligibility` result before prompt-cache writes, Codex spawn, or task mutation. -- Eligibility carries `allowed`, `writePolicy`, `allowFileEdits`, `codexSandbox`, `reason`, optional `requiredApproval`, and provenance metadata. -- Strict studio mutating implementation and fix runs require a matching approval. -- Without approval, strict non-dry runs fail before `.codex/runs/**` writes and task mutation. -- Guided studio mutating runs require a matching approval or `--approved-by-user`. -- The local override uses `override-write` provenance. -- Fast-prototype mutating runs use advisory write provenance. -- Dry-run output includes eligibility, write policy, sandbox, file-edit permission, provenance, and approval diagnostics. -- Dry-run does not write run metadata. -- Non-dry runs write prompt and metadata before executing Codex. -- Built-in implementation, review, and fix prompts include a shared `# Context Contract` section. -- The context contract records project stage, studio mode, phase, write policy, sandbox, file-edit permission, selected context, omissions, and blockers. -- Custom role review and fix prompts also use the shared context contract. -- Custom implementation prompts keep their custom-role session shape. -- Custom implementation prompts still list selected context and active policy fields. -- Review prompts add read-only review instructions. -- Fix prompts preserve selected implementation context and include bounded blocker placeholders. -- Implementation and fix passes use `danger-full-access` by default when file edits are allowed. -- `workspace-write` is used only when the caller passes `--constrained-sandbox`. -- Review passes use a read-only Codex sandbox. -- Built-in fix prompts receive the same runtime role context and selected templates as the primary implementation prompt. -- Custom fix prompts receive the configured custom role prompt and selected local templates. -- Review prompts receive QA playtester runtime context plus selected QA templates. -- Prompt, session, and run metadata records active write policy, file-edit permission, sandbox, and eligibility metadata. -- `src/studio-policy.ts` defines pure project-stage and studio-mode policy helpers. -- Policy helpers keep lifecycle stage separate from studio mode. -- Plan, review, and ship phases map to read-only behavior. -- Implementation and fix phases classify mutating eligibility. -- Allowed mutating policies map to `danger-full-access` unless constrained sandbox is explicitly requested. -- Task runs mutate task status only for non-dry execution. -- Task orchestration preflights selected tasks without writing run, lock, or task state. -- Non-dry task orchestration records an orchestration run under `.codex/runs//`, writes per-task prompt/output metadata under `tasks//`, and uses `.codex/locks/` for transient write locks. -- Bounded parallel orchestration caps `--max-concurrency` at 3. -- Mutating orchestrated tasks without declared `writeFiles` use a conservative project-wide write lock. -- `files` are read/context inputs; `writeFiles` are mutation approval and lock inputs. - -## Steps - -1. Validate the requested role or task and project state. -2. Select path-safe context entries. -3. Record missing, omitted, and rejected entries for the context contract. -4. Compute shared studio-run eligibility. -5. Block non-dry mutating runs when eligibility is not allowed. -6. Let inspection paths render diagnostics without mutation. -7. Render the Codex prompt with active write policy and sandbox. -8. For non-dry allowed runs, write prompt and metadata cache under `.codex/runs/`. -9. Check Codex availability before execution. -10. Execute the implementation prompt. -11. Run verification when configured. -12. Run review when requested and verification passes or is absent. -13. Run bounded fix passes when requested and blockers remain. -14. Report final status as `done` or `blocked`. -15. Persist final task status for task runs. - -## State, Retry, And Failure Behavior - -- Task stores live at `.codex/tasks.json`. -- Task stores use schema version 2 and unique `task-###` IDs; schema version 1 stores are normalized on read and rewritten as version 2 when saved. -- `task create` requires a valid studio project before writing task state. -- Task statuses are `ready`, `running`, `blocked`, `done`, `cancelled`, and `skipped`. -- Task dependency records require dependent tasks to reach `done`. -- Orchestration serializes task-store writes while bounded tasks execute. -- Verification commands use bounded stdout and stderr capture. -- Verification commands use a default timeout. -- Timed-out verification receives SIGTERM, then SIGKILL after the configured grace period. -- Malformed review JSON leaves the lifecycle blocked unless a later fix pass clears it. -- Non-zero Codex execution leaves the lifecycle blocked unless a later fix pass clears it. -- Failed verification leaves the lifecycle blocked unless a later fix pass clears it. -- Review blockers leave the lifecycle blocked unless a later fix pass clears them. - -## Outputs - -- Dry-run output lists eligibility, write policy, sandbox, context files, approval diagnostics, and the Codex command. -- Dry-run output does not write cache files. -- Print-prompt output is the deterministic prompt body. -- Non-dry run output reports implementation, verification, review, fix-pass, and final-status summaries. -- Task creation prints the new task ID. -- Task orchestration dry-runs print planned tasks, dependencies, locks, selected context, and Codex commands. -- Non-dry orchestration output reports per-task status and final orchestration status. - -## Product Truth Links - -- docs/truthmark/product/codex-game-studio-cli.md - -## Engineering Decisions - -- Decision (2026-05-28): Make dry-run and print-prompt non-mutating inspection paths. -- Decision (2026-05-28): Force review prompts through a read-only sandbox. -- Decision (2026-05-28): Require a valid project before task-store writes. -- Decision (2026-06-29): Use tracked custom agents, runtime role context, project state, and selected templates as runtime prompt input. -- Decision (2026-05-30): Keep broad context discovery bounded. -- Decision (2026-06-13): Keep the first studio-policy slice as pure mapping helpers. -- Decision (2026-06-13): Default allowed mutating policy results to `danger-full-access`. -- Decision (2026-06-13): Expose `workspace-write` only through the explicit constrained-sandbox option. -- Decision (2026-06-13): Route direct role runs and task runs through shared eligibility before mutation. -- Decision (2026-06-13): Fail closed for unapproved strict-studio mutation. -- Decision (2026-06-13): Use one shared context-contract renderer for implementation, review, and fix prompts. -- Decision (2026-06-13): Make selected context and write policy visible without broad prompt loading. -- Decision (2026-06-14): Fail wrong-engine specialist runs before contradictory prompts or run metadata writes. -- Decision (2026-06-17): Add task-relevant active-engine reference requests to role-run and workflow context contracts. -- Decision (2026-06-17): Select module and plugin depth by role/task relevance instead of broad prompt loading. -- Decision (2026-06-17): Route custom role runs through the same write-policy, sandbox, context, cache, and template contracts as built-in roles. -- Decision (2026-06-17): Do not introduce a separate plugin runtime for custom roles. -- Decision (2026-06-17): Honor review/fix flags for custom role runs with real lifecycle prompts. -- Decision (2026-06-25): Move explicit local task orchestration into the product boundary while keeping hosted orchestration, background loops, hidden planners, and unbounded parallelism out of scope. -- Decision (2026-06-25): Implement orchestration as a foreground `task orchestrate` command with side-effect-free preflight, schema-version-2 task state, transient `.codex/locks/`, and bounded concurrency capped at 3. -- Decision (2026-06-25): Bind task approval and orchestration locks to declared `writeFiles`; keep `files` as read/context inputs. -- Decision (2026-06-17): Use a read-only QA review prompt and a bounded custom-role fix prompt. - -## Rationale - -Codex execution is intentionally explicit. Users can inspect prompts without side effects before running implementation. - -Non-dry runs use visible cache paths and verification output. Read-only review prevents review from becoming a second implementation pass. - -## Non-Goals - -- This workflow implements explicit bounded local task orchestration; it does not implement hidden parallel execution. -- This workflow does not implement hosted orchestration, background autonomous loops, or unbounded parallelism. -- This workflow does not implement telemetry. -- This workflow does not implement ownership enforcement. -- This workflow does not implement a planner or next queue. -- This workflow does not choose role prompt content. - -## Maintenance Notes - -- Update this doc when runtime, task, customization, context, Codex runtime, or verification behavior changes. -- Update this doc when `src/studio-policy.ts` policy primitive behavior changes. -- Relevant verification includes studio-policy, runner, task, verification, Codex runtime, and lifecycle-focused tests. - -## Source References - -- ../../routes/areas/repository.md -- ../../../../src/runner.ts -- ../../../../src/studio-policy.ts -- ../../../../src/context.ts -- ../../../../src/customization.ts -- ../../../../src/context-manifest.ts -- ../../../../src/prompt-context.ts -- ../../../../src/tasks.ts -- ../../../../src/orchestrator.ts -- ../../../../src/orchestrator-locks.ts -- ../../../../src/workflow-recipes.ts -- ../../../../src/ccgs-adaptation.ts -- ../../../../src/codex-runtime.ts -- ../../../../src/verification.ts -- ../../../../tests/runner.test.ts -- ../../../../tests/studio-policy.test.ts -- ../../../../tests/tasks.test.ts -- ../../../../tests/orchestrator.test.ts -- ../../../../tests/workflow-recipes.test.ts -- ../../../../tests/ccgs-adaptation.test.ts -- ../../../../tests/verification.test.ts -- ../../../../tests/codex-runtime.test.ts - -## Codex prompt model routing - -Prompt surfaces declare exact Codex model policy in tracked template files. Complex design, architecture, production, and release-gate surfaces use `gpt-5.5`; moderate implementation, QA, docs, bugfix, and bounded workflow surfaces use `gpt-5.4`; simple help, status, classification, checklist, and lookup surfaces use `gpt-5.4-mini`. Runtime dry-runs and run metadata expose the selected model and reasoning effort, and Codex execution receives the exact selected model instead of a generic tier name. diff --git a/docs/truthmark/engineering/contracts/cli-and-validation.md b/docs/truthmark/engineering/contracts/cli-and-validation.md deleted file mode 100644 index 7eb7618..0000000 --- a/docs/truthmark/engineering/contracts/cli-and-validation.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -status: active -truth_kind: engineering-contract -last_reviewed: 2026-06-27 ---- - -# CLI And Validation Contracts - -## Purpose - -The CLI and validation contracts define the public `codex-game-studio` command surface. - -They also define package entrypoints, hard-failing validation checks, and future-surface guardrails. - -## Scope - -This leaf doc owns the repository CLI command contract, package scripts, package bin/files expectations, validation checks, and documented public-surface claims. - -It does not own project scaffolding internals, role prompt content, or Codex runtime lifecycle details. Runtime details appear here only when they are exposed as CLI options. - -## Current Implementation Behavior - -- The repository exposes a package CLI named `codex-game-studio`. -- The source checkout exposes a root `./codex-game-studio` wrapper. -- The wrapper executes built TypeScript output at `dist/cli.js` and tells users to run `npm install && npm run build` when it is missing. -- The TypeScript build entrypoint remains `dist/cli.js` for contributor and package validation. -- The CLI supports project initialization and status commands. -- It supports template discovery and project-local customization inspection. -- It supports role execution, file-backed tasks, approval-store management, workflow prompt rendering, workflow shortcut aliases, context-manifest refresh, and validation. -- Repository validation is executable through `npm run validate`. -- `npm run validate` builds TypeScript output and runs the built CLI validation command. -- Validation includes deterministic behavioral-evaluation scenarios for representative prompts. -- Behavioral-evaluation subchecks render prompts and inspect obligations locally. -- They do not use hosted evaluators, telemetry, hidden memory, or LLM calls. - -## Contract Surface - -- Package name: `codex-game-studio`. -- Package bin: `codex-game-studio` points to `./dist/cli.js`. -- 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. -- Public command groups also include template discovery, role runs, file-backed tasks, approval management, generic workflow rendering, and render-only workflow shortcuts. -- `codex-game-studio templates list --project ` includes project-local custom templates beside built-in templates. -- `codex-game-studio templates show --project ` can show project-local custom templates. -- `codex-game-studio workflow --project ` renders built-in workflow IDs. -- The same command also renders extend-only project-local custom workflow IDs and aliases. -- Render-only discovery shortcuts include market, analytics, start, onboard, brainstorm, and prototype. -- Render-only design shortcuts include design-spec, feel-review, art-direction, ui-review, architecture-decision, and architecture-review. -- Render-only production shortcuts include milestone, handoff, review, ship-check, release-checklist, and hotfix. -- Render-only planning shortcuts include create-epics, create-stories, sprint-plan, sprint-status, story-readiness, and story-done. -- Render-only QA and operations shortcuts include qa-plan, regression-suite, security-audit, perf-profile, and localization-plan. -- `codex-game-studio init` and `codex-game-studio new` accept `--studio-mode fast-prototype|guided-studio|strict-studio`. -- Omitted `--studio-mode` defaults to `guided-studio`. -- Generated `.codex/studio.json` persists the value as `studioMode`. -- `codex-game-studio approval grant --project --role --task --scope ` appends a scoped approval record. -- Approval grant accepts built-in roles and syntactically valid `custom-*` role IDs. -- Approval grant requires a safe, non-empty scope. -- Approval grant accepts either an existing same-role task ID or a 64-character SHA-256 objective hash. -- `codex-game-studio approval list --project ` prints approval history. -- Approval history includes revoked and expired records as visible non-authorizing records. -- `codex-game-studio approval revoke --project --approval-id ` sets `revokedAt` on the matching record. -- Revocation preserves approval history. -- `codex-game-studio run --project --dry-run --approval-scope ` prints approval mismatch diagnostics. -- The dry-run approval diagnostics apply to guided and strict studio modes. -- Dry-run approval diagnostics do not write prompt cache or run metadata. -- `codex-game-studio run ` and `codex-game-studio task run` expose `--approved-by-user` for guided-studio local override. -- They expose `--constrained-sandbox` for explicit `workspace-write` sandbox use. -- Without the constrained override, allowed mutating runs use `danger-full-access`. -- `codex-game-studio task run` accepts `--approval-scope `. -- Repository validation is exposed through `codex-game-studio validate` and `npm run validate`. -- Context-manifest refresh is exposed through `codex-game-studio refresh-context --project `. - -## Inputs - -- CLI options and arguments parsed by Commander in `src/cli.ts`. -- Repository files checked by validation. -- Checked files include package metadata, source files, templates, generated build output, engine configs, and engine reference packs. -- Checked inputs also include behavioral-evaluation scenarios and optional project paths. -- Project validation input when `--project ` is supplied. -- Project-local customization config at `.codex/studio/config.json`. -- Referenced local prompt, context, workflow, and template files. - -## Outputs - -- CLI commands print human-readable status, prompt, task, validation, or workflow output. -- Approval grant output includes the new approval ID, normalized role, objective/hash information, scopes, and approval-store path. -- Stored approval records include baseline metadata. -- Dry-run role-run output includes eligibility, write policy, Codex sandbox, file-edit permission, provenance, project stage, and studio mode. -- It also includes approval scopes, current objective hash, match status, and authorization reasons. -- Authorization reasons include role, objective, scope, project stage, studio mode, expiry, revocation, and stage mismatches. -- Validation emits one line per check in `STATUS id: message (path)` shape. -- Context refresh prints the refreshed project name and both context manifest paths. -- Validation exits non-zero when any check fails. -- Behavioral evaluation check IDs use `behavioral.scenario.`. -- Behavioral checks fail when prompts miss required obligations. -- They also fail on unnegated future-only drift, prompt-size overflow, missing selected-context categories, missing required templates, or forbidden templates. -- Package smoke validation builds TypeScript output and exercises the packed package bin. -- Package smoke validation also checks template loading behavior. -- Package validation checks every registered engine reference asset is included in `npm pack`. - -## Errors And Diagnostics - -- Unknown roles fail with a message naming Codex-native hyphenated role IDs. -- Approval grant rejects empty scopes. -- Approval grant rejects unsafe scopes. -- Approval grant rejects broad scopes unless `--allow-broad-scope` is supplied. -- Broad scopes include `**`, `**/*`, `*`, and `.`. -- Approval grant rejects invalid roles, unknown task IDs, wrong-role task IDs, and malformed canonical expiry timestamps. -- Approval revoke fails clearly for unknown approval IDs. -- Unapproved strict-studio mutating `run ` and `task run` fail before Codex launch, run metadata writes, or task mutation. -- Validation fails on missing package scripts, package bin/files, source wrapper, source files, Codex CLI, role packages, templates, and engine reference assets. -- It also fails on missing build output or broken package smoke behavior. -- Validation fails when engine reference metadata is missing reviewer, date, source link, engine, reviewed version, tags, roles, or workflows. -- Validation fails when future surfaces are exposed early. -- Project validation fails when `.codex/studio.json` is invalid. -- It fails when `.codex/approvals.json` is missing, malformed, or schema-invalid. -- It fails when `.codex/context-manifest.json` or its metadata sidecar is missing, malformed, or stale. -- It fails when `.codex/studio/config.json` is invalid. -- It fails when custom IDs override built-ins or omit the `custom-*` prefix. -- It fails for unsafe custom paths, missing custom files, missing custom template sections, and unknown custom references. -- It fails for missing generated project files and missing active-engine references. -- It fails for missing active-engine specialist prompts or materialized wrong-engine specialist prompts. -- It fails for missing workflow/prompt sections, stale generated metadata, tampered metadata, and current-renderer mismatches. -- It also fails for forbidden generated surfaces and read-only command mutations. -- Generated prompt or workflow files with no metadata markers are legacy skip diagnostics. -- Legacy skip diagnostics require regeneration before freshness checks can be trusted. - -## Compatibility Rules - -- The TypeScript project uses NodeNext ESM semantics. -- Relative TypeScript imports must use emitted `.js` specifiers. -- Node support requires a package engine floor that includes Node >=24. -- Packaged files must include `dist/`, `engine_configs/`, `engine_reference/`, and `templates`. -- Future-only command surfaces stay hidden until implemented intentionally. -- Future-only examples include `next`, `telemetry`, hosted/background orchestration, unbounded parallelism, and ownership enforcement. - -## Versioning And Migration - -- Current package version is managed in `package.json`. -- Commander renders the package version. -- CLI contract changes should update README claims, validation expectations, and tests in the same change. - -## Product Truth Links - -- docs/truthmark/product/codex-game-studio-cli.md - -## Engineering Decisions - -- Decision (2026-05-28): Keep `validate` as the hard-failing parity gate before readiness claims. -- Decision (2026-05-28): Test that future planner, telemetry, parallel, and ownership surfaces are not exposed. -- Decision (2026-05-30): Historical generated-surface metadata checks were replaced by tracked template-surface validation for clone-visible files. -- Decision (2026-06-13): Treat `.codex/approvals.json` as a required generated project contract. -- Decision (2026-06-13): Fail project validation with `codex.project.approvals` when the approval store is missing, malformed, or schema-invalid. -- Decision (2026-06-13): Expose approval grant/list/revoke as audit-store management commands. -- Decision (2026-06-13): Wire approval matching into mutating `run ` and `task run` eligibility. -- Decision (2026-06-13): Expose approval mismatch information through dry-run diagnostics. -- Decision (2026-06-13): Fail unapproved strict-studio mutation before side effects. -- Decision (2026-06-13): Treat context manifest and sidecar metadata as required generated project contracts. -- Decision (2026-06-13): Validate manifest schema and sidecar freshness. -- Decision (2026-06-14): Validate engine reference packs by registered file presence and seed-review metadata shape. -- Decision (2026-06-14): Validate active-engine materialized references without judging prose quality. -- Decision (2026-06-17): Expose the expanded workflow catalog as render-only CLI shortcuts. -- Decision (2026-06-26): Keep planner/next, telemetry, hosted/background orchestration, unbounded parallelism, and ownership enforcement absent from public CLI and validation surfaces. -- Decision (2026-06-25): Treat explicit local task orchestration as in-boundary once it has CLI behavior, validation, tests, and truth docs; keep hosted/background orchestration and unbounded parallelism hidden. -- Decision (2026-06-17): Add local deterministic behavioral-evaluation subchecks. -- Decision (2026-06-17): Do not use hosted evaluators, telemetry, hidden memory, or LLM judges for those checks. -- Decision (2026-06-17): Support project-local customization as an extend-only `custom-*` overlay. -- Decision (2026-06-17): Validate customization schema, project-safe paths, generic workflow rendering, and template inspection. -- Decision (2026-06-17): Do not allow customization to replace built-in registries. - -## Rationale - -The CLI is the stable integration boundary for humans, package installs, and generated project smoke checks. - -Validation makes those claims executable. Prompt-surface drift and packaging drift should fail before release or parity claims. - -## Non-Goals - -- This contract does not document every generated prompt body. -- This contract does not define approval matching, revocation, expiry, or scope normalization rules. -- This contract does not define the internal runtime lifecycle. -- This contract does not define npm audit remediation policy. - -## Maintenance Notes - -- Update this doc when CLI behavior, validation behavior, behavioral-evaluation checks, context-manifest checks, or engine-reference checks change. -- Also update it when package metadata, README claims, or validation IDs change. -- Relevant verification includes `npm run validate`, CLI help smoke checks, validation tests, context tests, and functionality-gap tests. -- It also includes validation tests, package smoke checks, and future-surface guard tests. - -## Source References - -- ../../routes/areas/repository.md -- ../../../../package.json -- ../../../../src/cli.ts -- ../../../../src/projects.ts -- ../../../../src/validation.ts -- ../../../../src/customization.ts -- ../../../../src/context-manifest.ts -- ../../../../src/engine-reference.ts -- ../../../../src/generated-surfaces.ts -- ../../../../src/behavioral-evaluation.ts -- ../../../../tests/project-workflow.test.ts -- ../../../../tests/validation.test.ts -- ../../../../tests/functionality-gap-pass.test.ts -- ../../../../tests/codex-context-files.test.ts -- ../../../../tests/template-repository-surfaces.test.ts diff --git a/docs/truthmark/engineering/projects/project-scaffolding.md b/docs/truthmark/engineering/projects/project-scaffolding.md deleted file mode 100644 index 1674bf4..0000000 --- a/docs/truthmark/engineering/projects/project-scaffolding.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -status: active -truth_kind: engineering-behavior -last_reviewed: 2026-06-29 ---- - -# Project Scaffolding - -## Purpose - -Project scaffolding records project-specific state inside a cloned Codex Game Studio template repository. - -The template repository already contains the game-facing Codex agents, workflows, skills, and root instructions. - -## Scope - -This leaf doc owns project initialization, project state, engine-specific files and folders, active-engine reference materialization, and read-only project status/resume behavior. - -It owns stateful `.codex/**` files such as `studio.json`, approval state, context manifests, run folders, task state, and project config. - -It does not own the instruction bodies in `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, or `.agents/skills/*/SKILL.md`. - -It does not own Codex run execution, task lifecycle persistence after creation, or repository-level CLI validation. - -## Current Implementation Behavior - -- `init` and `new` share the same initialization path. -- Initialization requires `--name`, `--engine`, `--mode`, and `--non-interactive`. -- Initialization accepts optional `--studio-mode` and defaults it to `guided-studio`. -- Initialization writes project state into the current repository root by default. -- Initialization rejects an existing different root project unless force refresh is explicit. -- Project state is written to `.codex/studio.json`. -- Project state uses schema version 1 and product `codex-game-studio`. -- Project state records project summary fields, lifecycle `mode`, policy `studioMode`, project-scoped roles, active roles, active engine specialist, and workflow IDs. -- Initialization writes an empty versioned `.codex/approvals.json` approval store. -- Initialization writes `.codex/studio/config.json` as an extend-only customization seed. -- The default customization file contains no local roles, workflows, or templates. -- Projects can add `custom-*` IDs without overriding built-in IDs. -- Initialization writes `.codex/context-manifest.json` and `.codex/context-manifest.meta.json`. -- The manifest records selected context entries with source path, reason, required flag, budget metadata, safety classification, and selection status. -- Freshness hashes and inputs live only in the context-manifest metadata sidecar. -- Initialization materializes only the active engine reference pack. -- Active engine references are copied under `docs/engine-reference//` from packaged `engine_reference//` assets before the context manifest is written. -- Context selection rejects unsafe, secret-like, generated-output, build-output, binary, and non-file paths before budget allocation. -- Existing required entries receive budget priority. -- Required entries must still fit file-count, per-entry character, and total character budgets. -- Default context manifest requests include selected active-engine reference files. -- Default context manifest requests do not include unrelated engine packs. -- Engine scaffolding uses the configured engine registry for Godot, Unity, and Unreal markers and source folders. -- Initialization writes starter design docs, production docs, market docs, engine marker files, state files, and runtime folders. -- Initialization does not create or overwrite `AGENTS.md`. -- Initialization does not create or overwrite `.codex/agents/*.toml`. -- Initialization does not create or overwrite `.codex/workflows/*.md`. -- Initialization does not create or overwrite `.agents/skills/*/SKILL.md`. -- Project-scoped roles include all non-specialist catalog roles. -- Project-scoped roles include exactly one active engine specialist role. -- Runtime role prompt packets are assembled in memory from tracked custom agents, typed role metadata, selected templates, and project state. -- Runtime role prompt packets are not mirrored to `.codex/prompts/**` during initialization. -- `status` and `resume` read project state without mutating `.codex/studio.json`. -- `freeze` intentionally changes project status to `frozen`. - -## Core Rules - -- Project creation is deterministic and non-interactive. -- Missing `--non-interactive` or `--mode` is an error. -- Omitted `--studio-mode` uses `guided-studio`. -- Projects use the current repository root as the project workspace. -- Users get template instruction files by cloning the template repository. -- `init` must not copy template instruction files back into the cloned repository. -- `CODEX.md`, `project_orchestrator.md`, `.gamestudio/runs`, `.codex/hooks.json`, coding-standard `.codex/rules/*.rules`, and Truthmark maintenance agents are forbidden game-facing project surfaces. -- Wrong-engine specialist agents may exist as tracked template files but runtime validation selects the active engine specialist for project state. -- Template instruction freshness is reviewed through Git, not generated-surface metadata. -- Generated-surface freshness metadata is not required for tracked agents, workflows, or skills. - -## Flows And States - -- Initialization parses options, normalizes engine, derives slug, and rejects collisions. -- It creates root game engine files, project files, and `.codex/runs`. -- It writes the empty approval store, studio state, and default customization config. -- It writes starter docs. -- It materializes the active engine reference pack. -- It writes the context manifest and sidecar metadata. -- Project status states are `active`, `frozen`, and `inactive`. -- `freeze` is the only current CLI path that mutates project status. - -## Contracts - -- `codex-game-studio init --name --engine --mode --non-interactive [--studio-mode ]` initializes the current repository root and prints the created path. -- `codex-game-studio new` is an alias for initialization. -- `codex-game-studio status [--project ]` reads `.codex/studio.json`. -- `codex-game-studio resume [--project ]` reads `.codex/studio.json`. -- `codex-game-studio freeze [--project ]` operates on `.codex/studio.json` and changes status. - -## Product Truth Links - -- docs/truthmark/product/codex-game-studio-cli.md - -## Engineering Decisions - -- Decision (2026-05-28): Preserve Codex-native project state under `.codex/`. -- Decision (2026-05-28): Keep status and resume read-only. -- Decision (2026-05-28): Inspection commands must not alter project state. -- Decision (2026-06-13): Persist studio policy mode separately from lifecycle mode. -- Decision (2026-06-13): Store context manifest freshness metadata in a sidecar. -- Decision (2026-06-13): Keep the manifest body as stable JSON describing selected context. -- Decision (2026-06-13): Detect stale project-stage and studio-mode inputs separately. -- Decision (2026-06-14): Materialize packaged engine references only for the active engine. -- Decision (2026-06-14): Select prompt/context entries by relevance instead of loading all engine packs. -- Decision (2026-06-14): Keep all specialist IDs in the canonical role catalog. -- Decision (2026-06-17): Initialize `.codex/studio/config.json` as an extend-only customization overlay. -- Decision (2026-06-17): Let users add `custom-*` roles, workflows, and templates without replacing built-ins. -- Decision (2026-06-29): Treat the clone checkout root as the game root; do not maintain a script-installed or nested project compatibility mode. -- Decision (2026-06-29): Treat Codex agents, workflows, and skills as tracked template repository surfaces. -- Decision (2026-06-29): Do not generate, copy, or overwrite agent, workflow, or skill instruction bodies during `init`. -- Decision (2026-06-29): Assemble runtime role prompt packets in memory instead of materializing `.codex/prompts/**` mirrors. - -## Rationale - -A deterministic scaffold gives Codex stable project state without hiding template behavior inside generators. - -Clone-visible template files keep the game-facing assistant surface reviewable in Git. - -## Non-Goals - -- This doc does not own runtime Codex execution. -- This doc does not own task-store status transitions after project creation. -- This doc does not define game engine runtime behavior beyond initial marker files, folders, and selected seed references. -- This doc does not own approval matching, revocation, expiry, or scope normalization rules. - -## Maintenance Notes - -- Update this doc when project initialization behavior changes. -- Update this doc when context manifest, config, engine, path, engine config, or engine reference assets change. -- Update the template-surface docs when `AGENTS.md`, `.codex/agents`, `.codex/workflows`, or `.agents/skills` behavior changes. -- Relevant verification includes project workflow, template-repository, engine-system, context-file, and project validation tests. - -## Source References - -- ../../routes/areas/repository.md -- ../../../../src/projects.ts -- ../../../../src/context-manifest.ts -- ../../../../src/config.ts -- ../../../../src/engines.ts -- ../../../../src/engine-reference.ts -- ../../../../src/agents.ts -- ../../../../src/skills.ts -- ../../../../src/paths.ts -- ../../../../src/generated-surfaces.ts -- ../../../../src/customization.ts -- ../../../../engine_configs/** -- ../../../../engine_reference/** -- ../../../../tests/project-workflow.test.ts -- ../../../../tests/template-repository-surfaces.test.ts -- ../../../../tests/engine-system.test.ts -- ../../../../tests/codex-context-files.test.ts diff --git a/docs/truthmark/engineering/repository/README.md b/docs/truthmark/engineering/repository/README.md index f07bcd4..6ba4f77 100644 --- a/docs/truthmark/engineering/repository/README.md +++ b/docs/truthmark/engineering/repository/README.md @@ -1,27 +1,15 @@ --- status: active doc_type: index -last_reviewed: 2026-06-25 +last_reviewed: 2026-06-29 --- # Repository Truth Docs -This directory is reserved for repository-level truth indexes and generated Truthmark repository handoffs. +This directory is reserved for narrow Truthmark repository handoffs. -README.md files are indexes, not Truth Sync targets. Current bounded truth lives in: - -- [Project Scaffolding](../projects/project-scaffolding.md) -- [Codex Roles And Workflows](../codex/roles-and-workflows.md) -- [Runtime And Task Execution](../codex/runtime-and-tasks.md) -- [CLI And Validation Contracts](../contracts/cli-and-validation.md) -- [Approval Stores](../codex/approval-stores.md) - -Truthmark installs [Repository Bootstrap Routing](bootstrap-routing.md) as a generated handoff for fresh repositories. - -Use it only when the default broad route still needs to be split. In this repository, bounded areas in `../../routes/areas/repository.md` remain canonical. - -Do not expand the bootstrap handoff into behavior truth. +The only retained repository handoff is [Repository Bootstrap Routing](bootstrap-routing.md). Do not rebuild broad Codex Game Studio behavior docs here unless a bounded Truthmark workflow explicitly requires them. ## Source References -- ../../routes/areas/repository.md +- ../../routes/areas.md diff --git a/docs/truthmark/engineering/repository/overview.md b/docs/truthmark/engineering/repository/overview.md deleted file mode 100644 index 557cdc0..0000000 --- a/docs/truthmark/engineering/repository/overview.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -status: active -truth_kind: engineering-behavior -last_reviewed: 2026-06-26 ---- - -# Repository Overview - -## Purpose - -Codex Game Studio is a Codex-native workflow layer for game-development projects. - -The repository packages a TypeScript CLI. - -The CLI configures cloned game-template repositories, renders role/workflow prompts for Codex, runs bounded Codex lifecycles, and validates repository, template, and project-state contracts. - -## Scope - -This leaf doc summarizes the repository-level behavior surface. - -More specific behavior is owned by leaf truth docs. - -Those docs cover project scaffolding, Codex role/workflow behavior, runtime/task execution, approval stores, and CLI/validation contracts. - -They are listed in `docs/truthmark/routes/areas/repository.md`. - -## Current Implementation Behavior - -- The package exposes the `codex-game-studio` CLI from the built `dist/cli.js` entrypoint, and the source checkout exposes `./codex-game-studio` as a thin wrapper over built TypeScript output. -- Initialization commands create deterministic game project structure in the current repository root. -- Template repositories contain tracked `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, `.agents/skills/*/SKILL.md`, and initialized project state under `.codex/**`. -- Role run commands render deterministic Codex prompts. -- Unless in inspection mode, role run commands execute Codex with optional verification, review, and bounded fix passes. -- Workflow shortcut commands are render-only prompt surfaces. -- Workflow shortcuts do not imply hidden planner, hosted orchestration, background loops, unbounded parallelism, telemetry, or ownership enforcement behavior. -- Explicit local task orchestration is limited to reviewable `.codex/**` state. -- Validation checks package metadata, source files, templates, role/workflow rendering, behavioral-evaluation scenarios, and customization packs. -- It also checks future-surface guardrails, build output, and package install smoke behavior. - -## Core Rules - -- Repository behavior is grouped by behavior ownership. -- Truth docs do not mechanically mirror every source file. -- Template instruction contracts use tracked 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. -- Non-dry runs write prompt/run metadata before executing Codex. -- Truthmark is an injected repository-truth workflow/tooling layer. -- Truthmark is not an Codex Game Studio runtime feature unless product code implements Truthmark-facing behavior. - -## Flows And States - -Architecture runtime walkthroughs live under `docs/architecture/flows/**`. - -They explain branching logic and failure paths. They also link back to the bounded truth docs that own behavior. - -- Project initialization parses CLI input, normalizes engine/config, guards collisions, creates files, writes `.codex` state, writes starter docs, and leaves tracked template instruction files untouched. -- See `docs/architecture/flows/project-initialization.md`. -- Role run lifecycle validates role, project, and task. -- It renders prompt and context, may return inspection output, writes run cache, executes Codex, runs verification/review, may run fix passes, and reports `done` or `blocked`. -- See `docs/architecture/flows/role-run-lifecycle.md`. -- Workflow prompt rendering validates project context, resolves workflow alias or ID, renders deterministic prompt text, and returns without launching Codex or writing run state. -- See `docs/architecture/flows/workflow-prompt-rendering.md`. -- Repository validation builds the package, runs validation checks, and fails broken package, source, prompt, workflow, template, or future-surface contracts. -- See `docs/architecture/flows/validation-and-repository-truth.md`. - -## Contracts - -- Public CLI command contracts are owned by `docs/truthmark/engineering/contracts/cli-and-validation.md`. -- Role/workflow prompt contracts are owned by `docs/truthmark/engineering/codex/roles-and-workflows.md`. -- Runtime/task lifecycle contracts are owned by `docs/truthmark/engineering/codex/runtime-and-tasks.md`. -- Approval-store contracts are owned by `docs/truthmark/engineering/codex/approval-stores.md`. -- Project scaffolding contracts are owned by `docs/truthmark/engineering/projects/project-scaffolding.md`. - -## Product Truth Links - -- None. This engineering overview summarizes repository implementation ownership directly. - -## Engineering Decisions - -- Decision (2026-05-28): Route truth by behavior ownership rather than source-file mirroring. -- Decision (2026-05-30): Treat Truthmark Portal output as generated non-canonical presentation. -- Decision (2026-05-30): Keep Markdown truth docs canonical. -- Decision (2026-05-30): Use Markdown Architecture Flow Guides for important runtime-view scenarios. -- Decision (2026-05-30): Keep bounded Truthmark truth docs as behavior authority. - -## Rationale - -The repository combines scaffolding, prompt generation, runtime execution, approvals, and validation in one package. - -Bounded truth surfaces make the architecture easier to review. They also prevent generated agent workflow scaffolding from being mistaken for user-facing product behavior. - -## Non-Goals - -- This doc does not replace specific leaf truth docs. -- This repository does not expose hidden parallel orchestration, hosted orchestration, background autonomous loops, or unbounded parallelism. -- This repository does not expose telemetry. -- This repository does not expose planner/next queues. -- This repository does not expose ownership enforcement as public CLI behavior. -- Truthmark Portal HTML is generated presentation and is not canonical repository truth. - -## Maintenance Notes - -- Update this overview when top-level repository behavior boundaries change. -- Update leaf truth docs when behavior changes within their owned surface. -- Update `docs/architecture/flows/**` when relevant runtime branches, sequences, or failure paths change. -- Relevant verification includes `npm run validate` for behavior changes. -- Relevant verification includes `truthmark check --json` for repository-truth documentation changes. - -## Source References - -- ../../routes/areas/repository.md -- ../../../architecture/repository-structure.md -- ../../../architecture/flows/project-initialization.md -- ../../../architecture/flows/role-run-lifecycle.md -- ../../../architecture/flows/workflow-prompt-rendering.md -- ../../../architecture/flows/validation-and-repository-truth.md -- ../../../../package.json -- ../../../../src/cli.ts -- ../../../../src/projects.ts -- ../../../../src/runner.ts -- ../../../../src/validation.ts diff --git a/docs/truthmark/product/README.md b/docs/truthmark/product/README.md index 4c504c8..cc03bdb 100644 --- a/docs/truthmark/product/README.md +++ b/docs/truthmark/product/README.md @@ -1,20 +1,14 @@ --- status: active doc_type: index -last_reviewed: 2026-06-25 +last_reviewed: 2026-06-29 --- -# Truth Docs +# Product Truth Docs -This directory is an index for current truth docs organized by the configured Truthmark hierarchy. +This directory is intentionally empty of product-specific leaf docs after the stale-doc purge. -Product truth owns capability promises, boundaries, decisions, and acceptance criteria. Product lane docs state what must be true, why it matters, and what success means. - -README.md files are indexes, not Truth Sync targets. Keep product truth in bounded capability docs. - -## Product Capability Docs - -- [Codex Game Studio CLI](codex-game-studio-cli.md) +Use the root `README.md`, `AGENTS.md`, tracked Codex surfaces, and tests as the primary product truth until a bounded Truthmark workflow explicitly creates a new product leaf doc. ## Source References diff --git a/docs/truthmark/product/codex-game-studio-cli.md b/docs/truthmark/product/codex-game-studio-cli.md deleted file mode 100644 index 229736c..0000000 --- a/docs/truthmark/product/codex-game-studio-cli.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -status: active -truth_kind: product-capability -last_reviewed: 2026-06-27 ---- - -# Codex Game Studio CLI - -## Capability Promise - -Codex Game Studio provides a local-first TypeScript CLI for Codex-assisted game development inside a repository. - -The CLI must let developers scaffold projects, render bounded Codex-native prompts, run selected studio roles and workflows, and record reviewable project state. - -It must also validate tracked template surfaces and project state. - -It must not require a hosted service, daemon, hidden memory layer, or heavyweight studio process. - -## Users And Value - -The primary users are developers who want Codex help for game creation while keeping files and evidence visible in the repository. - -The product protects lightweight prototype work by keeping studio depth optional. It also supports structured game-studio workflows when a project needs them. - -## Capability Scope - -This capability includes the user-visible Codex Game Studio package and CLI. - -It covers project initialization, role/workflow prompt rendering, direct Codex execution, task state, approval/write-policy primitives, and engine reference packaging. - -It also covers template files, project-state files, and validation. - -This capability excludes game-engine functionality and hosted orchestration. It includes explicit local task orchestration when state, approvals, selected context, locks, runs, and failures are reviewable in `.codex/**`. - -It also excludes background autonomous control, CI/release enforcement, hidden checkpoint/memory systems, and mandatory studio ceremony for small prototypes. - -Truthmark is repository workflow tooling for this checkout. Codex Game Studio must not present Truthmark mechanics as game-studio product features. - -## Current Product Behavior - -Codex Game Studio exposes a checked-in source checkout wrapper at `./codex-game-studio` for initialization, management, template listing, validation, context-manifest refresh, and Codex-oriented role execution. - -The source checkout wrapper runs built TypeScript output from `dist/cli.js` after `npm install && npm run build`. - -Contributor npm scripts remain available for rebuilding TypeScript output and validating package behavior. - -Template repositories use `AGENTS.md`, `.codex/**`, and `.agents/skills/**` surfaces instead of legacy `CODEX.md` contracts. - -Direct Codex execution through `codex-game-studio run ` is the default runtime path. - -`--dry-run` and `--print-prompt` remain inspection-only paths. - -The current repository includes metadata-validated engine reference material for Godot, Unity, and Unreal. - -It also includes context-manifest generation, project task state, approval-store behavior, role/workflow registries, and behavioral-evaluation scenarios. - -It includes project-local customization packs and validation coverage for package assets, template surfaces, and project state. - -Built-in role prompts use bounded structured contracts. - -These contracts cover responsibilities, expected inputs, output formats, quality gates, collaboration notes, and stop conditions. - -Built-in role prompts do not clone broad external agent bodies. - -Project-local customization uses `.codex/studio/config.json` as an extend-only overlay for `custom-*` roles, workflows, and templates. - -Customization uses path-safe validation and generic workflow rendering. It does not replace built-in registries. - -Engine reference depth is packaged as active-engine version, best-practice, deprecated API, breaking-change, module, and plugin files. - -Engine reference files are selected by role/task relevance instead of being loaded wholesale. - -The workflow catalog is a curated prompt-only game-development surface. - -It covers onboarding, discovery, design, architecture, implementation planning, QA, testing, release, hotfix, localization, accessibility, and team coordination. - -The workflow catalog is not a hidden lifecycle controller. - -The production template pack covers design, architecture, art, audio, UX, accessibility, QA, release, production risk, economy, difficulty, player journey, and pitch artifacts. - -Production templates are package-shipped assets selected by relevance. - -## Acceptance Criteria - -- Developers can initialize and manage project scaffolds through the source checkout wrapper without npm installation. -- Published or linked packages expose the same CLI as the `codex-game-studio` package bin. -- Template and project-state files remain reviewable in the repository. -- Role and workflow execution stays Codex-native by default. -- Role and workflow execution does not require a hosted service, daemon, or alternate agent runtime. -- Prompt and context materialization selects relevant roles, workflows, templates, engine references, and customization entries. -- Prompt and context materialization does not load every available agent or template for a single task. -- Mutating runtime behavior is visible and policy-gated. -- Dry-run and print-prompt paths do not mutate project state. -- Template contracts use `AGENTS.md`, `.codex/**`, and `.agents/skills/**`. -- Stale generated-project compatibility surfaces are not reintroduced without an explicit boundary change. -- Validation commands and tests cover public CLI/package behavior, template surfaces, project state, engine references, and future-only surfaces. - -## Product Decisions - -- 2026-06-13: Codex Game Studio is a local-first Codex-native CLI/package for game-development repository workflows. -- 2026-06-13: Codex Game Studio is not a hosted studio service, daemon, general-purpose orchestrator, or game engine. -- 2026-06-25: Explicit local task orchestration is inside the product boundary when it remains Codex-native, file-backed, bounded by selected context, policy-gated, and validated. -- 2026-06-26: Foreground task orchestration is exposed through `task orchestrate` with bounded concurrency, transient `.codex/locks/`, workflow task recipes, and no hosted/background/unbounded behavior. -- 2026-06-28: The product name is Codex Game Studio and the package name is `codex-game-studio`. -- 2026-06-28: The user-facing source checkout path is clone plus `./codex-game-studio`; npm install is contributor setup, not project-use setup. -- 2026-06-13: Studio depth is optional and mode-controlled. -- 2026-06-13: Lifecycle stage must remain separate from process strictness. -- 2026-06-29: Template instruction contracts use tracked `AGENTS.md`, `.codex/agents`, `.codex/workflows`, and `.agents/skills` files. -- 2026-06-29: Template instruction contracts do not use `CODEX.md`, `.codex/prompts/**` mirrors, or legacy compatibility shims. -- 2026-06-26: Planner/next, telemetry, hard ownership enforcement, hosted/background orchestration, unbounded parallelism, and similar surfaces remain out of scope unless a later product-boundary decision, implementation, tests, and truth docs bring them in. -- 2026-06-13: Truthmark-backed docs guard repository truth in this checkout. -- 2026-06-13: Truthmark workflow mechanics are not Codex Game Studio product features. -- 2026-06-17: Project-local customization is an extend-only, file-backed overlay for `custom-*` roles, workflows, and templates. -- 2026-06-17: Project-local customization must remain Codex-native, reviewable, path-safe, and non-hosted. - -## Engineering Realization Links - -- docs/truthmark/engineering/projects/project-scaffolding.md -- docs/truthmark/engineering/codex/roles-and-workflows.md -- docs/truthmark/engineering/codex/runtime-and-tasks.md -- docs/truthmark/engineering/codex/approval-stores.md -- docs/truthmark/engineering/contracts/cli-and-validation.md - -## Non-Goals - -- Game-engine implementation or replacement of Godot, Unity, Unreal, or their native toolchains. -- Hosted accounts, server-side orchestration, daemons, schedulers, or hidden long-running workflow controllers. -- General-purpose task management, PR approval, CI enforcement, or release governance unrelated to the game-studio CLI boundary. -- Hidden long-term memory, checkpoint storage, telemetry, or analytics platforms outside reviewable project files or deterministic CLI output. -- Mandatory heavyweight studio-process adoption for prototype or solo-game work. -- First-class non-Codex runtime replacements unless a future product-boundary update changes that direction. - -## Source References - -- ../../../README.md -- ../../../AGENTS.md -- ../../architecture/product-boundary.md -- ../routes/areas/repository.md -- ../engineering/projects/project-scaffolding.md -- ../engineering/codex/roles-and-workflows.md -- ../engineering/codex/runtime-and-tasks.md -- ../engineering/codex/approval-stores.md -- ../engineering/contracts/cli-and-validation.md -- ../../../src/cli.ts -- ../../../src/projects.ts -- ../../../src/roles.ts -- ../../../src/workflows.ts -- ../../../src/customization.ts -- ../../../src/runner.ts -- ../../../src/validation.ts -- ../../../tests/functionality-gap-pass.test.ts -- ../../../tests/project-workflow.test.ts -- ../../../tests/runner.test.ts -- ../../../tests/validation.test.ts diff --git a/docs/truthmark/routes/areas.md b/docs/truthmark/routes/areas.md index 2ed97f2..0550562 100644 --- a/docs/truthmark/routes/areas.md +++ b/docs/truthmark/routes/areas.md @@ -1,34 +1,38 @@ --- status: active doc_type: route-index -last_reviewed: 2026-06-25 +last_reviewed: 2026-06-29 --- # Truthmark Areas +The route index is intentionally small after the stale-doc purge. + ## Repository Area files: + - docs/truthmark/routes/areas/repository.md Code surface: + +- AGENTS.md +- README.md +- docs/** - src/** - tests/** +- scripts/** +- templates/** - engine_configs/** - engine_reference/** -- templates/** -- scripts/** - references/** - package.json - package-lock.json -- docs/architecture/** -- docs/ai/** -- README.md -- AGENTS.md Update truth when: -- repository CLI behavior, Codex prompt/workflow behavior, generated project layout, validation, packaging, or task execution changes -- code or tests move between bounded behavior owners + +- repository instructions, CLI behavior, validation, package assets, or remaining docs change +- a future Truthmark workflow creates a narrower bounded area ## Source References diff --git a/docs/truthmark/routes/areas/repository.md b/docs/truthmark/routes/areas/repository.md index ebae679..78e52ad 100644 --- a/docs/truthmark/routes/areas/repository.md +++ b/docs/truthmark/routes/areas/repository.md @@ -1,216 +1,45 @@ --- status: active -doc_type: area-route -last_reviewed: 2026-06-25 +doc_type: routing +last_reviewed: 2026-06-29 --- -# Repository Areas +# Repository Area -## Codex Game Studio Product Capability +## Repository Truth documents: + ```yaml truth_documents: - - path: docs/truthmark/product/codex-game-studio-cli.md - lane: product - kind: product-capability - realized_by: - - docs/truthmark/engineering/projects/project-scaffolding.md - - docs/truthmark/engineering/codex/roles-and-workflows.md - - docs/truthmark/engineering/codex/runtime-and-tasks.md - - docs/truthmark/engineering/codex/approval-stores.md - - docs/truthmark/engineering/contracts/cli-and-validation.md -``` - -Code surface: -- docs/architecture/product-boundary.md -- docs/ai/repo-rules.md -- src/cli.ts -- src/projects.ts -- src/roles.ts -- src/workflows.ts -- src/runner.ts -- src/customization.ts -- src/validation.ts -- engine_reference/** -- templates/** -- tests/functionality-gap-pass.test.ts -- tests/project-workflow.test.ts -- tests/runner.test.ts -- tests/validation.test.ts - -Update truth when: -- Codex Game Studio's mission, user-visible CLI/package capability, Codex-native product boundary, generated-project contract, product non-goals, or acceptance criteria change -- user-facing behavior crosses from optional/local repository workflow support into hosted orchestration, hidden memory, CI/release governance, or non-Codex runtime replacement - -## Project Scaffolding - -Truth documents: -```yaml -truth_documents: - - path: docs/truthmark/engineering/projects/project-scaffolding.md - lane: engineering - kind: engineering-behavior - realizes: - - docs/truthmark/product/codex-game-studio-cli.md -``` - -Code surface: -- src/projects.ts -- src/config.ts -- src/engines.ts -- src/agents.ts -- src/skills.ts -- src/context-manifest.ts -- src/engine-reference.ts -- src/generated-surfaces.ts -- src/customization.ts -- src/paths.ts -- engine_configs/** -- engine_reference/** -- tests/project-workflow.test.ts -- tests/template-repository-surfaces.test.ts -- tests/engine-system.test.ts -- tests/codex-context-files.test.ts - -Update truth when: -- project initialization, generated project state, engine folder creation, engine reference materialization, role prompt materialization, or status/resume/freeze behavior changes -- template `AGENTS.md`, custom-agent template files, workflow template files, repository skills, or base prompt package ownership changes - -## Codex Role And Workflow Surfaces - -Truth documents: -```yaml -truth_documents: - - path: docs/truthmark/engineering/codex/roles-and-workflows.md - lane: engineering - kind: engineering-behavior - realizes: - - docs/truthmark/product/codex-game-studio-cli.md -``` - -Code surface: -- src/roles.ts -- src/codex-session.ts -- src/codex-prompts.ts -- src/behavioral-evaluation.ts -- src/customization.ts -- src/prompt-context.ts -- src/prompt-surface-metadata.ts -- src/workflows.ts -- src/workflow-catalog.ts -- src/ccgs-parity.ts -- scripts/audit-ccgs-surfaces.ts -- scripts/audit-prompt-surfaces.ts -- src/engine-reference.ts -- src/templates.ts -- src/generated-surfaces.ts -- references/ccgs-surface-parity-matrix.* -- references/prompt-surface-uplift-matrix.* -- references/prompt-uplift-eval-protocol.md -- templates/** -- tests/roles.test.ts -- tests/codex-session.test.ts -- tests/codex-prompts.test.ts -- tests/ccgs-parity-audit.test.ts -- tests/workflow-catalog.test.ts -- tests/functionality-gap-pass.test.ts -- tests/template-repository-surfaces.test.ts -- tests/prompt-surface-audit.test.ts -- tests/prompt-surface-metadata.test.ts -- tests/prompt-surface-validation.test.ts - -Update truth when: -- studio role IDs, custom role IDs, role contracts, workflow registry entries, or prompt rendering change -- engine reference prompt selection, context strategies, or template selection rules change -- Codex-native workflow shortcuts or generated workflow prompt contents change - -## Runtime And Task Execution - -Truth documents: -```yaml -truth_documents: - - path: docs/truthmark/engineering/codex/runtime-and-tasks.md - lane: engineering + - path: docs/truthmark/engineering/repository/bootstrap-routing.md kind: engineering-workflow - realizes: - - docs/truthmark/product/codex-game-studio-cli.md -``` - -Code surface: -- src/runner.ts -- src/studio-policy.ts -- src/context.ts -- src/customization.ts -- src/context-manifest.ts -- src/prompt-context.ts -- src/tasks.ts -- src/orchestrator.ts -- src/orchestrator-locks.ts -- src/workflow-recipes.ts -- src/ccgs-adaptation.ts -- src/codex-runtime.ts -- src/verification.ts -- tests/runner.test.ts -- tests/studio-policy.test.ts -- tests/tasks.test.ts -- tests/orchestrator.test.ts -- tests/workflow-recipes.test.ts -- tests/ccgs-adaptation.test.ts -- tests/verification.test.ts -- tests/codex-runtime.test.ts - -Update truth when: -- Codex execution, dry-run or print-prompt mutation rules, review/fix lifecycle behavior, task-store persistence, or verification timeout behavior changes -- task status transitions or Codex sandbox policies change - -## Approval Stores - -Truth documents: -```yaml -truth_documents: - - path: docs/truthmark/engineering/codex/approval-stores.md lane: engineering - kind: engineering-behavior - realizes: - - docs/truthmark/product/codex-game-studio-cli.md ``` Code surface: -- src/approvals.ts -- tests/approval-gates.test.ts + +- AGENTS.md +- README.md +- docs/\*\* +- src/\*\* +- tests/\*\* +- scripts/\*\* +- templates/\*\* +- engine_configs/\*\* +- engine_reference/\*\* +- references/\*\* +- package.json +- package-lock.json Update truth when: -- approval store schema, canonical objective hashing, scope normalization, approval matching, expiry, revocation, or approval-store helper behavior changes -## CLI And Validation Contracts - -Truth documents: -```yaml -truth_documents: - - path: docs/truthmark/engineering/contracts/cli-and-validation.md - lane: engineering - kind: engineering-contract - realizes: - - docs/truthmark/product/codex-game-studio-cli.md -``` - -Code surface: -- src/cli.ts -- src/validation.ts -- src/customization.ts -- src/context-manifest.ts -- src/engine-reference.ts -- src/generated-surfaces.ts -- tests/validation.test.ts -- tests/functionality-gap-pass.test.ts -- tests/codex-context-files.test.ts - -Update truth when: -- public CLI commands, package scripts/bin/files, validation check IDs, or documentation claims change -- project-local customization checks, engine reference package checks, or package dependency contracts change -- future-only surfaces become exposed or are intentionally kept hidden +- repository instructions or product boundaries change +- CLI, validation, task, role, workflow, template, engine-reference, or package behavior changes +- a future Truthmark workflow creates a narrower bounded owner ## Source References +- ../areas.md - ../../../../.truthmark/config.yml +- ../../engineering/repository/bootstrap-routing.md diff --git a/docs/user-guide.md b/docs/user-guide.md index 6c6a043..0eb9549 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -177,8 +177,6 @@ Use `--dry-run` or `--print-prompt` when you only need to inspect the prompt pac Inspect the relevant tracked template surface or project-state file before trusting the output. Project validation is intentionally strict about missing template files, malformed context metadata, and malformed project state. -See [Workflow Validation](workflow-validation.md) for the detailed validation contract. - ## Codex prompt model routing Prompt surfaces declare exact Codex model policy in tracked template files. Complex design, architecture, production, and release-gate surfaces use `gpt-5.5`; moderate implementation, QA, docs, bugfix, and bounded workflow surfaces use `gpt-5.4`; simple help, status, classification, checklist, and lookup surfaces use `gpt-5.4-mini`. Runtime dry-runs and run metadata expose the selected model and reasoning effort, and Codex execution receives the exact selected model instead of a generic tier name. diff --git a/docs/workflow-validation.md b/docs/workflow-validation.md deleted file mode 100644 index c8d4f5c..0000000 --- a/docs/workflow-validation.md +++ /dev/null @@ -1,26 +0,0 @@ -# Workflow Validation - -Validation exits nonzero when any check fails. - -Repo validation checks package scripts, build output, package assets, engine configs, expanded role rendering, canonical workflow rendering, prompt-surface discovery metadata, deterministic behavioral-evaluation scenarios, templates, package packing, installed-bin asset loading, future-only CLI surfaces, and Codex CLI readiness. Tests also cover explicit task orchestration, workflow task recipes, and curated CCGS adaptation registry consistency. - -Project validation checks `.codex/studio.json` full `roles`, mode-specific `activeRoles`, registry-derived `workflows`, `.codex/studio/config.json` customization packs, tracked `AGENTS.md`, `.codex/agents/*.toml`, `.codex/workflows/*.md`, `.agents/skills/*/SKILL.md`, engine source files, starter docs, timeline sections, forbidden legacy artifacts, and read-only `status`/`resume` behavior. - -CLI surface checks: - -```bash -./codex-game-studio run --help | grep -- "--dry-run" -! ./codex-game-studio --help | grep -E " next|telemetry" -``` - -Workflow shortcut commands such as `market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, and `handoff` render prompts only. They do not launch Codex or create run records. `workflow create-tasks ` is the explicit path for turning supported workflow recipes into `.codex/tasks.json` tasks; it still does not launch Codex. - -Behavioral evaluation scenarios are local deterministic validation subchecks. They render built-in role and workflow prompts, assert required prompt obligations, selected context categories, relevant templates, output-contract coverage, and forbidden future-only drift. They do not call hosted evaluators, telemetry, hidden memory, or LLM judges. - -Project-local customization uses `.codex/studio/config.json` as an extend-only overlay. Custom role, workflow, and template IDs must use `custom-*`, must not override built-ins, and all referenced prompt/context/template paths must remain inside the project root. - -No generated `CODEX.md`, `.gamestudio/runs`, or `project_orchestrator.md` is required or produced. - -## Codex prompt model routing - -Prompt surfaces declare exact Codex model policy in tracked template files. Complex design, architecture, production, and release-gate surfaces use `gpt-5.5`; moderate implementation, QA, docs, bugfix, and bounded workflow surfaces use `gpt-5.4`; simple help, status, classification, checklist, and lookup surfaces use `gpt-5.4-mini`. Runtime dry-runs and run metadata expose the selected model and reasoning effort, and Codex execution receives the exact selected model instead of a generic tier name.