@zigrivers/scaffold 3.4.1 → 3.5.0

package/content/pipeline/specification/art-bible.md

@@ -0,0 +1,87 @@
+---
+name: art-bible
+description: Define art style, per-type asset specifications, naming conventions, DCC pipeline, LOD strategy, and collision layers
+summary: "Establishes the visual identity and technical art standards — art style pillars, per-type asset specs (3D models, 2D sprites, VFX, animation), naming conventions, DCC pipeline, LOD strategy, Git LFS mapping, and hitbox/collision layer definitions."
+phase: "specification"
+order: 866
+dependencies: [game-design-document, performance-budgets, content-structure-design]
+outputs: [docs/art-bible.md]
+conditional: null
+reads: []
+knowledge-base: [game-asset-pipeline, game-performance-budgeting, game-binary-vcs-strategy, review-art-bible]
+---
+
+## Purpose
+Define the complete art bible for the project — the authoritative reference for
+visual identity, technical art standards, and asset production workflows. This
+document bridges the creative vision from the GDD with the technical constraints
+from performance budgets to produce actionable specifications that every artist
+on the team follows.
+
+Games require per-type asset specifications because a character model, an
+environment prop, a VFX particle, and a UI sprite each have fundamentally
+different polygon budgets, texture requirements, animation constraints, and
+optimization strategies. Without an art bible, artists produce assets with
+inconsistent quality, naming, and technical specs — leading to pipeline
+failures, performance regressions, and visual incoherence.
+
+## Inputs
+- docs/game-design.md (required) — art style direction, world setting, character roster, environment types
+- docs/performance-budgets.md (required) — polygon budgets, texture memory budgets, draw call limits per platform
+- docs/content-structure-design.md (required) — content organization, asset directory structure, naming taxonomy
+- docs/plan.md (required) — target platforms informing quality tiers and LOD requirements
+
+## Expected Outputs
+- docs/art-bible.md — art style guide, per-type asset specs, naming conventions,
+  DCC pipeline, LOD strategy, Git LFS mapping, and collision layer definitions
+
+## Quality Criteria
+- (mvp) Art style pillars defined with visual reference descriptions (mood, color palette, silhouette language, rendering style)
+- (mvp) Per-type asset specs documented: 3D models (poly budget, texture resolution, material slots), 2D sprites (resolution, atlas packing, animation frames), VFX (particle count, draw call budget, shader complexity), animation (bone count, clip length, blend tree structure)
+- (mvp) Naming conventions defined per asset type following content-structure-design taxonomy
+- (mvp) DCC pipeline documented: source tool → export format → engine import → validation
+- (mvp) LOD strategy defined with distance thresholds, poly reduction targets, and LOD count per asset category
+- (mvp) Hitbox and collision layer definitions for gameplay-critical assets (characters, projectiles, interactables, terrain)
+- (deep) Git LFS tracking rules mapped per file type with size thresholds and binary file extensions
+- (deep) Texture compression formats specified per platform (BCn for desktop/console, ASTC for mobile, ETC2 fallback)
+- (deep) Material and shader standards documented (PBR metallic-roughness vs specular-glossiness, shader LOD, material instance hierarchy)
+- (deep) Color grading and post-processing reference targets for consistent look across lighting scenarios
+- (deep) Asset validation automation: import hooks that reject out-of-budget assets before they enter version control
+
+## Methodology Scaling
+- **deep**: Full art bible with style guide, per-type asset specs for all
+  categories (character, environment, prop, VFX, UI, animation), DCC pipeline
+  with tool-specific export settings, LOD strategy with platform-specific
+  distance tables, Git LFS configuration, texture compression matrix,
+  material standards, collision layer map, and automated validation rules.
+  15-25 pages.
+- **mvp**: Art style pillars, per-type specs for primary asset categories,
+  naming conventions, basic LOD strategy, and collision layer definitions.
+  4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: art style pillars and primary asset type polygon/texture budgets only.
+  - Depth 2: add naming conventions, basic DCC export pipeline, and collision layer definitions.
+  - Depth 3: add LOD strategy with distance thresholds, Git LFS mapping, and per-platform texture formats.
+  - Depth 4: add material/shader standards, animation specs, VFX budgets, and asset validation automation.
+  - Depth 5: full art bible with color grading targets, cinematic asset specs, destructible environment specs, and art QA checklist.
+
+## Mode Detection
+Check for docs/art-bible.md. If it exists, operate in update mode: read
+existing art bible and diff against current GDD visual direction and
+performance budgets. Preserve existing art style pillars, naming conventions,
+and DCC pipeline decisions. Update per-type budgets if performance budgets
+changed. Add specs for new asset categories introduced by GDD changes.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/art-bible.md exists
+- **Preserve**: art style pillars, existing per-type asset specs, naming
+  conventions, DCC pipeline configuration, material standards, collision layer
+  definitions
+- **Triggers for update**: GDD changed visual direction or added new asset
+  categories, performance budgets revised polygon or texture memory limits,
+  content-structure-design changed directory layout or naming taxonomy, target
+  platforms changed (affects LOD tiers and texture compression)
+- **Conflict resolution**: if performance budget reductions require lowering
+  per-type asset specs, document the impact on visual quality with before/after
+  comparison notes and propose tiered quality settings rather than universal
+  downgrade; never silently lower art specs without flagging the visual impact

package/content/pipeline/specification/audio-design.md

@@ -0,0 +1,96 @@
+---
+name: audio-design
+description: Define audio direction, SFX categories, adaptive music, middleware config, spatial audio, VO plan, and platform loudness targets
+summary: "Establishes audio direction, SFX category taxonomy, adaptive music system, middleware configuration (Wwise/FMOD), spatial audio setup, voice-over pipeline, platform-specific loudness targets (LUFS), and memory budget allocation from performance budgets."
+phase: "specification"
+order: 867
+dependencies: [game-design-document, performance-budgets, content-structure-design]
+outputs: [docs/audio-design.md]
+conditional: null
+reads: [narrative-bible]
+knowledge-base: [game-audio-design]
+---
+
+## Purpose
+Define the complete audio design specification — the authoritative reference for
+audio direction, middleware configuration, asset production standards, and
+runtime behavior. This document translates the emotional and mechanical needs
+from the GDD into concrete audio architecture decisions.
+
+Audio is a primary player feedback channel: it communicates spatial awareness
+(enemy footsteps behind you), game state (health low warning), emotional tone
+(rising tension before a boss), and mechanical timing (attack wind-up cues).
+Unlike visual assets which players consciously evaluate, audio operates
+subconsciously — players feel bad audio as "something is off" without
+identifying the cause. This makes early audio planning critical: middleware
+selection, bus hierarchy, and adaptive music architecture cannot be easily
+retrofitted once content production begins.
+
+**Note on forward-reads**: `narrative-bible` is listed as an optional read. On
+first generation it may not exist yet — in that case, define placeholder VO
+categories (protagonist, NPCs, narration) and mark them with
+`<!-- pending: narrative-bible -->` for a future update pass. When
+narrative-bible becomes available, these placeholders are filled in during
+update mode.
+
+## Inputs
+- docs/game-design.md (required) — mechanics, core loop, world setting, emotional tone informing audio direction
+- docs/performance-budgets.md (required) — audio memory budget, CPU budget for audio processing, streaming constraints
+- docs/content-structure-design.md (required) — audio asset directory structure, naming taxonomy
+- docs/plan.md (required) — target platforms informing loudness targets and format requirements
+- docs/narrative-bible.md (optional, forward-read) — character roster, dialogue structure, VO volume and language requirements
+
+## Expected Outputs
+- docs/audio-design.md — audio direction, SFX categories, adaptive music system,
+  middleware config, spatial audio, VO plan, loudness targets, and memory budget
+
+## Quality Criteria
+- (mvp) Audio direction defined: emotional tone per game context (exploration, combat, menu, cinematic), reference tracks or descriptive style pillars
+- (mvp) SFX categories defined with priority tiers: gameplay-critical (weapon, footstep, UI feedback), ambient (environment, weather), and cosmetic (character emotes, incidental)
+- (mvp) Adaptive music system documented: layered stems, horizontal re-sequencing, or vertical remixing approach with transition rules between game states
+- (mvp) Middleware selection documented with rationale (Wwise, FMOD, or engine-native) and bus hierarchy (master, music, SFX, ambient, VO, UI)
+- (mvp) Platform-specific loudness targets specified: -24 LUFS +/-2 for console, -18 LUFS +/-2 for mobile, with metering approach
+- (mvp) Audio memory budget allocated from performance budgets: streaming vs resident pools, per-platform limits
+- (deep) Spatial audio configuration: HRTF profiles, occlusion/obstruction model, attenuation curves, reverb zone strategy
+- (deep) VO pipeline documented: casting direction, recording spec (sample rate, bit depth, format), naming convention, localization workflow per language
+- (deep) Audio format matrix per platform: codec (Vorbis, Opus, ADPCM, platform-native), quality settings, streaming chunk size
+- (deep) Dynamic range management: compressor/limiter settings per bus, ducking rules (VO ducks music, gameplay SFX ducks ambient)
+- (deep) Accessibility audio: audio descriptions, mono downmix option, visual indicators for critical audio cues
+
+## Methodology Scaling
+- **deep**: Full audio design with style guide, complete SFX taxonomy with
+  per-category specs, adaptive music system with state machine, middleware
+  configuration with bus hierarchy and effects chains, spatial audio setup,
+  VO pipeline with localization plan, per-platform loudness and format matrix,
+  dynamic range strategy, memory budget breakdown, and accessibility audio
+  plan. 15-25 pages.
+- **mvp**: Audio direction, primary SFX categories, basic adaptive music
+  approach, middleware selection, loudness targets, and memory budget
+  allocation. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: audio direction pillars and primary SFX category list only.
+  - Depth 2: add middleware selection, bus hierarchy, and loudness targets.
+  - Depth 3: add adaptive music system, memory budget allocation, and audio format per platform.
+  - Depth 4: add spatial audio configuration, VO pipeline, dynamic range management, and accessibility audio.
+  - Depth 5: full specification with localization VO plan, per-context audio profiling targets, procedural audio specs, and audio QA checklist.
+
+## Mode Detection
+Check for docs/audio-design.md. If it exists, operate in update mode: read
+existing audio design and diff against current GDD emotional direction and
+performance budgets. Preserve existing middleware selection, bus hierarchy,
+and adaptive music architecture. Update memory budgets if performance budgets
+changed. Fill VO placeholders when narrative-bible becomes available.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/audio-design.md exists
+- **Preserve**: middleware selection, bus hierarchy, adaptive music architecture,
+  spatial audio configuration, loudness targets, audio format decisions
+- **Triggers for update**: GDD changed emotional tone or added new game states
+  requiring music transitions, performance budgets revised audio memory or CPU
+  limits, content-structure-design changed audio asset organization,
+  narrative-bible created (fill VO placeholder sections), target platforms
+  changed (affects loudness targets and format requirements)
+- **Conflict resolution**: if performance budget reductions require lowering
+  audio memory allocation, document the impact on simultaneous voice count
+  and streaming quality with concrete tradeoff analysis; propose quality
+  tiers (high/medium/low) rather than universal quality reduction

package/content/pipeline/specification/content-structure-design.md

@@ -0,0 +1,141 @@
+---
+name: content-structure-design
+description: Design level layouts, world regions, procedural rulesets, or mission structures based on content type
+summary: "Adapts output based on content structure trait: discrete levels, open-world regions, procedural generation rulesets, endless escalation bands, or mission templates. Always enabled for games."
+phase: "specification"
+order: 865
+dependencies: [game-design-document, system-architecture]
+outputs: [docs/content-structure/]
+conditional: null
+reads: [narrative-bible, performance-budgets]
+knowledge-base: [game-level-content-design]
+---
+
+## Purpose
+Design the content structure for the game — the organizational framework for
+all playable content. This step adapts its output based on the game's
+`contentStructure` trait, producing fundamentally different deliverables
+depending on the content model:
+
+- **discrete** — Traditional level-based games (platformers, puzzle games,
+  linear shooters). Produces level layout documents with progression
+  difficulty curves, mechanic introduction schedules, and pacing maps.
+- **open-world** — Seamless explorable spaces (open-world RPGs, survival
+  games). Produces world region documents with biome definitions, point-of-
+  interest density maps, level streaming boundaries, and exploration gating.
+- **procedural** — Content generated at runtime (roguelikes, procedural
+  dungeons). Produces generation ruleset documents with seed parameters,
+  constraint systems, content pools, difficulty scaling formulas, and
+  quality validation rules.
+- **endless** — Infinite escalation games (endless runners, wave survival,
+  idle games). Produces escalation band documents with difficulty curves,
+  content rotation schedules, score/distance milestones, and engagement
+  pacing analysis.
+- **mission-based** — Open structure with discrete objectives (GTA-style,
+  MMO quest systems). Produces mission template documents with objective
+  types, branching conditions, reward structures, and mission flow graphs.
+
+The `contentStructure` trait is determined from the GDD. If the GDD does not
+explicitly state a content structure, infer it from the game's genre, core
+loop, and mechanics catalog.
+
+## Inputs
+- docs/game-design.md (required) — core loop, mechanics, game modes, and world overview establishing content structure type
+- docs/system-architecture.md (required) — level streaming, scene management, and content loading architecture
+- docs/narrative-bible.md (optional, forward-read) — story beats, character arcs, and environmental storytelling requirements to weave into content structure
+- docs/performance-budgets.md (optional, forward-read) — per-scene object counts, draw call limits, and memory budgets constraining content density
+
+## Expected Outputs
+- docs/content-structure/ — directory containing content structure documents
+  adapted to the game's content type. Common files:
+  - `content-overview.md` — content structure type, volume estimates, and
+    progression philosophy
+  - Type-specific files (one or more depending on contentStructure trait):
+    - `level-designs.md` (discrete)
+    - `world-regions.md` (open-world)
+    - `generation-rulesets.md` (procedural)
+    - `escalation-bands.md` (endless)
+    - `mission-templates.md` (mission-based)
+
+## Content Structure Trait Adaptation
+
+### Discrete Levels
+- Level layout descriptions: spatial flow, encounter placement, collectible locations
+- Difficulty curve: per-level target difficulty mapped to overall progression arc
+- Mechanic introduction schedule: when each mechanic is introduced, tutorialized, and tested
+- Pacing map: intensity curve per level (exploration, combat, puzzle, rest)
+- Boss/milestone encounters: placement rationale and difficulty spike design
+
+### Open World Regions
+- Region definitions: biomes, themes, environmental hazards, ambient population
+- Point-of-interest density: landmarks, encounters, and discovery content per region
+- Level streaming boundaries: region transition points and loading strategy
+- Exploration gating: soft gates (difficulty), hard gates (story/item requirements), and natural barriers
+- Content density guidelines: encounters per square unit, loot distribution curves
+
+### Procedural Generation
+- Generation rulesets: seed parameters, room/tile templates, connection rules
+- Constraint systems: minimum distances, forbidden combinations, required guarantees (e.g., always include a shop)
+- Content pools: available rooms, enemies, items, events per difficulty tier
+- Difficulty scaling formulas: how seed or depth translates to enemy stats, trap frequency, resource scarcity
+- Quality validation: automated checks for solvability, pacing, fairness, and degenerate generation detection
+
+### Endless Escalation
+- Escalation bands: difficulty tiers with entry thresholds (score, distance, wave number)
+- Content rotation: how obstacles, enemies, and powerups cycle within and across bands
+- Milestone design: score/distance targets that provide psychological checkpoints
+- Engagement pacing: when to introduce new elements, when to provide breathers, when to spike difficulty
+- Long-session sustainability: how the game remains engaging past typical session length
+
+### Mission-Based
+- Mission templates: objective types (fetch, escort, defend, assassinate, investigate)
+- Branching conditions: prerequisite missions, player choice gates, reputation thresholds
+- Reward structures: XP, currency, items, narrative payoff per mission type and difficulty
+- Mission flow graphs: dependency trees showing critical path and optional branches
+- Side content integration: how side missions relate to main narrative and world state
+
+## Quality Criteria
+- (mvp) Content structure type identified and justified from GDD analysis
+- (mvp) Content volume estimated: total levels/regions/mission count with development effort per unit
+- (mvp) Difficulty progression defined from start to endgame with no unexplained difficulty spikes
+- (mvp) Every core loop mechanic exercised by content — no mechanic introduced in GDD but never used in content
+- (mvp) Content structure respects performance budgets (if available) — per-scene object counts, streaming boundaries
+- (deep) Narrative integration: story beats from narrative-bible mapped to content structure (level, region, or mission)
+- (deep) Replayability analysis: what drives repeat engagement (procedural variety, optional objectives, difficulty modes)
+- (deep) Content pipeline documented: authoring workflow from design to engine-ready format
+- (deep) Pacing analysis with annotated intensity curves showing moment-to-moment and session-level rhythm
+
+## Methodology Scaling
+- **deep**: Full content structure specification with all trait-specific
+  deliverables, narrative integration, replayability analysis, content
+  pipeline documentation, pacing analysis with intensity curves, and
+  content volume estimates with effort sizing. 15-30 pages.
+- **mvp**: Content type identification, core content overview, and key
+  progression structure. 3-5 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: content type identification and volume estimate only.
+  - Depth 2: add core progression structure and difficulty curve outline.
+  - Depth 3: add full trait-specific deliverables and mechanic-to-content mapping.
+  - Depth 4: add narrative integration, replayability analysis, and pacing intensity curves.
+  - Depth 5: full specification with content pipeline documentation, effort sizing per content unit, and automated quality validation rules.
+
+## Mode Detection
+Check for docs/content-structure/ directory. If it exists, operate in update
+mode: read existing content structure documents and diff against current GDD
+and system architecture. Preserve existing level/region/mission designs.
+Add content for new mechanics or areas. Update difficulty curves if GDD
+progression systems changed.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/content-structure/ directory exists with content files
+- **Preserve**: existing level layouts, region definitions, generation
+  rulesets, mission templates, difficulty curves, and pacing maps
+- **Triggers for update**: GDD added new mechanics or game modes, narrative-
+  bible added story beats requiring content placement, performance-budgets
+  revised per-scene limits, system architecture changed streaming or scene
+  management approach
+- **Conflict resolution**: if performance budget changes require reducing
+  content density in a region or level, document the constraint and propose
+  specific cuts prioritizing gameplay-critical content over ambient detail;
+  if narrative requirements conflict with pacing design, flag for user
+  decision with tradeoff analysis

package/content/pipeline/specification/economy-design.md

@@ -0,0 +1,104 @@
+---
+name: economy-design
+description: Design virtual currencies, faucet/sink balancing, loot tables, progression economy, and monetization with legal compliance
+summary: "Defines the game economy separating progression economy (currencies, faucet/sink balance, loot tables, crafting costs) from monetization (store, pricing, ethical guidelines). Includes legal compliance per target market for loot boxes, probability disclosure, and spending limits."
+phase: "specification"
+order: 868
+dependencies: [game-design-document]
+outputs: [docs/economy-design.md]
+conditional: "if-needed"
+reads: []
+knowledge-base: [game-economy-design]
+---
+
+## Purpose
+Design the complete game economy — the system of virtual currencies, resource
+flows, reward structures, and (optionally) real-money transactions that govern
+player progression and engagement. This document explicitly separates two
+concerns that are often conflated:
+
+1. **Progression economy**: How players earn, spend, and value in-game resources
+   through gameplay. This exists in every game with resources, upgrades, or
+   unlockables — including premium single-player titles with no monetization.
+2. **Monetization economy**: How the studio generates revenue through the
+   economy. This only applies to games with in-app purchases, premium currency,
+   or real-money trading.
+
+Separating these concerns matters because progression economy must be
+intrinsically satisfying regardless of monetization. If removing all real-money
+paths leaves an economy that feels grindy or punishing, the progression design
+is fundamentally broken.
+
+Legal compliance adds a third dimension. Loot boxes, gacha mechanics, and
+real-money randomized rewards face different regulations per market (China,
+Belgium, Netherlands, US state laws, Australia). Compliance requirements must
+be designed in — not patched after launch — because they affect UI flows,
+backend systems, and content structures.
+
+## Conditional Evaluation
+Enable when: the GDD describes any of the following — virtual currencies,
+resource crafting/spending systems, loot tables, progression unlocks tied to
+resource accumulation, in-app purchases, premium currency, battle passes,
+seasonal stores, or any economy-like mechanic beyond simple score tracking.
+
+Skip when: the game has no resource economy — e.g., pure arcade games with
+score-only progression, narrative adventures with no inventory or currency,
+puzzle games with no unlock systems. Simple XP/level systems that only gate
+content (no spending decisions) do not require a full economy design.
+
+## Inputs
+- docs/game-design.md (required) — core loop, progression mechanics, monetization model (if any), resource types
+- docs/plan.md (required) — target markets informing legal compliance requirements, business model (premium, F2P, hybrid)
+
+## Expected Outputs
+- docs/economy-design.md — currency definitions, faucet/sink models, loot table
+  design, progression economy, monetization design (if applicable), and legal
+  compliance checklist
+
+## Quality Criteria
+- (mvp) All virtual currencies defined with earn rates, spend sinks, and target time-to-purchase for key items
+- (mvp) Faucet/sink balance modeled: currency generation and removal rates per player-hour with steady-state analysis
+- (mvp) Progression economy operates independently of monetization — removing real-money paths does not break the core loop
+- (mvp) If loot tables exist: drop rate ranges defined, pity/mercy mechanics specified, duplicate handling documented
+- (mvp) If monetization exists: store structure, pricing tiers, and ethical guidelines documented (no pay-to-win in PvP, spending limit awareness)
+- (deep) Inflation/deflation trajectory modeled over player lifecycle (early game, mid game, end game, live service)
+- (deep) Exploit vectors identified at design level: duplication, overflow, conversion rate manipulation, timing exploits
+- (deep) Legal compliance checklist per target market: probability disclosure requirements, age-gating, spending limits, loot box classification
+- (deep) Economy simulation spreadsheet or formula reference with tunable parameters for balance testing
+- (deep) Seasonal/live-service economy plan: event currencies, battle pass reward tracks, limited-time offers, FOMO management
+
+## Methodology Scaling
+- **deep**: Full economy design with multi-currency architecture, faucet/sink
+  mathematical model, loot table probability design with pity systems,
+  progression economy with milestone analysis, monetization design with
+  ethical framework, legal compliance per market, exploit vector analysis,
+  economy simulation reference, and live-service economy plan. 15-25 pages.
+- **mvp**: Currency definitions, basic faucet/sink balance, progression
+  economy structure, and monetization overview (if applicable). 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: currency definitions and basic earn/spend rates only.
+  - Depth 2: add faucet/sink balance model and progression-monetization separation analysis.
+  - Depth 3: add loot table design, exploit vector identification, and legal compliance checklist.
+  - Depth 4: add inflation trajectory modeling, economy simulation formulas, and ethical monetization framework.
+  - Depth 5: full specification with live-service economy plan, seasonal event economics, A/B testing strategy for economy tuning, and economy health KPIs.
+
+## Mode Detection
+Check for docs/economy-design.md. If it exists, operate in update mode: read
+existing economy design and diff against current GDD progression and
+monetization mechanics. Preserve existing currency definitions, faucet/sink
+models, and legal compliance decisions. Update economy parameters if GDD
+changed progression pacing or added new resource types.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/economy-design.md exists
+- **Preserve**: currency definitions, faucet/sink ratios, loot table
+  probabilities, legal compliance decisions, monetization pricing structure,
+  ethical guidelines
+- **Triggers for update**: GDD changed progression mechanics or added new
+  resource types, target markets changed (affects legal compliance), business
+  model changed (premium to F2P or vice versa), live-service plan added
+  seasonal economy elements
+- **Conflict resolution**: if GDD changes require rebalancing the economy,
+  document the ripple effects across all currency tiers and progression
+  milestones; never adjust a single faucet or sink without analyzing the
+  system-wide impact on time-to-purchase and inflation trajectory

package/content/pipeline/specification/game-accessibility.md

@@ -0,0 +1,82 @@
+---
+name: game-accessibility
+description: Define accessibility features across visual, motor, cognitive, auditory, speech, and photosensitivity categories
+summary: "Creates an accessibility plan organized by Xbox Accessibility Guidelines (XAG) categories with implementation priorities, platform requirements, and CVAA compliance for communication features."
+phase: "specification"
+order: 861
+dependencies: [game-design-document]
+outputs: [docs/game-accessibility.md]
+conditional: null
+reads: []
+knowledge-base: [game-accessibility]
+---
+
+## Purpose
+Define a comprehensive game accessibility plan organized by Xbox Accessibility
+Guidelines (XAG) categories: visual, motor, cognitive, auditory, speech, and
+photosensitivity. Each category receives concrete feature requirements with
+implementation priority, platform-specific constraints, and compliance notes.
+
+Games have unique accessibility challenges compared to traditional software —
+real-time input demands, spatial audio reliance, color-coded gameplay feedback,
+and rapid visual effects all create barriers. This step produces an actionable
+accessibility plan that feeds into input-controls-spec, game-ui-spec, and
+implementation tasks.
+
+For games with online communication features, this step also documents CVAA
+(21st Century Communications and Video Accessibility Act) compliance
+requirements for text chat, voice chat, and video communication.
+
+## Inputs
+- docs/game-design.md (required) — mechanics, core loop, and interaction model
+- docs/plan.md (required) — target platforms and audience
+- docs/performance-budgets.md (optional) — platform constraints affecting accessibility features
+
+## Expected Outputs
+- docs/game-accessibility.md — accessibility plan with per-category features,
+  priorities, platform requirements, and compliance notes
+
+## Quality Criteria
+- (mvp) All six XAG categories addressed: visual, motor, cognitive, auditory, speech, photosensitivity
+- (mvp) Every accessibility feature has an implementation priority (P0-P3) and target milestone
+- (mvp) Remappable controls requirement documented (feeds input-controls-spec)
+- (mvp) Subtitle and caption requirements specified with size, contrast, and speaker identification
+- (mvp) Colorblind-safe palette requirement documented — no gameplay information conveyed by color alone
+- (deep) Platform-specific accessibility API integration documented (Xbox XAG, PlayStation accessibility toolkit, iOS/Android system settings)
+- (deep) CVAA compliance checklist for communication features (text chat, voice chat, video)
+- (deep) Difficulty and assist mode spectrum defined (speed reduction, aim assist, skip mechanics)
+- (deep) Photosensitivity analysis: flash frequency limits, screen-shake toggle, motion reduction mode
+
+## Methodology Scaling
+- **deep**: Full accessibility audit across all six XAG categories with
+  platform-specific API integration, CVAA compliance checklist, difficulty
+  spectrum design, photosensitivity analysis, and accessibility QA test
+  plan. 10-20 pages.
+- **mvp**: Core accessibility features: remappable controls, subtitle support,
+  colorblind mode, and font scaling. 2-4 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: remappable controls and subtitle requirements only.
+  - Depth 2: add colorblind-safe palette, font scaling, and audio cue alternatives.
+  - Depth 3: add difficulty/assist modes, screen reader menu support, and motor accessibility options.
+  - Depth 4: add platform-specific API integration, CVAA compliance, and photosensitivity analysis.
+  - Depth 5: full accessibility specification with QA test plan, conformance reporting template, and accessibility certification preparation.
+
+## Mode Detection
+Check for docs/game-accessibility.md. If it exists, operate in update mode:
+read existing accessibility plan and diff against current GDD mechanics. New
+mechanics may introduce new accessibility barriers. Preserve existing feature
+priorities and compliance decisions. Add accessibility requirements for any
+new mechanics or interaction patterns.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/game-accessibility.md exists
+- **Preserve**: existing feature priorities, platform API integration
+  decisions, CVAA compliance status, difficulty spectrum design
+- **Triggers for update**: GDD added new mechanics or interaction patterns,
+  target platforms changed, communication features added (triggers CVAA
+  review), performance budgets revised (may affect accessibility feature
+  feasibility)
+- **Conflict resolution**: if a new mechanic conflicts with an existing
+  accessibility requirement (e.g., color-dependent feedback), flag the
+  conflict and propose alternatives that preserve both gameplay intent and
+  accessibility; never silently remove accessibility features

package/content/pipeline/specification/game-ui-spec.md

@@ -0,0 +1,97 @@
+---
+name: game-ui-spec
+description: Specify HUD, menus, controller navigation, settings, FTUE, and UI state machines for games
+summary: "Replaces design-system and ux-spec for game projects. Covers UI visual tokens, HUD, menu hierarchy, controller navigation, settings screens, FTUE/tutorial, UI state machines, and responsive behavior."
+phase: "specification"
+order: 863
+dependencies: [game-accessibility, input-controls-spec, system-architecture]
+outputs: [docs/game-ui-spec.md]
+conditional: null
+reads: [game-design-document, economy-design, netcode-spec]
+knowledge-base: [game-ui-patterns, game-accessibility]
+---
+
+## Purpose
+Define the complete game UI specification, replacing both design-system and
+ux-spec for game projects. Traditional design systems focus on web/app
+component libraries; games need HUD elements, menu hierarchies with
+controller navigation, settings screens covering gameplay/audio/video/
+accessibility/controls, first-time user experience (FTUE) and tutorial flows,
+and UI state machines that respond to gameplay state transitions.
+
+This step covers: UI visual tokens (color palette, typography, iconography),
+HUD layout and information hierarchy, menu structure and navigation flow,
+controller and keyboard navigation patterns, settings screen categories and
+options, FTUE/tutorial design, UI state machines, and responsive behavior
+across target resolutions.
+
+**Note on forward-reads**: `economy-design` is listed as an optional read.
+On first generation it may not exist yet — in that case, define placeholder
+UI regions for economy-related elements (store, currency display, inventory
+value) and mark them with `<!-- pending: economy-design -->` for a future
+update pass. When economy-design becomes available, these placeholders are
+filled in during update mode.
+
+## Inputs
+- docs/game-design.md (required) — mechanics, core loop, game modes informing HUD and menu needs
+- docs/game-accessibility.md (required) — accessibility requirements for UI elements
+- docs/input-controls-spec.md (required) — input devices and navigation patterns
+- docs/system-architecture.md (required) — frontend architecture and rendering pipeline
+- docs/economy-design.md (optional, forward-read) — monetization and economy UI needs
+- docs/netcode-spec.md (optional, forward-read) — multiplayer UI states (lobby, matchmaking, connection status)
+
+## Expected Outputs
+- docs/game-ui-spec.md — complete game UI specification with visual tokens,
+  HUD, menus, navigation, settings, FTUE, state machines, and responsive
+  behavior
+
+## Quality Criteria
+- (mvp) UI visual tokens defined: color palette (with colorblind-safe variants), typography scale, icon set conventions
+- (mvp) HUD layout documented with information hierarchy — critical info (health, ammo) vs contextual info (objectives, minimap) vs ambient info (score, timer)
+- (mvp) Menu hierarchy defined: main menu, pause menu, settings, and all submenus with navigation flow
+- (mvp) Controller navigation specified for every menu screen — focus order, wrap behavior, shortcut buttons
+- (mvp) Settings categories defined: gameplay, video, audio, controls, accessibility (minimum)
+- (mvp) FTUE/tutorial flow documented — what is taught, when, and how (contextual prompts vs dedicated tutorial)
+- (deep) UI state machines defined for each major UI context (HUD, pause, inventory, store, multiplayer lobby)
+- (deep) Responsive behavior documented per target resolution (TV/monitor distances, handheld, mobile)
+- (deep) Platform shell integration specified (console system UI overlays, achievement popups, friend invites)
+- (deep) Localization requirements: text expansion buffers, RTL layout support, font fallback chains
+- (deep) UI performance budgets: draw call limits for UI layer, texture atlas strategy, UI update frequency
+
+## Methodology Scaling
+- **deep**: Full game UI specification with visual token system, detailed HUD
+  wireframe descriptions, complete menu hierarchy with controller navigation
+  maps, comprehensive settings screens, FTUE flow with branching for player
+  experience level, UI state machines for all contexts, responsive behavior
+  matrix, platform shell integration, localization plan, and UI performance
+  budgets. 20-35 pages.
+- **mvp**: Visual tokens, HUD layout, menu hierarchy, basic controller
+  navigation, and settings categories. 5-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: HUD information hierarchy and main menu structure only.
+  - Depth 2: add visual tokens, settings categories, and basic controller navigation.
+  - Depth 3: add FTUE flow, pause menu, all submenu screens, and responsive behavior per resolution.
+  - Depth 4: add UI state machines, platform shell integration, localization requirements, and economy UI regions.
+  - Depth 5: full specification with UI performance budgets, accessibility audit of every screen, animation/transition specs for UI, and multiplayer lobby UI flows.
+
+## Mode Detection
+Check for docs/game-ui-spec.md. If it exists, operate in update mode: read
+existing spec and diff against current GDD, accessibility plan, and input
+spec. Preserve existing HUD layout, menu hierarchy, and visual tokens.
+Update or add UI elements for new mechanics, new settings options for new
+accessibility features, and economy UI placeholders when economy-design
+becomes available.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/game-ui-spec.md exists
+- **Preserve**: existing visual tokens, HUD layout, menu hierarchy, controller
+  navigation patterns, FTUE flow, UI state machines
+- **Triggers for update**: GDD added new mechanics requiring HUD elements or
+  new menus, accessibility plan added new requirements, input-controls-spec
+  changed navigation patterns, economy-design created (fill placeholder
+  regions), netcode-spec created (add multiplayer UI states), system
+  architecture changed rendering pipeline
+- **Conflict resolution**: if a new HUD element competes for screen space
+  with an existing element, document the conflict with information hierarchy
+  analysis and propose resolution (overlay, toggle, contextual show/hide);
+  never silently remove HUD elements that players rely on for gameplay