Claude-Code-Game-Studios/.claude/docs/workflow-catalog.yaml

# Workflow Catalog
# Used by /help to determine where a user is and what comes next.
#
# Artifact checks:
#   glob: file glob pattern — complete if ≥1 file matches (or min_count)
#   pattern: text pattern that must appear in the file (checked after glob)
#   min_count: minimum matching files required (default: 1)
#   note: human-readable fallback when completion can't be auto-detected
#   any_of: list of alternative {glob, pattern} specs — the step is complete if
#           ANY one of them matches. Use when a setting has migrated and may
#           legitimately live in either the new or the legacy location.
#
# required: true → blocks progression to next phase (shown as REQUIRED)
# required: false → optional enhancement (shown as OPTIONAL)
# repeatable: true → runs multiple times (one per system, story, etc.)
#
# Phase gates (/gate-check): verdicts are ADVISORY — they guide the decision
# but never hard-block advancement. The user always decides whether to proceed.

# Tier paths: a tier whose route is not the phase ladder. At `workflow: minimal`
# nothing on the path runs /gate-check, so project.stage never leaves Concept —
# and walking the Concept phase names the concept doc, art bible and systems map
# (all REQUIRED there) as blockers on a project that already has stories.
# /help reads paths.minimal instead of the ladder at that tier. Same step schema
# as phases; artifact-check.sh reports a path only when asked with --path <id>.

paths:

  minimal:
    label: "Minimal path"
    description: "Engine, one-page brief, stories, then build — the brief's build order is the plan"
    steps:
      - id: engine-setup
        name: "Engine Setup"
        command: /setup-engine
        required: true
        # Same alternatives as concept.engine-setup — see the notes there.
        artifact:
          any_of:
            - glob: "project.yaml"
              pattern: 'name:[[:space:]]*"?(Godot|Unity|Unreal)'
            - glob: ".claude/docs/technical-preferences.md"
              pattern: '\*\*Engine\*\*: [^[]'
        description: "Configure the engine and pin its version"

      - id: game-brief
        name: "Game Brief"
        command: /brainstorm
        required: true
        artifact:
          glob: "design/game-brief.md"
        description: "One page: pitch, MVP features, build order. Replaces the concept doc, art bible, systems map and GDDs at this tier"

      - id: create-stories
        name: "Stories"
        command: /create-stories
        required: true
        artifact:
          glob: "production/epics/*/story-*.md"
        description: "One story per MVP feature, in build order. No /create-epics or /sprint-plan at this tier"

      - id: implement
        name: "Build the Next Story"
        command: /dev-story
        required: true
        repeatable: true
        artifact:
          note: "Each story's Status line (Ready / In Progress / Complete) is the record — story files are numbered in build order"
        description: "Implement the next story in build order: /dev-story [story-path]"

      - id: story-done
        name: "Close the Story"
        command: /story-done
        required: true
        repeatable: true
        description: "Verify the acceptance criteria and mark the story Complete, then build the next one"

phases:

  concept:
    label: "Concept"
    description: "Develop your game idea into a documented concept"
    next_phase: systems-design
    steps:
      - id: brainstorm
        name: "Brainstorm"
        command: /brainstorm
        required: false
        description: "Explore the game concept using MDA, verb-first, and player psychology frameworks"

      - id: engine-setup
        name: "Engine Setup"
        command: /setup-engine
        required: true
        # v1.1: engine.name in project.yaml is the primary source; technical-
        # preferences.md is the legacy fallback. Checking only the legacy file
        # made a correctly-configured project fail this REQUIRED gate.
        # /setup-engine writes the value quoted (`name: "Godot"`), so the quote
        # is optional; without it only the legacy alternative ever matched.
        # Single-quoted so the `"` needs no escape — artifact-check.sh strips
        # the outer quotes and does not unescape.
        artifact:
          any_of:
            - glob: "project.yaml"
              pattern: 'name:[[:space:]]*"?(Godot|Unity|Unreal)'
            # technical-preferences.md writes "- **Engine**: Godot 4.6", so the
            # pattern must clear the bold markers. The previous "Engine: [^[]"
            # required a literal "Engine: " and therefore never matched any
            # file /setup-engine produces. The [^[] guard rejects the
            # "[TO BE CONFIGURED]" placeholder.
            - glob: ".claude/docs/technical-preferences.md"
              pattern: '\*\*Engine\*\*: [^[]'
        description: "Configure engine, pin version, set naming conventions and performance budgets"

      - id: game-concept
        name: "Game Concept Document"
        command: /brainstorm
        required: true
        artifact:
          glob: "design/gdd/game-concept.md"
        description: "Formalize concept with pillars, MDA analysis, and scope tiers"

      - id: design-review-concept
        name: "Concept Review"
        command: /design-review
        required: false
        description: "Validate the game concept (recommended before proceeding)"

      - id: art-bible
        name: "Art Bible"
        command: /art-bible
        required: true
        artifact:
          glob: "design/art/art-bible.md"
        description: "Author the visual identity specification (9 sections). Uses the Visual Identity Anchor produced by /brainstorm. Run after game concept is formed, before systems design."

      - id: map-systems
        name: "Systems Map"
        command: /map-systems
        required: true
        artifact:
          glob: "design/gdd/systems-index.md"
        description: "Decompose concept into systems with dependency ordering and priority tiers"

  systems-design:
    label: "Systems Design"
    description: "Author a GDD for each system in the systems index"
    next_phase: technical-setup
    steps:
      - id: design-system
        name: "System GDDs"
        command: /design-system
        required: true
        repeatable: true
        artifact:
          note: "Check design/gdd/systems-index.md — each MVP system needs Status: Approved"
        description: "Author per-system GDDs (guided, section-by-section). Run once per system."

      - id: design-review
        name: "Per-System Design Review"
        command: /design-review
        required: true
        repeatable: true
        description: "Validate each GDD (required sections per workflow tier, no MAJOR REVISION verdict). Run per system."

      - id: review-all-gdds
        name: "Cross-GDD Review"
        command: /review-all-gdds
        required: true
        artifact:
          glob: "design/gdd/gdd-cross-review-*.md"
        description: "Holistic consistency check + design theory review across all GDDs simultaneously"

      - id: consistency-check
        name: "Consistency Check"
        command: /consistency-check
        required: false
        repeatable: true
        description: "Scan all GDDs for contradictions, undefined references, and mechanic conflicts. Run after /review-all-gdds, and again any time a GDD is added or revised mid-project."

  technical-setup:
    label: "Technical Setup"
    description: "Architecture decisions, visual identity specification, accessibility foundations, engine validation"
    next_phase: pre-production
    steps:
      - id: create-architecture
        name: "Architecture Document"
        command: /create-architecture
        required: true
        artifact:
          glob: "docs/architecture/architecture.md"
        description: "Author the master architecture document covering all systems"

      - id: architecture-decision
        name: "Architecture Decisions (ADRs)"
        command: /architecture-decision
        required: true
        repeatable: true
        artifact:
          glob: "docs/architecture/adr-*.md"
          min_count: 3
        description: "Document key technical decisions as ADRs. Minimum 3 Foundation-layer ADRs required."

      - id: architecture-review
        name: "Architecture Review"
        command: /architecture-review
        required: true
        artifact:
          glob: "docs/architecture/architecture-review-*.md"
        description: "Validate completeness, dependency ordering, engine compatibility"

      - id: control-manifest
        name: "Control Manifest"
        command: /create-control-manifest
        required: true
        artifact:
          glob: "docs/architecture/control-manifest.md"
        description: "Flat programmer rules sheet generated from all Accepted ADRs"

      - id: accessibility-doc
        name: "Accessibility Requirements"
        # This step had no `command:` at all -- the only artifact entry in the
        # catalog that named no producer. It was REQUIRED, so the Technical
        # Setup -> Pre-Production gate could never pass, and the remediation
        # every skill printed ("run /ux-design") wrote into design/ux/ where
        # this glob does not look. /ux-design now has an `accessibility` mode.
        command: /ux-design
        required: true
        artifact:
          glob: "design/accessibility-requirements.md"
        description: "Run `/ux-design accessibility`. Commit accessibility tier (Basic/Standard/Comprehensive/Exemplary) and feature matrix. UX specs (Phase 4) reference this tier."

      - id: interaction-patterns
        name: "Interaction Pattern Library"
        command: /ux-design
        required: true
        artifact:
          glob: "design/ux/interaction-patterns.md"
        description: "Run `/ux-design patterns` to start the pattern library that UX specs reuse. The Technical Setup → Pre-Production gate requires it at `full` (recommended at `standard`)."

      - id: test-setup
        name: "Test Framework Setup"
        command: /test-setup
        required: true
        artifact:
          glob: ".github/workflows/tests.yml"
        description: "Scaffold the test framework, the CI workflow and an example test. The Technical Setup → Pre-Production gate requires all three at `standard` and `full`. Leads to /test-helpers for fixture generation, /qa-plan per epic, and /smoke-check per sprint."

  pre-production:
    label: "Pre-Production"
    description: "Visual entity inventory, UX specs, asset specs, prototype the core mechanic, define stories, validate fun"
    next_phase: production
    steps:
      - id: entity-inventory
        name: "Visual Entity & Screen Inventory"
        command: /asset-spec
        required: false
        artifact:
          glob: "design/assets/entity-inventory.md"
        description: "Enumerate everything the game needs visually: entities (characters, enemies, buildings, environment pieces), UI screens, HUD elements, panels. Run /asset-spec with no arguments to start a collaborative inventory session — brief or detailed based on your responses. Reads GDDs and art bible to propose a starting list; you add, remove, and adjust. Becomes the source of truth for all art and UX work. Not required if the game has very few distinct visual elements."

      - id: asset-spec
        name: "Asset Specs"
        command: /asset-spec
        required: false
        repeatable: true
        artifact:
          glob: "design/assets/asset-manifest.md"
        description: "Generate per-asset visual specifications and AI generation prompts. Run once per entity, system, level, or character. If no source doc exists, /asset-spec interviews you inline — no narrative document required."

      - id: ux-design
        name: "UX Specs (key screens)"
        command: /ux-design
        required: true
        repeatable: true
        artifact:
          glob: "design/ux/*.md"
          min_count: 3
        description: "Author UX specs for the screens identified in the entity inventory (or GDDs if no inventory). Minimum required: main menu, core gameplay HUD, pause menu. Add more screens as the inventory identifies them. Reads input method and platform from technical-preferences.md."

      - id: ux-review
        name: "UX Review"
        command: /ux-review
        required: true
        description: "Validate all key screen UX specs for GDD alignment and accessibility tier compliance. Run before creating epics."

      - id: prototype
        name: "Prototype"
        command: /prototype
        required: false
        artifact:
          # /prototype writes prototypes/[name]-concept/REPORT.md -- it has never
          # written a README. The `-concept` suffix is load-bearing: /vertical-slice
          # writes the same REPORT.md basename under `-vertical-slice`, so a bare
          # `prototypes/*/REPORT.md` here would let either step satisfy the other.
          glob: "prototypes/*-concept/REPORT.md"
          min_count: 1
        description: "Build a throwaway prototype to validate the core mechanic is fun before committing to full production. Recommended for first-time mechanics or high-risk design decisions. Solo devs with proven concepts may skip."

      - id: create-epics
        name: "Create Epics"
        command: /create-epics
        required: true
        repeatable: true
        artifact:
          glob: "production/epics/*/EPIC.md"
          min_count: 1
        description: "Translate GDDs + ADRs into epics — one per architectural module. Run per layer: /create-epics layer: foundation, then /create-epics layer: core"

      - id: create-stories
        name: "Create Stories"
        command: /create-stories
        required: true
        repeatable: true
        artifact:
          glob: "production/epics/**/*.md"
          min_count: 2
        description: "Break each epic into implementable story files. Run per epic: /create-stories [epic-slug]"

      - id: sprint-plan
        name: "First Sprint Plan"
        command: /sprint-plan
        required: true
        artifact:
          glob: "production/sprints/sprint-*.md"
          min_count: 1
        description: "Plan the first sprint with prioritized stories from epics"

      - id: vertical-slice
        name: "Vertical Slice"
        command: /vertical-slice
        required: false
        artifact:
          # Must stay scoped to `-vertical-slice`: the untethered form matched
          # /prototype's concept report, so running only /prototype silently
          # marked the vertical slice complete and skipped the validation the
          # Pre-Production → Production gate exists to require.
          glob: "prototypes/*-vertical-slice/REPORT.md"
          min_count: 1
        description: "Build and playtest a vertical slice — a complete end-to-end pass through the core loop. Recommended before committing epics and stories to production. Skipping is a valid solo dev call but increases risk of late-stage design pivots. If built, must be played and documented before advancing."

  production:
    label: "Production"
    description: "Sprint-based feature development — pick, implement, close stories"
    next_phase: polish
    steps:
      - id: sprint-plan
        name: "Sprint Plan"
        command: /sprint-plan
        required: true
        repeatable: true
        artifact:
          glob: "production/sprints/sprint-*.md"
        description: "Plan the current sprint with prioritized, ready stories"

      - id: story-readiness
        name: "Story Readiness Check"
        command: /story-readiness
        required: false
        description: "Validate a story is implementation-ready before a developer picks it up"

      - id: implement
        name: "Implement Stories"
        command: /dev-story
        required: true
        repeatable: true
        artifact:
          note: "Check the code root (src/, Assets/ or Source/ by engine) for active code and production/epics/**/*.md for In Progress stories"
        description: "Pick the next ready story and implement it with /dev-story [story-path]. Routes to the correct programmer agent."

      - id: code-review
        name: "Code Review"
        command: /code-review
        required: false
        repeatable: true
        description: "Architectural code review after each story implementation. Run after /dev-story, before /story-done."

      - id: story-done
        name: "Story Done Review"
        command: /story-done
        required: true
        repeatable: true
        description: "Verify all acceptance criteria, check GDD/ADR deviations, close the story"

      - id: qa-plan
        name: "QA Plan"
        command: /qa-plan
        required: false
        repeatable: true
        description: "Generate a QA test plan per epic or sprint. Run /qa-plan [epic-slug]. Produces test cases for /smoke-check, /regression-suite, and /test-evidence-review."

      - id: bug-report
        name: "Bug Report / Triage"
        command: /bug-report
        required: false
        repeatable: true
        description: "Log and prioritize bugs found during implementation. /bug-report creates a structured report; /bug-triage prioritizes the open backlog."

      - id: retrospective
        name: "Sprint Retrospective"
        command: /retrospective
        required: false
        repeatable: true
        description: "Post-sprint review to capture what worked and what to change. Run at the end of each sprint, before planning the next."

      - id: team-feature
        name: "Team Orchestration (optional)"
        required: false
        repeatable: true
        description: "Coordinate multiple agents on a complex feature. Use: /team-combat, /team-narrative, /team-ui, /team-audio, /team-level, /team-live-ops, /team-qa. Run when a feature spans multiple agent domains."

      - id: scope-check
        name: "Scope Check"
        command: /scope-check
        required: false
        repeatable: true
        artifact:
          glob: "production/sprints/sprint-*.md"
          note: "Run when stories are added mid-sprint, or before sprint retrospectives"
        description: "Detect scope creep by comparing current sprint scope to original epic scope. Run (a) when stories are added mid-sprint, or (b) before sprint retrospectives."

      - id: sprint-status
        name: "Sprint Status"
        command: /sprint-status
        required: false
        description: "Quick 30-line snapshot of sprint progress without a full report"

  polish:
    label: "Polish"
    description: "Performance, balance, playtesting, bug fixing"
    next_phase: release
    steps:
      - id: perf-profile
        name: "Performance Profile"
        command: /perf-profile
        required: false
        description: "Profile and optimize CPU/GPU/memory bottlenecks"

      - id: balance-check
        name: "Balance Check"
        command: /balance-check
        required: true
        description: "Analyze game balance formulas and data for outliers and broken progressions"

      - id: asset-audit
        name: "Asset Audit"
        command: /asset-audit
        required: false
        description: "Verify naming conventions, file format standards, and size budgets"

      - id: playtest-polish
        name: "Playtest Sessions (×3)"
        command: /playtest-report
        required: true
        artifact:
          # /playtest-report writes production/qa/playtests/, not production/playtests/.
          # The old glob matched nothing on every project, so this REQUIRED step
          # read as 0/3 forever no matter how many playtests were actually run.
          glob: "production/qa/playtests/*.md"
          min_count: 3
        description: "Cover: new player experience, mid-game systems, difficulty curve"

      - id: team-polish
        name: "Polish Team Pass"
        command: /team-polish
        required: true
        description: "Coordinated polish pass across performance, audio, visual, and UX"

      - id: security-audit
        name: "Security Audit"
        command: /security-audit
        required: true
        artifact:
          glob: "production/security/security-audit-*.md"
        description: "The Polish -> Release gate reads the newest `full`-scope report (plus any later `quick` re-run) at standard and full: no open CRITICAL or HIGH finding"

      - id: localize-qa
        name: "Localization QA"
        command: /localize
        required: false
        description: "Run `/localize qa` for every language you ship; at full the release gate needs PASS or PASS WITH CONDITIONS for each (recommended at standard, dropped at minimal)"

      - id: release-checklist
        name: "Release Checklist"
        command: /release-checklist
        required: true
        description: "Pre-release validation across all departments: code, content, store, legal. The Polish -> Release gate checks it, so it runs before /gate-check release"

      - id: changelog
        name: "Changelog"
        command: /changelog
        required: true
        description: "Internal changelog from commits, sprints, and design docs. The release gate needs the changelog or the patch notes drafted"

      - id: patch-notes
        name: "Patch Notes"
        command: /patch-notes
        required: false
        description: "Player-facing patch notes from git history and sprint data; /team-release finalizes them on a GO"

  release:
    label: "Release"
    description: "Launch preparation, certification, and ship"
    next_phase: null
    steps:
      - id: launch-checklist
        name: "Launch Checklist"
        command: /launch-checklist
        required: true
        description: "Final launch readiness — last gate before shipping to players"

      - id: team-release
        name: "Coordinated Release"
        command: /team-release
        required: false
        description: "Release candidate, quality gate, go/no-go and deployment, coordinated across release, QA and DevOps"