docs: plan CCGS surface parity upgrades

2026-08-25 07:54:34 +02:00 · 2026-06-29 22:54:22 +10:00
parent d823bdefa5
commit 8aba7eeea0
8 changed files with 371 additions and 0 deletions
@@ -0,0 +1,13 @@
+# CCGS Surface Parity Upgrade Plan
+
+Canonical plan: `openspec/changes/ccgs-surface-parity-upgrade/`.
+
+This plan covers a one-by-one comparison of Codex Game Studio agents, skills, workflows, templates, rules, and validation behavior against the Claude Code Game Studios reference checkout.
+
+Start with:
+
+- `openspec/changes/ccgs-surface-parity-upgrade/proposal.md`
+- `openspec/changes/ccgs-surface-parity-upgrade/design.md`
+- `openspec/changes/ccgs-surface-parity-upgrade/specs/ccgs-surface-parity-audit/spec.md`
+- `openspec/changes/ccgs-surface-parity-upgrade/specs/codex-surface-quality-upgrades/spec.md`
+- `openspec/changes/ccgs-surface-parity-upgrade/tasks.md`
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-29
@@ -0,0 +1,20 @@
+# CCGS Surface Parity Upgrade
+
+This OpenSpec change is the canonical plan for comparing Codex Game Studio against Claude Code Game Studios one surface at a time and upgrading CGS where it falls behind.
+
+## Canonical Artifacts
+
+- `proposal.md`: why the parity audit and upgrade work is needed.
+- `design.md`: audit model, quality rubric, Codex-native adaptation decisions, risks, and rollout.
+- `specs/ccgs-surface-parity-audit/spec.md`: requirements for one-by-one inventory, mapping, scoring, and reports.
+- `specs/codex-surface-quality-upgrades/spec.md`: requirements for upgrading agents, skills, workflows, templates, validation, and behavioral evals.
+- `tasks.md`: ordered implementation checklist.
+
+## Reference Baseline
+
+Preliminary local inventory:
+
+- CGS current: 38 roles, 31 workflows, 11 generated skills.
+- CCGS reference: 49 `.claude/agents/*.md`, 73 `.claude/skills/*/SKILL.md`, and a 395-line `.claude/docs/workflow-catalog.yaml`.
+
+The implementation must generate a full parity matrix before claiming upgrade coverage.
@@ -0,0 +1,107 @@
+## Context
+
+The previous repository-root change made CGS clone-injectable and Codex-native, but the generated content is still shallow. For example, current `cgs-vertical-slice` is a short generic wrapper, while CCGS `.claude/skills/vertical-slice/SKILL.md` is a long phase-based production validation workflow with scope rules, recovery checkpoints, playtest debrief questions, verdicts, and report shape.
+
+A preliminary inventory from this checkout found:
+
+| Surface | CGS current | CCGS reference | Immediate gap |
+| --- | ---: | ---: | --- |
+| Agents / role packages | 38 | 49 | Missing sub-specialists and several renamed or collapsed domains need one-by-one decisions. |
+| Generated skills | 11 | 73 | Most CCGS command skills have no CGS equivalent yet. |
+| Workflows / workflow catalog steps | 31 workflow IDs | 30 unmatched workflow-catalog step IDs plus phase metadata | CGS has workflows but lacks CCGS phase progression, artifact checks, and gate semantics. |
+
+The plan must compare content quality, not only count files. CCGS agents often include frontmatter, tool/model hints, skills links, collaboration protocol, key responsibilities, forbidden actions, gate verdict formats, output templates, and escalation maps. CCGS skills often include invocation metadata, phase-by-phase context loading, artifact writes, user approval points, recovery checkpoints, quality standards, and concrete report templates.
+
+CGS must adapt those strengths to Codex-native surfaces:
+
+- `.codex/agents/*.toml` for custom agents;
+- `.agents/skills/<name>/SKILL.md` for repository skills;
+- `.codex/workflows/*.md` and `.codex/prompts/*.md` for current CGS runtime surfaces;
+- `AGENTS.md` for project instructions.
+
+CGS must not copy Claude-only mechanics as product behavior. CCGS hooks, AskUserQuestion UI details, `.claude/rules/**`, `.claude/settings.json`, and Claude model/tool metadata are evidence for intent, not implementation formats.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Produce a complete machine-readable and human-reviewable parity matrix for every CCGS agent, skill, and workflow-catalog step.
+- Decide one action for every row: `adopt`, `adapt`, `merge`, `rename-alias`, `defer`, or `out-of-scope`.
+- Upgrade CGS surfaces where CGS is lower quality and the CCGS behavior fits Codex Game Studio.
+- Preserve Codex-native file formats and root-mode generated surfaces.
+- Add validation and tests so upgraded generated surfaces cannot silently regress to generic wrappers.
+- Add cheap deterministic tests by default and keep real agent/LLM behavioral evals manual unless explicitly enabled.
+
+**Non-Goals:**
+
+- Do not promise full CCGS parity based on counts or README claims.
+- Do not bulk copy CCGS `.claude/**` files into CGS.
+- Do not add hidden lifecycle hooks or autonomous background orchestration.
+- Do not use `.codex/rules/*.rules` for coding standards.
+- Do not force one CGS surface per CCGS file when a merged Codex-native role or skill is better.
+- Do not make Truthmark, OpenSpec, or maintainer workflows part of generated game behavior unless a separate product decision says so.
+
+## Decisions
+
+### Compare one by one before upgrading
+
+Create an audit artifact at `references/ccgs-surface-parity-matrix.json` and a readable summary at `references/ccgs-surface-parity-matrix.md`. The matrix is generated from the CCGS checkout and current CGS registries. Every CCGS agent, skill, and workflow-catalog step gets one row with source path, source type, nearest CGS surface, quality scores, decision, rationale, implementation target, tests, and status.
+
+Alternative rejected: only compare counts or a few representative examples. The user explicitly called out quality and content gaps; aggregate counts would miss thin wrappers and collapsed domain expertise.
+
+### Use a quality rubric, not raw length
+
+Each row receives scores for content depth, procedural specificity, context contract, output contract, role/skill linkage, gate or escalation behavior, Codex fit, and testability. Long CCGS files can still be rejected if they are Claude-only; short CGS surfaces can pass if they cover the required contract.
+
+Alternative rejected: length parity. Long prompts can be noisy, and Codex skill lists can become unusable if every upstream section is copied without adaptation.
+
+### Adapt to Codex-native surfaces
+
+Agents upgrade `src/roles.ts` role packages and `renderProjectCustomAgentToml()` output. Skills upgrade `src/skills.ts` generated definitions and `.agents/skills/**` renderers. Workflows upgrade `src/workflows.ts`, `src/workflow-recipes.ts`, templates, and context manifest selection. CCGS command names become aliases only when they help users migrate and do not conflict with CGS naming.
+
+Alternative rejected: generate `.claude/agents/**` or `.claude/skills/**`. CGS remains a Codex-native product.
+
+### Phase the upgrades by production value
+
+Implement in vertical slices rather than one giant import:
+
+1. Audit tooling and matrix.
+2. Agent role-depth pass.
+3. Core lifecycle skills and workflows: `start`, `setup-engine`, `brainstorm`, `map-systems`, `design-system`, `create-architecture`, `vertical-slice`, `sprint-plan`, `bug-report`, `release-checklist`, `gate-check`.
+4. Discipline/team skills: art, audio, narrative, UI/UX, QA, live ops, release, tests, security, performance.
+5. Engine sub-specialists and plugin/domain specialists.
+6. Behavioral eval fixtures and manual agent probes.
+
+Alternative rejected: upgrade all 73 skills at once. That would be hard to review and likely import Claude-specific assumptions.
+
+### Validation must catch thin generated wrappers
+
+Validation should check required sections and selected body markers for upgraded surfaces, not just file existence or metadata. For example, vertical-slice must include validation question, scope discipline, recovery checkpoint, playtest debrief, and verdict/report guidance after upgrade.
+
+Alternative rejected: trust renderer snapshots alone. Snapshot freshness proves deterministic generation but not quality.
+
+## Risks / Trade-offs
+
+- Reference checkout availability can vary → store source path and source hash in the matrix and fail clearly when the CCGS reference is missing.
+- Over-importing CCGS can bloat Codex context → use matrix decisions and generate only active engine/team subsets by default.
+- CCGS collaboration rules may conflict with the user's autonomy preference → adapt approval language to CGS policy and keep mutating runtime explicit.
+- Engine sub-specialists may multiply prompt surfaces → materialize only specialists relevant to the selected engine and plugin stack.
+- Behavioral evals can burn tokens → keep deterministic structure checks in CI and make real agent probes opt-in.
+
+## Migration Plan
+
+1. Add audit fixtures and matrix generation without changing generated runtime behavior.
+2. Commit the baseline matrix so reviewers can inspect every row.
+3. Upgrade one domain cluster at a time with focused tests and validation.
+4. Refresh the matrix after each cluster and mark rows complete only when implementation, tests, and validation pass.
+5. Update README/user guide and Truthmark docs after behavior changes land.
+6. Run `npm test`, `npm run validate`, `truthmark check --json`, `truthmark index --json`, `openspec validate ccgs-surface-parity-upgrade --strict --json`, and `git diff --check` before claiming completion.
+
+Rollback: revert the cluster commit and its matrix status changes. Keep the audit tooling so later work can retry a smaller upgrade.
+
+## Open Questions
+
+- Should the CCGS reference path be configurable with `CCGS_REFERENCE_ROOT`, or should tests use checked-in fixtures only?
+- Which CCGS collaboration/approval rules should be softened for CGS given the user prefers autonomous execution on their own machine?
+- Should merged role decisions retain CCGS aliases such as `qa-lead`, `ux-designer`, and `lead-programmer`, or only record them in migration docs?
+- How many generated skills should be active by default before the skill list becomes noisy?
@@ -0,0 +1,35 @@
+## Why
+
+Codex Game Studio now exposes Codex-native agents, skills, and workflows, but the first generated pass is much thinner than Claude Code Game Studios. A preliminary inventory shows CGS currently has 38 role IDs, 31 workflow IDs, and 11 generated skills, while the CCGS reference checkout has 49 agents, 73 skills, and a 395-line workflow catalog with phase gates and artifact checks.
+
+This change creates a one-by-one CCGS comparison and upgrade plan so CGS improves content quality without blindly copying Claude-specific surfaces or hidden lifecycle behavior.
+
+## What Changes
+
+- Add a parity audit pipeline that inventories every CCGS agent, skill, and workflow-catalog step and maps it to a CGS role, workflow, skill, template, validation rule, or explicit deferral.
+- Add a quality rubric for generated agents, skills, and workflows covering domain depth, context inputs, procedure phases, output contracts, gate verdicts, escalation rules, tool/runtime boundaries, and behavioral-eval coverage.
+- Upgrade CGS generated Codex-native surfaces where the audit finds CGS is thinner than CCGS and the source behavior fits CGS product boundaries.
+- Expand generated skills from the current first-pass set toward CCGS-equivalent workflow coverage under `.agents/skills/<name>/SKILL.md`.
+- Expand or deepen role packages and custom-agent TOML developer instructions where CCGS agents carry stronger domain protocols.
+- Add workflow phase/catalog support where CCGS has explicit progression, required artifacts, repeatable steps, and gates that CGS lacks.
+- Add parity reports, tests, and validation that fail when an audited surface regresses below the accepted quality bar.
+- Do not add `.claude/**` compatibility, Claude hooks, hidden lifecycle automation, or Codex permission rules for coding standards.
+
+## Capabilities
+
+### New Capabilities
+
+- `ccgs-surface-parity-audit`: Inventory, map, score, and track every CCGS agent, skill, and workflow step against CGS surfaces.
+- `codex-surface-quality-upgrades`: Upgrade CGS Codex-native agents, skills, workflows, templates, and validation where the audit shows quality or coverage gaps.
+
+### Modified Capabilities
+
+None. This repository has no archived OpenSpec specs yet; the prior repository-root change is still an active change artifact.
+
+## Impact
+
+- Source: `src/roles.ts`, `src/agents.ts`, `src/skills.ts`, `src/workflows.ts`, `src/workflow-recipes.ts`, `src/templates.ts`, `src/validation.ts`, and related helpers.
+- Tests: `tests/agents-templates.test.ts`, `tests/project-workflow.test.ts`, `tests/runner.test.ts`, `tests/validation.test.ts`, new parity/audit tests, and optional behavioral-evaluation fixtures.
+- Generated surfaces: `AGENTS.md`, `.codex/agents/*.toml`, `.codex/prompts/*.md`, `.codex/workflows/*.md`, `.agents/skills/*/SKILL.md`, `.codex/context-manifest.json`, and starter game docs.
+- Reference input: `/opt/data/repos/Claude-Code-Game-Studios/.claude/agents/**`, `.claude/skills/**`, `.claude/docs/workflow-catalog.yaml`, `.claude/docs/templates/**`, `.claude/rules/**`, and `.claude/docs/**`.
+- Docs and truth: README/user guide updates only after implementation behavior changes; Truthmark docs updated after code and tests land.
@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: Complete CCGS surface inventory
+The system SHALL inventory every CCGS agent file, skill package, and workflow-catalog step before marking a parity upgrade complete.
+
+#### Scenario: CCGS reference is available
+- **WHEN** the audit command is run with a valid CCGS reference root
+- **THEN** the output includes rows for every `.claude/agents/*.md`, every `.claude/skills/*/SKILL.md`, and every step in `.claude/docs/workflow-catalog.yaml`
+
+#### Scenario: CCGS reference is missing
+- **WHEN** the audit command is run without an available CCGS reference root
+- **THEN** the command fails with a diagnostic naming the missing reference path and does not write a partial completed matrix
+
+### Requirement: One-by-one mapping decisions
+The parity matrix SHALL assign exactly one decision to every CCGS source row: `adopt`, `adapt`, `merge`, `rename-alias`, `defer`, or `out-of-scope`.
+
+#### Scenario: Surface has a direct CGS counterpart
+- **WHEN** a CCGS surface has an equivalent CGS role, workflow, skill, template, or validation rule
+- **THEN** the matrix records the CGS target path and a decision explaining whether to adopt, adapt, or leave unchanged
+
+#### Scenario: Surface has no CGS counterpart
+- **WHEN** a CCGS surface has no matching CGS target
+- **THEN** the matrix records a decision of `adopt`, `adapt`, `merge`, `defer`, or `out-of-scope` with a rationale and follow-up task reference
+
+### Requirement: Quality scoring rubric
+The audit SHALL score each mapped surface against a documented quality rubric rather than using file count or length alone.
+
+#### Scenario: Skill is a thin wrapper
+- **WHEN** a CGS skill only tells the agent to read another workflow file and report changed files
+- **THEN** the audit marks missing procedure depth, context contract, output contract, and testability against the comparable CCGS skill
+
+#### Scenario: Claude-only behavior is present
+- **WHEN** a CCGS source depends on Claude-specific hooks, tools, settings, or UI mechanics
+- **THEN** the audit records the useful product intent separately from the rejected Claude-specific implementation format
+
+### Requirement: Source traceability
+Every parity row SHALL record source paths and source hashes for the CCGS source and CGS target used during comparison.
+
+#### Scenario: Source content changes
+- **WHEN** the CCGS source hash changes after a matrix row was accepted
+- **THEN** validation reports that the row needs review before parity can be claimed
+
+### Requirement: Reviewable reports
+The audit SHALL produce both machine-readable and human-readable parity reports.
+
+#### Scenario: Matrix generation completes
+- **WHEN** the audit command succeeds
+- **THEN** it writes `references/ccgs-surface-parity-matrix.json` and `references/ccgs-surface-parity-matrix.md` with matching row counts and decision summaries
@@ -0,0 +1,71 @@
+## ADDED Requirements
+
+### Requirement: Codex-native upgrade targets
+Surface upgrades SHALL be implemented through CGS Codex-native registries and renderers, not by copying `.claude/**` runtime files.
+
+#### Scenario: Agent surface is upgraded
+- **WHEN** a CCGS agent row is accepted for upgrade
+- **THEN** the implementation updates CGS role package content and generated `.codex/agents/<role>.toml` developer instructions without generating `.claude/agents/**`
+
+#### Scenario: Skill surface is upgraded
+- **WHEN** a CCGS skill row is accepted for upgrade
+- **THEN** the implementation updates generated `.agents/skills/<name>/SKILL.md` content with Codex-native metadata and procedures without generating `.claude/skills/**`
+
+#### Scenario: Workflow surface is upgraded
+- **WHEN** a CCGS workflow-catalog row is accepted for upgrade
+- **THEN** the implementation updates CGS workflow definitions, recipes, templates, context selection, or validation rather than adding hidden hooks
+
+### Requirement: Content-depth acceptance criteria
+An upgraded surface SHALL include enough adapted content to match the accepted CCGS intent for domain responsibilities, context inputs, procedure, outputs, and escalation or gate behavior.
+
+#### Scenario: Upgraded vertical-slice skill
+- **WHEN** the vertical-slice skill is regenerated after upgrade
+- **THEN** the generated skill includes validation question framing, scope discipline, recovery checkpoint, playtest/debrief procedure, verdict options, and report expectations
+
+#### Scenario: Upgraded producer agent
+- **WHEN** the producer custom agent is regenerated after upgrade
+- **THEN** the generated TOML developer instructions include sprint planning, milestone management, risk management, scope negotiation, coordination boundaries, and status-report output expectations
+
+### Requirement: Alias and merge decisions
+The system SHALL preserve migration clarity when CCGS surfaces are renamed, merged, or split in CGS.
+
+#### Scenario: CCGS role is merged into a CGS role
+- **WHEN** a CCGS role such as `qa-lead` maps to a CGS role such as `qa-playtester`
+- **THEN** the matrix records the merge decision and tests verify the generated CGS role covers the accepted lead responsibilities
+
+#### Scenario: CCGS command name becomes an alias
+- **WHEN** a CCGS skill or workflow name is accepted as a compatibility alias
+- **THEN** CLI/help/rendering tests verify both the canonical CGS name and alias resolve to the same adapted surface
+
+### Requirement: Generated-surface validation
+Validation SHALL fail for missing, stale, malformed, or content-thin generated surfaces after a surface has been accepted for upgrade.
+
+#### Scenario: Upgraded skill loses required sections
+- **WHEN** a generated upgraded skill is missing a required adapted section
+- **THEN** project validation fails with a diagnostic naming the skill and missing section
+
+#### Scenario: Wrong engine specialist appears
+- **WHEN** a generated project includes CCGS-derived engine specialists for an inactive engine
+- **THEN** project validation fails and names the wrong-engine agent or skill
+
+### Requirement: Behavioral evaluation separation
+The implementation SHALL distinguish deterministic generated-surface validation from real agent behavior evaluation.
+
+#### Scenario: Deterministic validation passes
+- **WHEN** generated files include expected metadata and content sections
+- **THEN** the test result may claim generated-surface freshness and content coverage but MUST NOT claim that agents behave correctly in real tasks
+
+#### Scenario: Manual agent probe is enabled
+- **WHEN** a manual behavioral-eval command is explicitly run
+- **THEN** it records scenario, trace, diff or artifact output, final report, and reviewer verdict separately from default CI tests
+
+### Requirement: Product-boundary preservation
+Upgrades SHALL preserve the CGS product boundary and SHALL NOT import hidden Claude lifecycle behavior as default generated behavior.
+
+#### Scenario: CCGS source uses hooks
+- **WHEN** a CCGS workflow depends on `.claude/hooks/**`
+- **THEN** the CGS upgrade captures explicit validation or workflow intent and does not generate `.codex/hooks.json` by default
+
+#### Scenario: CCGS source uses coding rules
+- **WHEN** a CCGS rule describes coding standards under `.claude/rules/**`
+- **THEN** the CGS upgrade maps accepted standards to skills, AGENTS guidance, or selected context and does not write coding standards to `.codex/rules/*.rules`
@@ -0,0 +1,75 @@
+## 1. Baseline Inventory and Audit Tooling
+
+- [ ] 1.1 Add `scripts/audit-ccgs-surfaces.ts` that reads `CCGS_REFERENCE_ROOT` or defaults to `/opt/data/repos/Claude-Code-Game-Studios`.
+- [ ] 1.2 Add parser coverage for CCGS `.claude/agents/*.md` frontmatter, body sections, skills lists, gate tokens, and output templates.
+- [ ] 1.3 Add parser coverage for CCGS `.claude/skills/*/SKILL.md` frontmatter, argument hints, allowed tools, assigned agent, phase headings, context files, write targets, verdicts, and report templates.
+- [ ] 1.4 Add parser coverage for `.claude/docs/workflow-catalog.yaml` phases, steps, commands, required flags, repeatable flags, artifact globs, artifact patterns, and next-phase links.
+- [ ] 1.5 Add CGS registry extraction for `src/roles.ts`, `src/workflows.ts`, `src/skills.ts`, `src/templates.ts`, and generated validation markers.
+- [ ] 1.6 Write `tests/ccgs-parity-audit.test.ts` with fixture-based unit tests proving all three source types produce stable inventory rows.
+- [ ] 1.7 Run `npm test -- tests/ccgs-parity-audit.test.ts`; expected result: parser tests pass without requiring the live CCGS checkout.
+
+## 2. Parity Matrix and Scoring Rubric
+
+- [ ] 2.1 Define the matrix schema in `src/ccgs-parity.ts` with source type, source path, source hash, CGS target, decision, score fields, rationale, implementation owner path, test path, and status.
+- [ ] 2.2 Implement score categories: content depth, procedural specificity, context contract, output contract, role-skill linkage, gate/escalation behavior, Codex fit, and testability.
+- [ ] 2.3 Generate `references/ccgs-surface-parity-matrix.json` and `references/ccgs-surface-parity-matrix.md` from the current live CCGS checkout.
+- [ ] 2.4 Require every CCGS row to have one decision: `adopt`, `adapt`, `merge`, `rename-alias`, `defer`, or `out-of-scope`.
+- [ ] 2.5 Seed obvious preliminary decisions for known exact gaps: CCGS has 49 agents, 73 skills, and workflow-catalog phase steps; CGS currently has 38 roles, 31 workflows, and 11 generated skills.
+- [ ] 2.6 Add tests that fail when row counts differ between JSON and Markdown reports.
+- [ ] 2.7 Add tests that fail when any row lacks a decision, rationale, or source hash.
+
+## 3. Agent-by-Agent Upgrade Pass
+
+- [ ] 3.1 Compare every CCGS agent against `src/roles.ts` and record whether the target is a direct role, merged role, alias, new role, or out-of-scope.
+- [ ] 3.2 Upgrade high-value direct matches first: `producer`, `creative-director`, `technical-director`, `game-designer`, `systems-designer`, `gameplay-programmer`, `qa-playtester`, `release-manager`, and `performance-analyst`.
+- [ ] 3.3 Resolve renamed or collapsed roles: `art-director`, `narrative-director`, `ux-designer`, `qa-lead`, `qa-tester`, `lead-programmer`, `prototyper`, and `analytics-engineer`.
+- [ ] 3.4 Decide and implement engine sub-specialists: Godot C#, GDExtension, GDScript, shader; Unity Addressables, DOTS, shader, UI; Unreal Blueprint, GAS, replication, UMG.
+- [ ] 3.5 Update `renderProjectCustomAgentToml()` tests so upgraded agents prove required domain sections appear in `.codex/agents/*.toml`.
+- [ ] 3.6 Update prompt rendering tests so `.codex/prompts/*.md` and `.codex/agents/*.toml` stay semantically aligned.
+- [ ] 3.7 Run `npm test -- tests/agents-templates.test.ts tests/project-workflow.test.ts tests/validation.test.ts`.
+
+## 4. Skill-by-Skill Upgrade Pass
+
+- [ ] 4.1 Replace generic generated skill bodies in `src/skills.ts` with a renderer that supports per-skill phases, context files, write targets, handoff/report formats, and validation markers.
+- [ ] 4.2 Upgrade onboarding and setup skills: `start`, `onboard`, `adopt`, `setup-engine`, `help`, and `project-stage-detect`.
+- [ ] 4.3 Upgrade design skills: `brainstorm`, `quick-design`, `map-systems`, `design-system`, `design-review`, `review-all-gdds`, `art-bible`, `asset-spec`, `ux-design`, and `ux-review`.
+- [ ] 4.4 Upgrade architecture and production skills: `create-architecture`, `create-control-manifest`, `architecture-decision`, `architecture-review`, `create-epics`, `create-stories`, `estimate`, `sprint-plan`, `sprint-status`, `scope-check`, and `milestone-review`.
+- [ ] 4.5 Upgrade build and validation skills: `prototype`, `vertical-slice`, `bug-report`, `bug-triage`, `qa-plan`, `regression-suite`, `smoke-check`, `soak-test`, `test-setup`, `test-helpers`, `test-flakiness`, and `test-evidence-review`.
+- [ ] 4.6 Upgrade release and operations skills: `release-checklist`, `launch-checklist`, `hotfix`, `day-one-patch`, `patch-notes`, `changelog`, `localize`, `security-audit`, `perf-profile`, `tech-debt`, and `retrospective`.
+- [ ] 4.7 Upgrade team specialty skills: `team-audio`, `team-combat`, `team-level`, `team-live-ops`, `team-narrative`, `team-polish`, `team-qa`, `team-release`, and `team-ui`.
+- [ ] 4.8 Add validation that upgraded generated skills include required sections and adapted body markers, not just frontmatter.
+- [ ] 4.9 Run `npm test -- tests/project-workflow.test.ts tests/validation.test.ts tests/template-root-smoke.test.ts`.
+
+## 5. Workflow Catalog and Phase Progression
+
+- [ ] 5.1 Add a CGS workflow-catalog model that can represent CCGS-style phases, required steps, optional steps, repeatable steps, artifact checks, and next-phase links.
+- [ ] 5.2 Map CCGS catalog phases into CGS lifecycle phases without importing Claude slash-command mechanics.
+- [ ] 5.3 Upgrade `status`, `resume`, and workflow rendering to show relevant next steps, required artifacts, and incomplete gate checks.
+- [ ] 5.4 Implement explicit artifact checks for accepted workflow rows such as game concept, systems map, architecture, UX design, vertical slice, playtest polish, release checklist, and changelog.
+- [ ] 5.5 Add tests for required artifact detection and repeatable step reporting.
+- [ ] 5.6 Run `npm test -- tests/runner.test.ts tests/tasks.test.ts tests/workflow-recipes.test.ts tests/validation.test.ts`.
+
+## 6. Templates, Rules, and Context Adaptation
+
+- [ ] 6.1 Compare CCGS `.claude/docs/templates/**` one by one against CGS `templates/**` and record matrix decisions.
+- [ ] 6.2 Upgrade or add templates where CCGS has stronger game-facing artifacts: art bible, architecture decision record, control manifest, pitch, project-stage report, prototype report, test plan, UX spec, and vertical-slice report.
+- [ ] 6.3 Compare CCGS `.claude/rules/**` one by one and map accepted standards to `.agents/skills/**`, `AGENTS.md`, or selected context, never `.codex/rules/*.rules`.
+- [ ] 6.4 Update context manifest defaults so upgraded workflows select the minimum relevant standards, templates, and engine references.
+- [ ] 6.5 Run `npm test -- tests/codex-context-files.test.ts tests/agents-templates.test.ts tests/validation.test.ts`.
+
+## 7. Behavioral Evaluation Layer
+
+- [ ] 7.1 Add deterministic fixture tests for upgraded generated content before adding any LLM or live Codex probe.
+- [ ] 7.2 Add manual behavioral-eval scenarios for at least producer planning, vertical-slice scoping, bug triage, QA plan, and release checklist.
+- [ ] 7.3 Ensure manual eval output records scenario, selected agent/skill, prompt, trace summary, changed files or no-write proof, final report, and reviewer verdict.
+- [ ] 7.4 Keep real Codex/LLM judge runs out of default `npm test` unless explicitly enabled by environment variables.
+- [ ] 7.5 Run deterministic behavioral tests with `npm test -- tests/behavioral-evaluation.test.ts`.
+
+## 8. Documentation, Truth, and Final Validation
+
+- [ ] 8.1 Update README and user guide only after upgraded behavior exists and tests pass.
+- [ ] 8.2 Update Truthmark docs for role, skill, workflow, template, validation, and generated-surface behavior after code lands.
+- [ ] 8.3 Refresh `references/ccgs-surface-parity-matrix.*` and confirm every adopted/adapted/merged row is implemented or intentionally deferred.
+- [ ] 8.4 Run `npm test`.
+- [ ] 8.5 Run `npm run validate` before any parity claim.
+- [ ] 8.6 Run `truthmark check --json`, `truthmark index --json`, `git diff --check`, `openspec validate ccgs-surface-parity-upgrade --strict --json`, `openspec validate --all --strict --json`, and `openspec status --change ccgs-surface-parity-upgrade --json`.