codex-game-studio/docs/truthmark-portal/assets/search.json

[
  {
    "url": "index.html",
    "title": "Portal Overview",
    "summary": "Entry point and search.",
    "sources": [
      ".truthmark/config.yml",
      "docs/architecture/repository-structure.md",
      "docs/architecture/flows/README.md",
      "docs/architecture/flows/project-initialization.md",
      "docs/architecture/flows/role-run-lifecycle.md",
      "docs/architecture/flows/workflow-prompt-rendering.md",
      "docs/architecture/flows/validation-and-repository-truth.md",
      "docs/truthmark/areas.md",
      "docs/truthmark/areas/repository.md",
      "docs/truth/README.md",
      "docs/truth/repository/README.md",
      "docs/truth/repository/overview.md",
      "docs/truth/projects/project-scaffolding.md",
      "docs/truth/codex/roles-and-workflows.md",
      "docs/truth/codex/runtime-and-tasks.md",
      "docs/truth/contracts/cli-and-validation.md",
      "docs/standards/default-principles.md",
      "docs/standards/documentation-governance.md"
    ],
    "text": "version: 1 platforms: - codex - opencode - github-copilot docs: layout: hierarchical roots: ai: docs/ai standards: docs/standards architecture: docs/architecture truth: docs/truth routing: root_index: docs/truthmark/areas.md area_files_root: docs/truthmark/areas default_area: repository max_delegation_depth: 1 authority: - docs/truthmark/areas.md - docs/truthmark/areas/**/*.md - docs/ai/**/*.md - docs/standards/**/*.md - docs/architecture/**/*.md - docs/truth/**/*.md instruction_targets: - AGENTS.md truthmark-portal: enabled: true output: docs/truthmark-portal template: default frontmatter: required: [] recommended: - status - doc_type - last_reviewed - source_of_truth ignore: - node_modules/** - vendor/** - dist/** - build/** # Repository Structure ## Purpose Open GameStudio 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. Bounded behavior details live in leaf docs under `docs/truth/**`; 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 Vitest 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/areas/repository.md`. Update `docs/architecture/flows/**` when an architecturally relevant runtime scenario, branch, or failure path changes. # Architecture Flow Guides ## Purpose These Architecture Flow Guides document Open GameStudio's important runtime scenarios, branching logic, failure paths, and code/truth-doc traceability. They are Markdown docs-as-code runtime views: readable in GitHub/VS Code, reviewable in pull requests, and detailed enough to guide humans and agents through the system. ## 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\u00e1taxis 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/truth/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-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/truth/projects/project-scaffolding.md` | | [Role Run Lifecycle](role-run-lifecycle.md) | `run <role>` renders, executes, verifies, reviews, and optionally fixes a Codex role run. | `docs/truth/codex/runtime-and-tasks.md`, `docs/truth/codex/roles-and-workflows.md` | | [Workflow Prompt Rendering](workflow-prompt-rendering.md) | Workflow shortcut commands render deterministic prompts without executing Codex. | `docs/truth/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/truth/contracts/cli-and-validation.md`, `docs/truth/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. # Project Initialization Flow Guide ## Purpose This architecture flow guide documents the runtime scenario for `open-gamestudio init` and `open-gamestudio new`. Both commands use the same initialization path to create a deterministic Codex Game Studio project under `projects/<slug>/`. ## Scope This flow starts when a user invokes `init` or `new` with required project options. It ends when the generated project has engine markers, `.codex` state, workflow prompts, starter docs, role prompts, and project-level `AGENTS.md`. This flow does **not** execute Codex and does **not** own task lifecycle persistence after project creation. ## Boundaries Project initialization owns generated project creation and initial `.codex` state. 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 | | --- | --- | --- | | `open-gamestudio init` | Primary project initialization command. | `src/cli.ts` | | `open-gamestudio new` | Alias that delegates to the same initialization path. | `src/cli.ts` | | `initProject(...)` | Creates project config, directories, state, docs, workflows, and prompts. | `src/projects.ts` | ## Preconditions - The user supplies `--name`, `--engine`, `--mode`, and `--non-interactive`. - The selected engine is known by the engine registry. - The target `projects/<slug>/` path does not already exist. - Same-parent project slug and Unreal class-name collision checks pass. ## 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 Agents as src/agents.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 workflow prompt files and starter docs Projects->>Agents: render generated project AGENTS.md and role prompts Projects-->>CLI: project root and config CLI-->>User: Created <name> at <path> ``` ## 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 workflows, starter docs, AGENTS.md, role prompts] 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/truth/contracts/cli-and-validation.md` | | `--non-interactive` missing | Determinism guard | Stop before writing. | Required option error. | `src/cli.ts`; `docs/truth/projects/project-scaffolding.md` | | Engine is unknown | Engine registry guard | Stop before writing. | Invalid engine/lookup failure. | `src/engines.ts`; `docs/truth/projects/project-scaffolding.md` | | Target path exists | Collision guard | Stop before mutating target. | Existing project/path error. | `src/projects.ts`; `docs/truth/projects/project-scaffolding.md` | | Collision checks pass | Happy path | Write generated project surfaces. | `Created <name> at <path>`. | `src/projects.ts`; `docs/truth/projects/project-scaffolding.md` | ## Generated Outputs The successful flow creates or writes: - `projects/<slug>/` - `.codex/studio.json` - `.codex/runs/` - `.codex/workflows/*.md` - starter design/production/market documents - engine-specific marker files and source folders - project-level `AGENTS.md` - role prompt files for the canonical studio role roster 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 | `projects/<slug>/` already exists. | Project directory and slug derivation in `src/projects.ts`. | | Generated file missing in validation | Scaffolding contract drift. | `src/projects.ts`, `src/agents.ts`, `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/**` | | Generated project instruction surface | `src/agents.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. - Generated project instructions use Codex-native `AGENTS.md`; this flow does not introduce `CODEX.md` as a primary project instruction contract. ## Rationale A bounded initialization flow gives users and agents a stable project scaffold without implying that scaffolding also executes Codex, manages planner state, or owns later runtime task transitions. ## Truth Sources - `docs/truth/projects/project-scaffolding.md` - `docs/truth/repository/overview.md` - `docs/truth/contracts/cli-and-validation.md` - `docs/truthmark/areas/repository.md` ## Verification For behavior changes in this flow, run the relevant project workflow, agent/template, engine-system, and validation tests. For repository-wide readiness claims, run: ```bash npm run validate npx truthmark check --json ``` # Role Run Lifecycle Flow Guide ## Purpose This architecture flow guide documents the runtime scenario for `open-gamestudio run <role>`. 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 <role> ... --project <path>`. 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 | | --- | --- | --- | | `open-gamestudio run <role>` | 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 <path>` 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 `<role>` | 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 <role> objective --project <path> 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/truth/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, or parallel orchestration behavior. ## Truth Sources - `docs/truth/codex/runtime-and-tasks.md` - `docs/truth/codex/roles-and-workflows.md` - `docs/truth/contracts/cli-and-validation.md` - `docs/truthmark/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 ``` # 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 <path>`. 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 <path>` 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 <path> 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, or parallel orchestration behavior. ## 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/truth/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/truth/codex/roles-and-workflows.md` - `docs/truth/contracts/cli-and-validation.md` - `docs/truth/repository/overview.md` - `docs/truthmark/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 ``` # Validation And Repository Truth Flow Guide ## Purpose This architecture flow guide documents the validation path around Open GameStudio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates. Validation is an Open GameStudio CLI/package behavior. Truthmark is an injected repository-truth workflow/tooling layer for documentation authority, routing, and agent workflow surfaces; it is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior. ## Scope This guide covers two related but separate flows: 1. `open-gamestudio 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 Open GameStudio package behavior implemented by the CLI and validation modules. Truthmark checks are an injected repository-truth workflow/tooling layer for documentation authority and generated agent surfaces, not an Open GameStudio runtime feature. ## Entry Points | Entry point | Role in flow | Code / owner | | --- | --- | --- | | `open-gamestudio 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/areas.md`, `docs/truthmark/areas/repository.md` | | Truth docs | Canonical bounded behavior/reference docs. | `docs/truth/**` | ## 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 <path>` 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/areas*.md` | for Truthmark checks | Map code/doc surfaces to bounded truth docs. | | Truth docs | `docs/truth/**` | 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 / open-gamestudio 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. | Open GameStudio repo | | Generated project behavior changed | Project validation branch | Validate generated-project contracts. | Missing/invalid generated surface diagnostic. | `src/validation.ts` and scaffold owners | | Public CLI claim changed | CLI contract branch | Update contract truth doc and validation/readme claims together. | Validation or doc drift if missed. | `docs/truth/contracts/cli-and-validation.md` | | Behavior claim changed | Truth sync branch | Update owning bounded truth doc. | Truthmark may flag stale/unmapped surfaces. | Truthmark docs workflow | | 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/areas.md`, `docs/truthmark/areas/repository.md`. | | Truth doc and flow guide diverge | Flow guide was updated without updating canonical truth or vice versa. | Owning `docs/truth/**` file and affected `docs/architecture/flows/**` file. | | Portal output stale | Generated non-canonical site not refreshed after Markdown changes. | `docs/truthmark-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/truth/contracts/cli-and-validation.md` | | Truthmark config and generated workflow surfaces | `.truthmark/config.yml`, generated agent files | | Truth routing | `docs/truthmark/areas.md`, `docs/truthmark/areas/repository.md` | | Bounded canonical behavior docs | `docs/truth/**` | | Cross-cutting runtime scenario explanations | `docs/architecture/flows/**` | | Generated presentation output | `docs/truthmark-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 Open GameStudio 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/truth/contracts/cli-and-validation.md` - `docs/truth/repository/overview.md` - `docs/truthmark/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. # Truthmark Areas ## Repository Area files: - docs/truthmark/areas/repository.md Code surface: - src/** - tests/** - engine_configs/** - templates/** - package.json - package-lock.json - 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 Areas ## Project Scaffolding Truth documents: ```yaml truth_documents: - path: docs/truth/projects/project-scaffolding.md kind: behavior ``` Code surface: - src/projects.ts - src/config.ts - src/engines.ts - src/agents.ts - src/paths.ts - engine_configs/** - tests/project-workflow.test.ts - tests/agents-templates.test.ts - tests/engine-system.test.ts - tests/codex-context-files.test.ts Update truth when: - project initialization, generated project state, engine folder creation, role prompt materialization, or status/resume/freeze behavior changes - generated project AGENTS.md or base prompt package ownership changes ## Codex Role And Workflow Surfaces Truth documents: ```yaml truth_documents: - path: docs/truth/codex/roles-and-workflows.md kind: behavior ``` Code surface: - src/roles.ts - src/codex-session.ts - src/codex-prompts.ts - src/workflows.ts - src/templates.ts - templates/** - tests/roles.test.ts - tests/codex-session.test.ts - tests/codex-prompts.test.ts - tests/functionality-gap-pass.test.ts Update truth when: - studio role IDs, role contracts, workflow registry entries, prompt rendering, 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/truth/codex/runtime-and-tasks.md kind: workflow ``` Code surface: - src/runner.ts - src/tasks.ts - src/codex-runtime.ts - src/verification.ts - tests/runner.test.ts - tests/tasks.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 ## CLI And Validation Contracts Truth documents: ```yaml truth_documents: - path: docs/truth/contracts/cli-and-validation.md kind: contract ``` Code surface: - src/cli.ts - src/validation.ts - tests/validation.test.ts - tests/functionality-gap-pass.test.ts Update truth when: - public CLI commands, package scripts/bin/files, validation check IDs, documentation claims, or package dependency contracts change - future-only surfaces become exposed or are intentionally kept hidden # Truth Docs This directory is an index for current truth docs organized by the configured Truthmark hierarchy. README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under `<domain>/<behavior>.md`. # Repository Truth Docs This directory is reserved for repository-level truth indexes. 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) # Repository Overview ## Purpose Open GameStudio exists as a Codex-native workflow layer for game-development projects. The repository packages a TypeScript CLI that scaffolds game projects, renders role/workflow prompts for Codex, executes bounded Codex run lifecycles, and validates both repository and generated-project contracts. ## Scope This bounded leaf truth doc summarizes the repository-level behavior surface. More specific behavior is owned by the project scaffolding, Codex role/workflow, runtime/task execution, and CLI/validation truth documents listed in `docs/truthmark/areas/repository.md`. ## Current Behavior - The package exposes the `open-gamestudio` CLI from `dist/cli.js`. - Initialization commands create deterministic generated game project structure under `projects/<slug>`. - Generated projects contain `.codex/studio.json`, role prompt files, workflow markdown, starter design/production/market documents, engine-specific project markers, and a Codex-native `AGENTS.md` instruction surface. - Role run commands render deterministic Codex prompts and, unless in inspection mode, execute Codex with optional verification, review, and bounded fix passes. - Workflow shortcut commands are render-only prompt surfaces and do not imply hidden planner, parallel orchestration, telemetry, or ownership enforcement behavior. - Validation checks package metadata, source and template presence, role/workflow rendering, future-surface guardrails, build output, and package install smoke behavior. ## Core Rules - Repository behavior is grouped by behavior ownership rather than by mechanically mirroring every source file. - Generated project instruction contracts use Codex-native `AGENTS.md`; the repository does not introduce `CODEX.md` as a primary instruction contract. - Runtime execution is explicit: dry-run and print-prompt modes are inspection paths, while non-dry runs write prompt/run metadata before executing Codex. - Truthmark is an injected repository-truth workflow/tooling layer for agent surfaces and documentation routing. It is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior. ## Flows And States Architecture runtime walkthroughs live under `docs/architecture/flows/**`; they explain branching logic and failure paths while linking back to the bounded truth docs that own the behavior. - Project initialization flow: parse CLI input, normalize engine/config, guard against project-name collisions, create engine/project folders, write `.codex` state and workflow files, write starter docs, and materialize role prompts/instructions. See `docs/architecture/flows/project-initialization.md`. - Role run flow: validate role/project/task, render prompt and context list, optionally return inspection output, write run cache, execute Codex, run verification/review, optionally run bounded fix passes, and report `done` or `blocked`. See `docs/architecture/flows/role-run-lifecycle.md`. - Workflow prompt rendering flow: validate project context, resolve the workflow alias/ID, render deterministic prompt text, and return without launching Codex or writing run state. See `docs/architecture/flows/workflow-prompt-rendering.md`. - Repository validation flow: build the package, run validation checks, and fail if any package, source, prompt, workflow, template, or future-surface contract is broken. See `docs/architecture/flows/validation-and-repository-truth.md`. ## Contracts - Public CLI command contracts are owned by `docs/truth/contracts/cli-and-validation.md`. - Role/workflow prompt contracts are owned by `docs/truth/codex/roles-and-workflows.md`. - Runtime/task lifecycle contracts are owned by `docs/truth/codex/runtime-and-tasks.md`. - Project scaffolding contracts are owned by `docs/truth/projects/project-scaffolding.md`. ## Product Decisions - Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file. - Decision (2026-05-30): Treat Truthmark Portal output as generated non-canonical presentation; Markdown truth docs remain canonical. - Decision (2026-05-30): Use Markdown Architecture Flow Guides as runtime-view documentation for important cross-cutting flow scenarios; bounded Truthmark truth docs remain the behavior authority. ## Rationale The repository combines scaffolding, prompt generation, runtime execution, and validation in one package. Keeping those surfaces bounded makes the architecture easier to reason about and prevents generated agent workflow scaffolding from being mistaken for user-facing Open GameStudio product behavior. ## Non-Goals - This doc does not replace the more specific bounded truth docs for project scaffolding, Codex role/workflow surfaces, runtime/task execution, or CLI/validation contracts. - This repository does not expose hidden parallel orchestration, telemetry, planner/next queues, or 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 the leaf truth docs named in `docs/truthmark/areas/repository.md` when behavior changes within their owned surface. - Update `docs/architecture/flows/**` when an architecturally relevant runtime branch, sequence, or failure path changes. - Relevant verification includes `npm run validate` for behavior changes and `npx truthmark check --json` for repository-truth documentation changes. # Project Scaffolding ## Purpose Project scaffolding turns a non-interactive CLI request into a ready Codex Game Studio project with deterministic state, engine markers, role prompts, workflow prompts, and starter production/design artifacts. ## Scope This bounded leaf truth doc owns project initialization, generated project state, engine-specific file/folder creation, generated project `AGENTS.md` and role prompts, and read-only project status/resume behavior. It does not own Codex run execution, task lifecycle persistence, or repository-level CLI validation. This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md. ## Current Behavior - `init` and `new` share the same initialization path and require `--name`, `--engine`, `--mode`, and `--non-interactive`. - Initialization writes projects under `projects/<slug>/`, rejects an existing target path, and checks same-parent slug and Unreal class-name collisions before writing. - Project state is written to `.codex/studio.json` with schema version 1, product `codex-game-studio`, the full canonical role roster, mode-active roles, and all workflow IDs. - Engine scaffolding uses the configured engine registry to create Godot, Unity, or Unreal marker files and source folders. - Initialization writes `.codex/workflows/*.md`, starter design/production/market docs, project `AGENTS.md`, and one prompt per studio role. - `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. - Generated projects live under `projects/<slug>/` by default. - `CODEX.md`, `project_orchestrator.md`, and `.gamestudio/runs` are forbidden generated project surfaces. - Generated project prompts must include the project name, role display name, project summary, engine context, role instructions, expected outputs, review checklist, and handoff sections. ## Flows And States - Initialization flow: parse options, normalize engine, derive slug, reject collisions, create engine files, create `.codex/runs`, write studio state, write workflow files, write starter docs, and materialize role prompts. - Project status states are `active`, `frozen`, and `inactive`; `freeze` is the only current CLI path that mutates status. ## Contracts - `open-gamestudio init --name <name> --engine <engine> --mode <mode> --non-interactive` creates a project and prints the created path. - `open-gamestudio new` is an alias for the same initialization behavior. - `open-gamestudio status --project <path>`, `resume --project <path>`, and `freeze --project <path>` operate on `.codex/studio.json`. ## Product Decisions - Decision (2026-05-28): Preserve Codex-native project state under `.codex/` and use project-level `AGENTS.md` as the generated instruction surface. - Decision (2026-05-28): Keep status/resume read-only so inspection commands cannot alter generated project state. ## Rationale A deterministic project scaffold gives Codex a stable context package without introducing a separate planner database or hidden orchestration layer. Keeping generated project instructions in `AGENTS.md` aligns with Codex-native workflows and avoids a parallel `CODEX.md` contract. ## Non-Goals - This doc does not own runtime Codex execution or task-store status transitions after project creation. - This doc does not define game engine runtime behavior beyond the initial marker files and folders created by the scaffolder. ## Maintenance Notes - Update this doc with changes to `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, `src/paths.ts`, or `engine_configs/**`. - Relevant verification includes project workflow, agent/template, engine-system, and project validation tests. # Codex Roles And Workflows ## Purpose Codex roles and workflows provide the role-specific prompt contracts, context boundaries, templates, and render-only workflow shortcuts that make Open GameStudio a Codex-native game-development layer. ## Scope This bounded leaf truth doc owns studio role IDs, role package metadata, Codex session prompt rendering, workflow registry entries, template registry behavior, and generated workflow prompt content. It does not own process execution, task persistence, package installation, or generated project initialization side effects. This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md. ## Current Behavior - The canonical studio role roster is defined by hyphenated Codex-native role IDs such as `producer`, `gameplay-programmer`, `qa-playtester`, and `studio-orchestrator`. - Each role package contains a display name, system prompt, context strategy, expected outputs, handoff wording, and a review checklist. - Codex session prompts render the role display name, role ID, phase, project root, objective, engine context, context files, expected outputs, verification command, review checklist, and completion-report instructions. - The workflow registry defines vertical-slice, bugfix, playtest, market-analysis, analytics-setup, design-spec, game-feel-tuning, art-direction, ui-ux-review, production-milestone, handoff, review, and ship-check workflow prompts. - Selected workflows include CLI aliases for render-only shortcuts, including market, analytics, design-spec, feel-review, art-direction, ui-review, milestone, and handoff. - Template selection is task- and role-sensitive; template files are read from package assets and embedded into applicable workflow prompts. ## Core Rules - Unknown role errors must point users toward Codex-native hyphenated role IDs rather than legacy agent names. - Prompt rendering must include the role display name and project/session metadata needed by Codex to operate without hidden state. - Templates that require Markdown sections must have non-empty required sections; the project config template must parse as JSON. - Workflow shortcuts render prompts; they do not imply hidden parallel orchestration or future planner behavior. ## Flows And States - Workflow prompt flow: read project engine from `.codex/studio.json`, look up the workflow registry entry, create a Codex studio session for the owning role and phase, render the standard prompt, then append any workflow template bodies. - Template selection flow: match role and task text against bounded keyword rules and return only matching template IDs. ## Contracts - Role IDs are stable strings exported from `src/roles.ts` and reused by config validation, project state, prompt generation, workflow routing, and task creation. - Workflow IDs map to `.codex/workflows/<workflow>.md` files and expected context-file lists. - Template IDs map to package template paths, role applicability, tags, and required-section validation. ## Product Decisions - Decision (2026-05-28): Use Codex-native hyphenated role IDs as the canonical user- and project-facing role contract. - Decision (2026-05-28): Keep workflow shortcuts render-only for this pass; future planner, next, telemetry, ownership enforcement, and parallel orchestration surfaces remain hidden. ## Rationale Role and workflow prompt generation is the user-facing contract that turns a generic Codex CLI into a specialized game-studio workflow. Keeping it render-only and declarative avoids overclaiming automation that is not implemented while still making the workflow packages inspectable and testable. ## Non-Goals - This doc does not own whether Codex is installed or authenticated. - This doc does not own task lifecycle mutations or verification command execution. ## Maintenance Notes - Update this doc with changes to `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, or `templates/**`. - Relevant verification includes role, Codex prompt/session, workflow, template, and functionality-gap tests. # Runtime And Task Execution ## Purpose Runtime and task execution connect prepared Codex Game Studio prompts to the Codex CLI, preserve explicit task state, and run bounded verification/review/fix loops without hidden orchestration. ## Scope This bounded leaf truth doc owns `run` preparation and execution, Codex command construction and availability checks, task-store persistence, review/fix lifecycle behavior, sandbox policy, and structured verification command execution. It does not own role prompt content, project scaffolding, or public CLI help wording except where runtime behavior depends on those options. ## Triggers - A user invokes `run <role> ... --project <path>` to render or execute a role prompt. - A user creates or runs a file-backed task through `task create` or `task run`. - A run includes structured verification, review, or bounded fix-pass options. ## Inputs - A valid project root with `.codex/studio.json`. - A studio role ID or task ID. - A non-empty task/objective. - Optional included artifacts, verification command/args, review flag, fix flag, and max fix-pass count. ## Execution Model - `prepareRun` resolves the project, reads studio state, renders a Codex prompt, computes prompt and metadata cache paths, and builds Codex execution commands. - `--print-prompt` and `--dry-run` are inspection-only paths 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. - Task runs mutate task status only for non-dry execution. ## Steps 1. Validate the requested role/task and project state. 2. Build context-file lists and render the Codex prompt. 3. For non-dry runs, write the prompt and metadata cache under `.codex/runs/`. 4. Check Codex availability before execution through the CLI path. 5. Execute the implementation prompt. 6. Run verification when configured. 7. Run review when requested and verification passes or is absent. 8. Run bounded fix passes when requested and blockers remain. 9. Report final status as `done` or `blocked`; task runs also persist final task status. ## State, Retry, And Failure Behavior - Task stores live at `.codex/tasks.json` with schema version 1 and unique `task-###` IDs. - `task create` requires a valid studio project before writing task state. - Task statuses are `ready`, `running`, `blocked`, and `done`. - Verification commands are spawned with bounded stdout/stderr capture, a default timeout, SIGTERM on timeout, and SIGKILL after the configured grace period. - Malformed review JSON, non-zero Codex execution, failed verification, or review blockers leave the lifecycle blocked unless a later bounded fix pass clears the blocker. ## Outputs - Dry-run output lists context files and the Codex command without writing 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. ## Product 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 while implementation/fix prompts retain workspace-write behavior. - Decision (2026-05-28): Require a valid project before task-store writes. ## Rationale Codex execution is intentionally explicit: users can inspect prompts without side effects, then run bounded implementation/review/fix loops with visible cache paths and verification output. Read-only review protects the review contract from accidentally becoming a second implementation pass. ## Non-Goals - This workflow does not implement hidden parallel execution, telemetry, ownership enforcement, or a planner/next queue. - This workflow does not choose role prompt content; it consumes the role and workflow surfaces owned by the Codex roles truth doc. ## Maintenance Notes - Update this doc with changes to `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, or `src/verification.ts`. - Relevant verification includes runner, task, verification, Codex runtime, and lifecycle-focused tests. # CLI And Validation Contracts ## Purpose The CLI and validation contracts define the public `open-gamestudio` command surface, package entrypoints, hard-failing validation checks, and future-surface guardrails for this repository. ## Scope This bounded leaf truth doc owns the repository CLI command contract, package scripts/bin/files expectations, validation check behavior, and documented public-surface claims. It does not own the internal details of project scaffolding, role prompt content, or Codex runtime lifecycle beyond the options exposed through the CLI. ## Contract Surface - Package name: `open-gamestudio`. - Package bin: `open-gamestudio` points to `./dist/cli.js`. - Primary scripts include `build`, `typecheck`, `test`, `validate`, `init`, `manage`, and `templates`. - Public CLI command groups include initialization/status commands, template discovery, role run execution, file-backed tasks, and render-only workflow shortcuts. - Repository validation is exposed through `open-gamestudio validate` and the `npm run validate` script. ## Inputs - CLI options and arguments parsed by Commander in `src/cli.ts`. - Repository files checked by validation, including package metadata, source files, templates, generated build output, engine configs, and optional project paths. - Project validation input when `--project <path>` is supplied. ## Outputs - CLI commands print human-readable status, prompt, task, validation, or workflow output. - Validation emits one line per check in `STATUS id: message (path)` shape and exits non-zero when any check fails. - Package smoke validation builds and exercises the packed package bin and template loading behavior. ## Errors And Diagnostics - Unknown roles fail with a message naming Codex-native hyphenated role IDs. - Missing package scripts, missing package bin/files, missing source files, unavailable Codex CLI, invalid templates, exposed future surfaces, missing build output, and package smoke failures are validation failures. - Project validation fails for invalid `.codex/studio.json`, missing generated project files, missing workflow/prompt sections, forbidden generated surfaces, or read-only command mutations. ## 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 >=20. - Packaged files must include `dist/`, `engine_configs/`, and `templates/` so the installed bin can load runtime assets. - Future-only command surfaces such as `next`, `telemetry`, `parallel`, and ownership enforcement must stay hidden until implemented intentionally. ## Versioning And Migration - Current package version is managed in `package.json` and rendered by Commander. - CLI contract changes should update README claims, validation expectations, and tests in the same change. ## Product Decisions - Decision (2026-05-28): Keep `validate` as the hard-failing parity gate before claiming repository or project readiness. - Decision (2026-05-28): Document and test that future planner/telemetry/parallel/ownership surfaces are not exposed by the CLI. ## Rationale The CLI is the stable integration boundary for humans, package installs, and generated project smoke checks. Validation makes those claims executable so prompt-surface and packaging drift fail before release or parity claims. ## Non-Goals - This contract does not document every generated prompt body; those belong to the Codex role/workflow truth doc. - This contract does not define npm audit remediation policy. ## Maintenance Notes - Update this doc with changes to `src/cli.ts`, `src/validation.ts`, package metadata, README public command claims, or validation check IDs. - Relevant verification includes `npm run validate`, CLI help smoke checks, validation tests, package dry-run/smoke checks, and future-surface guard tests. # Default Principles ## Scope This is a bootstrap standards baseline for repositories that adopt Truthmark. ## Reusable Defaults - Authority order should be explicit. - Committed repository artifacts are the durable source of truth. - Each document should have one primary responsibility. - Each class of fact should have one canonical source. - Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, generated-surface ownership, and architecturally relevant runtime views. - Do not put ordinary feature behavior in architecture docs; use architecture flow guides only for cross-cutting runtime scenarios, branching logic, failure paths, and traceability back to bounded truth docs. - Verification should be explicit, and skipped checks should state why. - Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs. - Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable. # Documentation Governance ## Core Rules - Each document should have one primary responsibility. - Each class of fact should have one canonical source. - Current implementation, reusable standards, and future proposals should be stored separately. - Generated helper output is never canonical truth. - Architecture docs describe structure, ownership, and runtime views; truth docs describe current product behavior and remain the canonical behavior reference. - Architecture flow guides may explain branching logic and failure paths, but they must trace back to the owning truth docs rather than becoming a competing source of behavior truth. ## Truthmark Implications - Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort. - Weak routing produces weak truth maintenance. - Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created."
  },
  {
    "url": "architecture.html",
    "title": "Architecture",
    "summary": "Architecture boundaries and runtime flow guides.",
    "sources": [
      "docs/architecture/repository-structure.md",
      "docs/architecture/flows/README.md",
      "docs/architecture/flows/project-initialization.md",
      "docs/architecture/flows/role-run-lifecycle.md",
      "docs/architecture/flows/workflow-prompt-rendering.md",
      "docs/architecture/flows/validation-and-repository-truth.md"
    ],
    "text": "# Repository Structure ## Purpose Open GameStudio 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. Bounded behavior details live in leaf docs under `docs/truth/**`; 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 Vitest 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/areas/repository.md`. Update `docs/architecture/flows/**` when an architecturally relevant runtime scenario, branch, or failure path changes. # Architecture Flow Guides ## Purpose These Architecture Flow Guides document Open GameStudio's important runtime scenarios, branching logic, failure paths, and code/truth-doc traceability. They are Markdown docs-as-code runtime views: readable in GitHub/VS Code, reviewable in pull requests, and detailed enough to guide humans and agents through the system. ## 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\u00e1taxis 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/truth/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-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/truth/projects/project-scaffolding.md` | | [Role Run Lifecycle](role-run-lifecycle.md) | `run <role>` renders, executes, verifies, reviews, and optionally fixes a Codex role run. | `docs/truth/codex/runtime-and-tasks.md`, `docs/truth/codex/roles-and-workflows.md` | | [Workflow Prompt Rendering](workflow-prompt-rendering.md) | Workflow shortcut commands render deterministic prompts without executing Codex. | `docs/truth/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/truth/contracts/cli-and-validation.md`, `docs/truth/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. # Project Initialization Flow Guide ## Purpose This architecture flow guide documents the runtime scenario for `open-gamestudio init` and `open-gamestudio new`. Both commands use the same initialization path to create a deterministic Codex Game Studio project under `projects/<slug>/`. ## Scope This flow starts when a user invokes `init` or `new` with required project options. It ends when the generated project has engine markers, `.codex` state, workflow prompts, starter docs, role prompts, and project-level `AGENTS.md`. This flow does **not** execute Codex and does **not** own task lifecycle persistence after project creation. ## Boundaries Project initialization owns generated project creation and initial `.codex` state. 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 | | --- | --- | --- | | `open-gamestudio init` | Primary project initialization command. | `src/cli.ts` | | `open-gamestudio new` | Alias that delegates to the same initialization path. | `src/cli.ts` | | `initProject(...)` | Creates project config, directories, state, docs, workflows, and prompts. | `src/projects.ts` | ## Preconditions - The user supplies `--name`, `--engine`, `--mode`, and `--non-interactive`. - The selected engine is known by the engine registry. - The target `projects/<slug>/` path does not already exist. - Same-parent project slug and Unreal class-name collision checks pass. ## 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 Agents as src/agents.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 workflow prompt files and starter docs Projects->>Agents: render generated project AGENTS.md and role prompts Projects-->>CLI: project root and config CLI-->>User: Created <name> at <path> ``` ## 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 workflows, starter docs, AGENTS.md, role prompts] 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/truth/contracts/cli-and-validation.md` | | `--non-interactive` missing | Determinism guard | Stop before writing. | Required option error. | `src/cli.ts`; `docs/truth/projects/project-scaffolding.md` | | Engine is unknown | Engine registry guard | Stop before writing. | Invalid engine/lookup failure. | `src/engines.ts`; `docs/truth/projects/project-scaffolding.md` | | Target path exists | Collision guard | Stop before mutating target. | Existing project/path error. | `src/projects.ts`; `docs/truth/projects/project-scaffolding.md` | | Collision checks pass | Happy path | Write generated project surfaces. | `Created <name> at <path>`. | `src/projects.ts`; `docs/truth/projects/project-scaffolding.md` | ## Generated Outputs The successful flow creates or writes: - `projects/<slug>/` - `.codex/studio.json` - `.codex/runs/` - `.codex/workflows/*.md` - starter design/production/market documents - engine-specific marker files and source folders - project-level `AGENTS.md` - role prompt files for the canonical studio role roster 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 | `projects/<slug>/` already exists. | Project directory and slug derivation in `src/projects.ts`. | | Generated file missing in validation | Scaffolding contract drift. | `src/projects.ts`, `src/agents.ts`, `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/**` | | Generated project instruction surface | `src/agents.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. - Generated project instructions use Codex-native `AGENTS.md`; this flow does not introduce `CODEX.md` as a primary project instruction contract. ## Rationale A bounded initialization flow gives users and agents a stable project scaffold without implying that scaffolding also executes Codex, manages planner state, or owns later runtime task transitions. ## Truth Sources - `docs/truth/projects/project-scaffolding.md` - `docs/truth/repository/overview.md` - `docs/truth/contracts/cli-and-validation.md` - `docs/truthmark/areas/repository.md` ## Verification For behavior changes in this flow, run the relevant project workflow, agent/template, engine-system, and validation tests. For repository-wide readiness claims, run: ```bash npm run validate npx truthmark check --json ``` # Role Run Lifecycle Flow Guide ## Purpose This architecture flow guide documents the runtime scenario for `open-gamestudio run <role>`. 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 <role> ... --project <path>`. 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 | | --- | --- | --- | | `open-gamestudio run <role>` | 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 <path>` 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 `<role>` | 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 <role> objective --project <path> 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/truth/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, or parallel orchestration behavior. ## Truth Sources - `docs/truth/codex/runtime-and-tasks.md` - `docs/truth/codex/roles-and-workflows.md` - `docs/truth/contracts/cli-and-validation.md` - `docs/truthmark/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 ``` # 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 <path>`. 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 <path>` 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 <path> 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, or parallel orchestration behavior. ## 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/truth/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/truth/codex/roles-and-workflows.md` - `docs/truth/contracts/cli-and-validation.md` - `docs/truth/repository/overview.md` - `docs/truthmark/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 ``` # Validation And Repository Truth Flow Guide ## Purpose This architecture flow guide documents the validation path around Open GameStudio behavior changes and the injected Truthmark repository-truth workflow around documentation/routing updates. Validation is an Open GameStudio CLI/package behavior. Truthmark is an injected repository-truth workflow/tooling layer for documentation authority, routing, and agent workflow surfaces; it is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior. ## Scope This guide covers two related but separate flows: 1. `open-gamestudio 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 Open GameStudio package behavior implemented by the CLI and validation modules. Truthmark checks are an injected repository-truth workflow/tooling layer for documentation authority and generated agent surfaces, not an Open GameStudio runtime feature. ## Entry Points | Entry point | Role in flow | Code / owner | | --- | --- | --- | | `open-gamestudio 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/areas.md`, `docs/truthmark/areas/repository.md` | | Truth docs | Canonical bounded behavior/reference docs. | `docs/truth/**` | ## 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 <path>` 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/areas*.md` | for Truthmark checks | Map code/doc surfaces to bounded truth docs. | | Truth docs | `docs/truth/**` | 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 / open-gamestudio 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. | Open GameStudio repo | | Generated project behavior changed | Project validation branch | Validate generated-project contracts. | Missing/invalid generated surface diagnostic. | `src/validation.ts` and scaffold owners | | Public CLI claim changed | CLI contract branch | Update contract truth doc and validation/readme claims together. | Validation or doc drift if missed. | `docs/truth/contracts/cli-and-validation.md` | | Behavior claim changed | Truth sync branch | Update owning bounded truth doc. | Truthmark may flag stale/unmapped surfaces. | Truthmark docs workflow | | 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/areas.md`, `docs/truthmark/areas/repository.md`. | | Truth doc and flow guide diverge | Flow guide was updated without updating canonical truth or vice versa. | Owning `docs/truth/**` file and affected `docs/architecture/flows/**` file. | | Portal output stale | Generated non-canonical site not refreshed after Markdown changes. | `docs/truthmark-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/truth/contracts/cli-and-validation.md` | | Truthmark config and generated workflow surfaces | `.truthmark/config.yml`, generated agent files | | Truth routing | `docs/truthmark/areas.md`, `docs/truthmark/areas/repository.md` | | Bounded canonical behavior docs | `docs/truth/**` | | Cross-cutting runtime scenario explanations | `docs/architecture/flows/**` | | Generated presentation output | `docs/truthmark-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 Open GameStudio 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/truth/contracts/cli-and-validation.md` - `docs/truth/repository/overview.md` - `docs/truthmark/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."
  },
  {
    "url": "truth.html",
    "title": "Repository Truth",
    "summary": "Truthmark routes and bounded truth docs.",
    "sources": [
      "docs/truthmark/areas.md",
      "docs/truthmark/areas/repository.md",
      "docs/truth/README.md",
      "docs/truth/repository/README.md",
      "docs/truth/repository/overview.md",
      "docs/truth/projects/project-scaffolding.md",
      "docs/truth/codex/roles-and-workflows.md",
      "docs/truth/codex/runtime-and-tasks.md",
      "docs/truth/contracts/cli-and-validation.md"
    ],
    "text": "# Truthmark Areas ## Repository Area files: - docs/truthmark/areas/repository.md Code surface: - src/** - tests/** - engine_configs/** - templates/** - package.json - package-lock.json - 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 Areas ## Project Scaffolding Truth documents: ```yaml truth_documents: - path: docs/truth/projects/project-scaffolding.md kind: behavior ``` Code surface: - src/projects.ts - src/config.ts - src/engines.ts - src/agents.ts - src/paths.ts - engine_configs/** - tests/project-workflow.test.ts - tests/agents-templates.test.ts - tests/engine-system.test.ts - tests/codex-context-files.test.ts Update truth when: - project initialization, generated project state, engine folder creation, role prompt materialization, or status/resume/freeze behavior changes - generated project AGENTS.md or base prompt package ownership changes ## Codex Role And Workflow Surfaces Truth documents: ```yaml truth_documents: - path: docs/truth/codex/roles-and-workflows.md kind: behavior ``` Code surface: - src/roles.ts - src/codex-session.ts - src/codex-prompts.ts - src/workflows.ts - src/templates.ts - templates/** - tests/roles.test.ts - tests/codex-session.test.ts - tests/codex-prompts.test.ts - tests/functionality-gap-pass.test.ts Update truth when: - studio role IDs, role contracts, workflow registry entries, prompt rendering, 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/truth/codex/runtime-and-tasks.md kind: workflow ``` Code surface: - src/runner.ts - src/tasks.ts - src/codex-runtime.ts - src/verification.ts - tests/runner.test.ts - tests/tasks.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 ## CLI And Validation Contracts Truth documents: ```yaml truth_documents: - path: docs/truth/contracts/cli-and-validation.md kind: contract ``` Code surface: - src/cli.ts - src/validation.ts - tests/validation.test.ts - tests/functionality-gap-pass.test.ts Update truth when: - public CLI commands, package scripts/bin/files, validation check IDs, documentation claims, or package dependency contracts change - future-only surfaces become exposed or are intentionally kept hidden # Truth Docs This directory is an index for current truth docs organized by the configured Truthmark hierarchy. README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under `<domain>/<behavior>.md`. # Repository Truth Docs This directory is reserved for repository-level truth indexes. 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) # Repository Overview ## Purpose Open GameStudio exists as a Codex-native workflow layer for game-development projects. The repository packages a TypeScript CLI that scaffolds game projects, renders role/workflow prompts for Codex, executes bounded Codex run lifecycles, and validates both repository and generated-project contracts. ## Scope This bounded leaf truth doc summarizes the repository-level behavior surface. More specific behavior is owned by the project scaffolding, Codex role/workflow, runtime/task execution, and CLI/validation truth documents listed in `docs/truthmark/areas/repository.md`. ## Current Behavior - The package exposes the `open-gamestudio` CLI from `dist/cli.js`. - Initialization commands create deterministic generated game project structure under `projects/<slug>`. - Generated projects contain `.codex/studio.json`, role prompt files, workflow markdown, starter design/production/market documents, engine-specific project markers, and a Codex-native `AGENTS.md` instruction surface. - Role run commands render deterministic Codex prompts and, unless in inspection mode, execute Codex with optional verification, review, and bounded fix passes. - Workflow shortcut commands are render-only prompt surfaces and do not imply hidden planner, parallel orchestration, telemetry, or ownership enforcement behavior. - Validation checks package metadata, source and template presence, role/workflow rendering, future-surface guardrails, build output, and package install smoke behavior. ## Core Rules - Repository behavior is grouped by behavior ownership rather than by mechanically mirroring every source file. - Generated project instruction contracts use Codex-native `AGENTS.md`; the repository does not introduce `CODEX.md` as a primary instruction contract. - Runtime execution is explicit: dry-run and print-prompt modes are inspection paths, while non-dry runs write prompt/run metadata before executing Codex. - Truthmark is an injected repository-truth workflow/tooling layer for agent surfaces and documentation routing. It is not an Open GameStudio runtime feature unless product code explicitly implements Truthmark-facing behavior. ## Flows And States Architecture runtime walkthroughs live under `docs/architecture/flows/**`; they explain branching logic and failure paths while linking back to the bounded truth docs that own the behavior. - Project initialization flow: parse CLI input, normalize engine/config, guard against project-name collisions, create engine/project folders, write `.codex` state and workflow files, write starter docs, and materialize role prompts/instructions. See `docs/architecture/flows/project-initialization.md`. - Role run flow: validate role/project/task, render prompt and context list, optionally return inspection output, write run cache, execute Codex, run verification/review, optionally run bounded fix passes, and report `done` or `blocked`. See `docs/architecture/flows/role-run-lifecycle.md`. - Workflow prompt rendering flow: validate project context, resolve the workflow alias/ID, render deterministic prompt text, and return without launching Codex or writing run state. See `docs/architecture/flows/workflow-prompt-rendering.md`. - Repository validation flow: build the package, run validation checks, and fail if any package, source, prompt, workflow, template, or future-surface contract is broken. See `docs/architecture/flows/validation-and-repository-truth.md`. ## Contracts - Public CLI command contracts are owned by `docs/truth/contracts/cli-and-validation.md`. - Role/workflow prompt contracts are owned by `docs/truth/codex/roles-and-workflows.md`. - Runtime/task lifecycle contracts are owned by `docs/truth/codex/runtime-and-tasks.md`. - Project scaffolding contracts are owned by `docs/truth/projects/project-scaffolding.md`. ## Product Decisions - Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file. - Decision (2026-05-30): Treat Truthmark Portal output as generated non-canonical presentation; Markdown truth docs remain canonical. - Decision (2026-05-30): Use Markdown Architecture Flow Guides as runtime-view documentation for important cross-cutting flow scenarios; bounded Truthmark truth docs remain the behavior authority. ## Rationale The repository combines scaffolding, prompt generation, runtime execution, and validation in one package. Keeping those surfaces bounded makes the architecture easier to reason about and prevents generated agent workflow scaffolding from being mistaken for user-facing Open GameStudio product behavior. ## Non-Goals - This doc does not replace the more specific bounded truth docs for project scaffolding, Codex role/workflow surfaces, runtime/task execution, or CLI/validation contracts. - This repository does not expose hidden parallel orchestration, telemetry, planner/next queues, or 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 the leaf truth docs named in `docs/truthmark/areas/repository.md` when behavior changes within their owned surface. - Update `docs/architecture/flows/**` when an architecturally relevant runtime branch, sequence, or failure path changes. - Relevant verification includes `npm run validate` for behavior changes and `npx truthmark check --json` for repository-truth documentation changes. # Project Scaffolding ## Purpose Project scaffolding turns a non-interactive CLI request into a ready Codex Game Studio project with deterministic state, engine markers, role prompts, workflow prompts, and starter production/design artifacts. ## Scope This bounded leaf truth doc owns project initialization, generated project state, engine-specific file/folder creation, generated project `AGENTS.md` and role prompts, and read-only project status/resume behavior. It does not own Codex run execution, task lifecycle persistence, or repository-level CLI validation. This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md. ## Current Behavior - `init` and `new` share the same initialization path and require `--name`, `--engine`, `--mode`, and `--non-interactive`. - Initialization writes projects under `projects/<slug>/`, rejects an existing target path, and checks same-parent slug and Unreal class-name collisions before writing. - Project state is written to `.codex/studio.json` with schema version 1, product `codex-game-studio`, the full canonical role roster, mode-active roles, and all workflow IDs. - Engine scaffolding uses the configured engine registry to create Godot, Unity, or Unreal marker files and source folders. - Initialization writes `.codex/workflows/*.md`, starter design/production/market docs, project `AGENTS.md`, and one prompt per studio role. - `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. - Generated projects live under `projects/<slug>/` by default. - `CODEX.md`, `project_orchestrator.md`, and `.gamestudio/runs` are forbidden generated project surfaces. - Generated project prompts must include the project name, role display name, project summary, engine context, role instructions, expected outputs, review checklist, and handoff sections. ## Flows And States - Initialization flow: parse options, normalize engine, derive slug, reject collisions, create engine files, create `.codex/runs`, write studio state, write workflow files, write starter docs, and materialize role prompts. - Project status states are `active`, `frozen`, and `inactive`; `freeze` is the only current CLI path that mutates status. ## Contracts - `open-gamestudio init --name <name> --engine <engine> --mode <mode> --non-interactive` creates a project and prints the created path. - `open-gamestudio new` is an alias for the same initialization behavior. - `open-gamestudio status --project <path>`, `resume --project <path>`, and `freeze --project <path>` operate on `.codex/studio.json`. ## Product Decisions - Decision (2026-05-28): Preserve Codex-native project state under `.codex/` and use project-level `AGENTS.md` as the generated instruction surface. - Decision (2026-05-28): Keep status/resume read-only so inspection commands cannot alter generated project state. ## Rationale A deterministic project scaffold gives Codex a stable context package without introducing a separate planner database or hidden orchestration layer. Keeping generated project instructions in `AGENTS.md` aligns with Codex-native workflows and avoids a parallel `CODEX.md` contract. ## Non-Goals - This doc does not own runtime Codex execution or task-store status transitions after project creation. - This doc does not define game engine runtime behavior beyond the initial marker files and folders created by the scaffolder. ## Maintenance Notes - Update this doc with changes to `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, `src/paths.ts`, or `engine_configs/**`. - Relevant verification includes project workflow, agent/template, engine-system, and project validation tests. # Codex Roles And Workflows ## Purpose Codex roles and workflows provide the role-specific prompt contracts, context boundaries, templates, and render-only workflow shortcuts that make Open GameStudio a Codex-native game-development layer. ## Scope This bounded leaf truth doc owns studio role IDs, role package metadata, Codex session prompt rendering, workflow registry entries, template registry behavior, and generated workflow prompt content. It does not own process execution, task persistence, package installation, or generated project initialization side effects. This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md. ## Current Behavior - The canonical studio role roster is defined by hyphenated Codex-native role IDs such as `producer`, `gameplay-programmer`, `qa-playtester`, and `studio-orchestrator`. - Each role package contains a display name, system prompt, context strategy, expected outputs, handoff wording, and a review checklist. - Codex session prompts render the role display name, role ID, phase, project root, objective, engine context, context files, expected outputs, verification command, review checklist, and completion-report instructions. - The workflow registry defines vertical-slice, bugfix, playtest, market-analysis, analytics-setup, design-spec, game-feel-tuning, art-direction, ui-ux-review, production-milestone, handoff, review, and ship-check workflow prompts. - Selected workflows include CLI aliases for render-only shortcuts, including market, analytics, design-spec, feel-review, art-direction, ui-review, milestone, and handoff. - Template selection is task- and role-sensitive; template files are read from package assets and embedded into applicable workflow prompts. ## Core Rules - Unknown role errors must point users toward Codex-native hyphenated role IDs rather than legacy agent names. - Prompt rendering must include the role display name and project/session metadata needed by Codex to operate without hidden state. - Templates that require Markdown sections must have non-empty required sections; the project config template must parse as JSON. - Workflow shortcuts render prompts; they do not imply hidden parallel orchestration or future planner behavior. ## Flows And States - Workflow prompt flow: read project engine from `.codex/studio.json`, look up the workflow registry entry, create a Codex studio session for the owning role and phase, render the standard prompt, then append any workflow template bodies. - Template selection flow: match role and task text against bounded keyword rules and return only matching template IDs. ## Contracts - Role IDs are stable strings exported from `src/roles.ts` and reused by config validation, project state, prompt generation, workflow routing, and task creation. - Workflow IDs map to `.codex/workflows/<workflow>.md` files and expected context-file lists. - Template IDs map to package template paths, role applicability, tags, and required-section validation. ## Product Decisions - Decision (2026-05-28): Use Codex-native hyphenated role IDs as the canonical user- and project-facing role contract. - Decision (2026-05-28): Keep workflow shortcuts render-only for this pass; future planner, next, telemetry, ownership enforcement, and parallel orchestration surfaces remain hidden. ## Rationale Role and workflow prompt generation is the user-facing contract that turns a generic Codex CLI into a specialized game-studio workflow. Keeping it render-only and declarative avoids overclaiming automation that is not implemented while still making the workflow packages inspectable and testable. ## Non-Goals - This doc does not own whether Codex is installed or authenticated. - This doc does not own task lifecycle mutations or verification command execution. ## Maintenance Notes - Update this doc with changes to `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, or `templates/**`. - Relevant verification includes role, Codex prompt/session, workflow, template, and functionality-gap tests. # Runtime And Task Execution ## Purpose Runtime and task execution connect prepared Codex Game Studio prompts to the Codex CLI, preserve explicit task state, and run bounded verification/review/fix loops without hidden orchestration. ## Scope This bounded leaf truth doc owns `run` preparation and execution, Codex command construction and availability checks, task-store persistence, review/fix lifecycle behavior, sandbox policy, and structured verification command execution. It does not own role prompt content, project scaffolding, or public CLI help wording except where runtime behavior depends on those options. ## Triggers - A user invokes `run <role> ... --project <path>` to render or execute a role prompt. - A user creates or runs a file-backed task through `task create` or `task run`. - A run includes structured verification, review, or bounded fix-pass options. ## Inputs - A valid project root with `.codex/studio.json`. - A studio role ID or task ID. - A non-empty task/objective. - Optional included artifacts, verification command/args, review flag, fix flag, and max fix-pass count. ## Execution Model - `prepareRun` resolves the project, reads studio state, renders a Codex prompt, computes prompt and metadata cache paths, and builds Codex execution commands. - `--print-prompt` and `--dry-run` are inspection-only paths 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. - Task runs mutate task status only for non-dry execution. ## Steps 1. Validate the requested role/task and project state. 2. Build context-file lists and render the Codex prompt. 3. For non-dry runs, write the prompt and metadata cache under `.codex/runs/`. 4. Check Codex availability before execution through the CLI path. 5. Execute the implementation prompt. 6. Run verification when configured. 7. Run review when requested and verification passes or is absent. 8. Run bounded fix passes when requested and blockers remain. 9. Report final status as `done` or `blocked`; task runs also persist final task status. ## State, Retry, And Failure Behavior - Task stores live at `.codex/tasks.json` with schema version 1 and unique `task-###` IDs. - `task create` requires a valid studio project before writing task state. - Task statuses are `ready`, `running`, `blocked`, and `done`. - Verification commands are spawned with bounded stdout/stderr capture, a default timeout, SIGTERM on timeout, and SIGKILL after the configured grace period. - Malformed review JSON, non-zero Codex execution, failed verification, or review blockers leave the lifecycle blocked unless a later bounded fix pass clears the blocker. ## Outputs - Dry-run output lists context files and the Codex command without writing 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. ## Product 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 while implementation/fix prompts retain workspace-write behavior. - Decision (2026-05-28): Require a valid project before task-store writes. ## Rationale Codex execution is intentionally explicit: users can inspect prompts without side effects, then run bounded implementation/review/fix loops with visible cache paths and verification output. Read-only review protects the review contract from accidentally becoming a second implementation pass. ## Non-Goals - This workflow does not implement hidden parallel execution, telemetry, ownership enforcement, or a planner/next queue. - This workflow does not choose role prompt content; it consumes the role and workflow surfaces owned by the Codex roles truth doc. ## Maintenance Notes - Update this doc with changes to `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, or `src/verification.ts`. - Relevant verification includes runner, task, verification, Codex runtime, and lifecycle-focused tests. # CLI And Validation Contracts ## Purpose The CLI and validation contracts define the public `open-gamestudio` command surface, package entrypoints, hard-failing validation checks, and future-surface guardrails for this repository. ## Scope This bounded leaf truth doc owns the repository CLI command contract, package scripts/bin/files expectations, validation check behavior, and documented public-surface claims. It does not own the internal details of project scaffolding, role prompt content, or Codex runtime lifecycle beyond the options exposed through the CLI. ## Contract Surface - Package name: `open-gamestudio`. - Package bin: `open-gamestudio` points to `./dist/cli.js`. - Primary scripts include `build`, `typecheck`, `test`, `validate`, `init`, `manage`, and `templates`. - Public CLI command groups include initialization/status commands, template discovery, role run execution, file-backed tasks, and render-only workflow shortcuts. - Repository validation is exposed through `open-gamestudio validate` and the `npm run validate` script. ## Inputs - CLI options and arguments parsed by Commander in `src/cli.ts`. - Repository files checked by validation, including package metadata, source files, templates, generated build output, engine configs, and optional project paths. - Project validation input when `--project <path>` is supplied. ## Outputs - CLI commands print human-readable status, prompt, task, validation, or workflow output. - Validation emits one line per check in `STATUS id: message (path)` shape and exits non-zero when any check fails. - Package smoke validation builds and exercises the packed package bin and template loading behavior. ## Errors And Diagnostics - Unknown roles fail with a message naming Codex-native hyphenated role IDs. - Missing package scripts, missing package bin/files, missing source files, unavailable Codex CLI, invalid templates, exposed future surfaces, missing build output, and package smoke failures are validation failures. - Project validation fails for invalid `.codex/studio.json`, missing generated project files, missing workflow/prompt sections, forbidden generated surfaces, or read-only command mutations. ## 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 >=20. - Packaged files must include `dist/`, `engine_configs/`, and `templates/` so the installed bin can load runtime assets. - Future-only command surfaces such as `next`, `telemetry`, `parallel`, and ownership enforcement must stay hidden until implemented intentionally. ## Versioning And Migration - Current package version is managed in `package.json` and rendered by Commander. - CLI contract changes should update README claims, validation expectations, and tests in the same change. ## Product Decisions - Decision (2026-05-28): Keep `validate` as the hard-failing parity gate before claiming repository or project readiness. - Decision (2026-05-28): Document and test that future planner/telemetry/parallel/ownership surfaces are not exposed by the CLI. ## Rationale The CLI is the stable integration boundary for humans, package installs, and generated project smoke checks. Validation makes those claims executable so prompt-surface and packaging drift fail before release or parity claims. ## Non-Goals - This contract does not document every generated prompt body; those belong to the Codex role/workflow truth doc. - This contract does not define npm audit remediation policy. ## Maintenance Notes - Update this doc with changes to `src/cli.ts`, `src/validation.ts`, package metadata, README public command claims, or validation check IDs. - Relevant verification includes `npm run validate`, CLI help smoke checks, validation tests, package dry-run/smoke checks, and future-surface guard tests."
  },
  {
    "url": "standards.html",
    "title": "Standards",
    "summary": "Documentation standards.",
    "sources": [
      "docs/standards/default-principles.md",
      "docs/standards/documentation-governance.md"
    ],
    "text": "# Default Principles ## Scope This is a bootstrap standards baseline for repositories that adopt Truthmark. ## Reusable Defaults - Authority order should be explicit. - Committed repository artifacts are the durable source of truth. - Each document should have one primary responsibility. - Each class of fact should have one canonical source. - Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, generated-surface ownership, and architecturally relevant runtime views. - Do not put ordinary feature behavior in architecture docs; use architecture flow guides only for cross-cutting runtime scenarios, branching logic, failure paths, and traceability back to bounded truth docs. - Verification should be explicit, and skipped checks should state why. - Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs. - Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable. # Documentation Governance ## Core Rules - Each document should have one primary responsibility. - Each class of fact should have one canonical source. - Current implementation, reusable standards, and future proposals should be stored separately. - Generated helper output is never canonical truth. - Architecture docs describe structure, ownership, and runtime views; truth docs describe current product behavior and remain the canonical behavior reference. - Architecture flow guides may explain branching logic and failure paths, but they must trace back to the owning truth docs rather than becoming a competing source of behavior truth. ## Truthmark Implications - Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort. - Weak routing produces weak truth maintenance. - Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created."
  }
]