fix: render custom workflows with built-in roles

Support project-local custom workflows that target built-in studio roles by rendering through the standard Codex session prompt and role contract path.

Add regression coverage for validation-accepted built-in workflow roles and update routed Truthmark role/workflow docs.
This commit is contained in:
MerlinH
2026-06-26 00:31:03 +10:00
parent bea667adff
commit 484e8667ad
3 changed files with 95 additions and 5 deletions
@@ -37,7 +37,7 @@ This doc was created from the editable engineering-behavior template at docs/tru
- Behavioral evaluation scenarios cover representative role/workflow prompt contracts by rendering prompts locally and checking required obligations, output-contract fields, selected context categories, relevant templates, forbidden future-only drift, and prompt-size bounds without LLM judges or hosted evaluators.
- Market analyst, data scientist, game-feel, UI/UX, QA, release, audio, content, systems/economy, accessibility/localization/live-ops/community, and technical specialist roles have bounded default role packages; reusable template selection remains task-specific rather than loading every role or template.
- Project-local customization packs may add `custom-*` role, workflow, and template IDs through `.codex/studio/config.json`; these overlays are extend-only and cannot replace built-in role/workflow/template IDs.
- Custom role prompts render the same visible role ID, context strategy, expected outputs, review checklist, write-policy, sandbox, and selected-template sections as built-in role runs, while custom workflow prompts use the generic `workflow <id>` command, require the declared workflow markdown file to exist, include that file as selected context, and render its body as workflow instructions rather than adding unbounded shortcut commands.
- Custom role prompts render the same visible role ID, context strategy, expected outputs, review checklist, write-policy, sandbox, and selected-template sections as built-in role runs, while custom workflow prompts use the generic `workflow <id>` command, require the declared workflow markdown file to exist, include that file as selected context, and render its body as workflow instructions rather than adding unbounded shortcut commands. Custom workflows may target either a built-in studio role or a project-local custom role; built-in targets render through the standard Codex session prompt and role contract, while custom targets append the project-local custom role prompt.
- Generated workflow files carry deterministic source-input and rendered-body hash metadata that covers workflow definition fields and the owning role display name, expected outputs, and review checklist used in the rendered workflow body.
## Core Rules
@@ -54,7 +54,7 @@ This doc was created from the editable engineering-behavior template at docs/tru
## Flows And States
- Workflow prompt flow: read project stage, studio mode, and engine from `.codex/studio.json`, select the workflow's declared context files through the path-safe selector, compute phase/studio-mode eligibility, create a Codex studio session for the owning role and phase, render the standard prompt with a context contract, then append any workflow template bodies.
- Custom workflow prompt flow: resolve the workflow or alias from `.codex/studio/config.json`, validate its custom role, workflow file, and template references, select the declared workflow file plus other project-safe context files, render the workflow file body as workflow instructions, render the custom role prompt, then append only the custom workflow's template IDs.
- Custom workflow prompt flow: resolve the workflow or alias from `.codex/studio/config.json`, accept a validated built-in studio role or project-local custom role target, select the declared workflow file plus other project-safe context files, render the workflow file body as workflow instructions, render the built-in session role contract or custom role prompt for the target role, then append only the custom workflow's template IDs.
- Template selection flow: match role and task text against bounded keyword rules and return only matching template IDs.
## Contracts
@@ -82,7 +82,7 @@ This doc was created from the editable engineering-behavior template at docs/tru
- Decision (2026-06-17): Expand engine reference depth as package-shipped, metadata-validated active-engine assets with default role references plus task/workflow-keyword-selected module and plugin references.
- Decision (2026-06-17): Expand role prompt depth through structured compact role contracts and reusable shared fragments rendered in both standard Codex session prompts and generated project role prompts, while keeping role/task context bounded.
- Decision (2026-06-17): Add representative behavioral-evaluation fixtures as deterministic prompt-contract checks instead of adopting hosted/LLM agent-evaluation infrastructure.
- Decision (2026-06-17): Add project-local customization as an extend-only overlay so users can define local `custom-*` roles, workflows, and templates while preserving built-in registries and bounded context selection.
- Decision (2026-06-17): Add project-local customization as an extend-only overlay so users can define local `custom-*` roles, workflows, and templates while preserving built-in registries and bounded context selection; custom workflows may reuse built-in roles rather than requiring duplicate local role definitions.
## Rationale
@@ -101,3 +101,6 @@ Role and workflow prompt generation is the user-facing contract that turns a gen
## Source References
- ../../routes/areas/repository.md
- ../../../../src/workflows.ts
- ../../../../src/customization.ts
- ../../../../tests/customization.test.ts