pixelheros/.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
#
# 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.

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
        artifact:
          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 (8 required sections, 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"
        required: true
        artifact:
          glob: "design/accessibility-requirements.md"
        description: "Commit accessibility tier (Basic/Standard/Comprehensive/Exemplary) and feature matrix. UX specs (Phase 4) reference this tier."

  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:
          glob: "prototypes/*/README.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: test-setup
        name: "Test Framework Setup"
        command: /test-setup
        required: false
        artifact:
          note: "Check tests/ directory for engine-specific test framework scaffold"
        description: "Scaffold the test framework and CI pipeline once before the first sprint. Leads to /test-helpers for fixture generation, /qa-plan per epic, and /smoke-check per sprint."

      - 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:
          glob: "prototypes/*/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 src/ 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: false
        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:
          glob: "production/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"

  release:
    label: "Release"
    description: "Launch preparation, certification, and ship"
    next_phase: null
    steps:
      - id: release-checklist
        name: "Release Checklist"
        command: /release-checklist
        required: true
        description: "Pre-release validation across all departments: code, content, store, legal"

      - id: patch-notes
        name: "Patch Notes"
        command: /patch-notes
        required: false
        description: "Generate player-facing patch notes from git history and sprint data"

      - id: changelog
        name: "Changelog"
        command: /changelog
        required: false
        description: "Auto-generate internal changelog from commits, sprints, and design docs"

      - id: launch-checklist
        name: "Launch Checklist"
        command: /launch-checklist
        required: true
        description: "Final launch readiness — last gate before shipping to players"