@zigrivers/scaffold 3.4.1 → 3.5.1

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

@@ -0,0 +1,142 @@
+---
+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
+- (mvp) Type-specific deliverable produced matching the identified content structure trait: level-designs.md (discrete), world-regions.md (open-world), generation-rulesets.md (procedural), escalation-bands.md (endless), or mission-templates.md (mission-based)
+
+## 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,105 @@
+---
+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
+- (mvp) If the economy involves online transactions: server-authoritative transaction model specified — client cannot dictate transaction outcomes
+
+## 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

package/content/pipeline/specification/input-controls-spec.md

@@ -0,0 +1,81 @@
+---
+name: input-controls-spec
+description: Specify input bindings, rebinding, haptics, dead zones, and cross-play input fairness
+summary: "Documents default bindings per device, input abstraction layer, rebinding system, dead zones, aim assist, haptics, controller disconnect behavior, and accessibility input requirements."
+phase: "specification"
+order: 862
+dependencies: [game-design-document, game-accessibility]
+outputs: [docs/input-controls-spec.md]
+conditional: null
+reads: []
+knowledge-base: [game-input-systems, game-vr-ar-design]
+---
+
+## Purpose
+Specify the complete input system for the game: default bindings per input
+device (keyboard/mouse, gamepad, touch, motion), the input abstraction layer
+that maps physical inputs to gameplay actions, the rebinding and
+customization system, analog tuning (dead zones, sensitivity curves, aim
+assist), haptic feedback design, controller disconnect behavior, and
+accessibility-driven input requirements from the accessibility plan.
+
+This step bridges the GDD's gameplay mechanics and the accessibility plan
+into a concrete input specification that implementation can build directly
+from. Every mechanic in the GDD should trace to at least one input action
+documented here.
+
+## Inputs
+- docs/game-design.md (required) — mechanics and interaction verbs requiring input bindings
+- docs/game-accessibility.md (required) — remappable controls requirements, motor accessibility needs
+- docs/plan.md (required) — target platforms and supported input devices
+- docs/performance-budgets.md (optional) — input latency budgets
+
+## Expected Outputs
+- docs/input-controls-spec.md — input bindings, abstraction layer, rebinding
+  system, analog tuning, haptics, disconnect behavior, and accessibility
+  input requirements
+
+## Quality Criteria
+- (mvp) Default binding table per supported input device (keyboard/mouse, gamepad, touch) with every GDD mechanic mapped to an input action
+- (mvp) Input abstraction layer defined — actions are named semantically (e.g., "jump", "interact") not by physical key
+- (mvp) Rebinding system requirements specified per accessibility plan
+- (mvp) Controller disconnect behavior defined (pause, AI takeover, timeout)
+- (deep) Dead zone and sensitivity curve specifications per analog input (stick, trigger)
+- (deep) Aim assist parameters documented (magnetism strength, slowdown radius, snap-to-target rules) with per-input-device tuning
+- (deep) Haptic feedback map: gameplay events to vibration patterns (intensity, duration, motor selection)
+- (deep) Cross-play input fairness: input-based matchmaking rules, aim assist parity between input types
+- (deep) Simultaneous input handling documented (keyboard + mouse + gamepad hot-switching)
+
+## Methodology Scaling
+- **deep**: Full input specification with binding tables per device, abstraction
+  layer architecture, rebinding UI wireframe descriptions, dead zone curves,
+  aim assist tuning parameters, haptic feedback map, cross-play fairness
+  rules, accessibility input matrix, and input latency budget. 10-20 pages.
+- **mvp**: Default bindings per device, action abstraction layer, rebinding
+  support flag, and controller disconnect behavior. 3-5 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: action list with default keyboard/mouse and gamepad bindings only.
+  - Depth 2: add input abstraction layer design and rebinding requirements.
+  - Depth 3: add dead zones, sensitivity curves, controller disconnect behavior, and touch bindings.
+  - Depth 4: add aim assist parameters, haptic feedback map, and cross-play input fairness rules.
+  - Depth 5: full specification with input latency budgets, simultaneous input hot-switching, accessibility input matrix, and platform certification input requirements.
+
+## Mode Detection
+Check for docs/input-controls-spec.md. If it exists, operate in update mode:
+read existing bindings and diff against current GDD mechanics. New mechanics
+may require new input actions. Preserve existing binding defaults and player
+muscle memory conventions. Add bindings for new mechanics without disrupting
+established controls.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/input-controls-spec.md exists
+- **Preserve**: existing default bindings, dead zone values, aim assist
+  tuning, haptic patterns, rebinding system design
+- **Triggers for update**: GDD added new mechanics requiring new input
+  actions, accessibility plan updated motor requirements, target platforms
+  changed (new input devices), performance budgets revised input latency
+  targets
+- **Conflict resolution**: if a new mechanic's ideal binding conflicts with
+  an existing binding, document both the conflict and recommended resolution
+  (rebind the new action, not the established one); never silently reassign
+  bindings that players may have committed to muscle memory

package/content/pipeline/specification/localization-plan.md

@@ -0,0 +1,113 @@
+---
+name: localization-plan
+description: Plan target languages, string management, font support (CJK/RTL), UI text expansion, VO localization, cultural adaptation, and LQA
+summary: "Plans the localization strategy — target languages and tiers, string management pipeline, font support for CJK and RTL scripts, UI text expansion handling (~30% for German), voice-over localization approach, cultural adaptation guidelines, and linguistic QA process."
+phase: "specification"
+order: 874
+dependencies: [game-design-document]
+outputs: [docs/localization-plan.md]
+conditional: "if-needed"
+reads: [game-ui-spec, narrative-bible]
+knowledge-base: [game-localization]
+---
+
+## Purpose
+Plan the localization strategy — the systematic process of adapting the game
+for multiple languages and cultures. Localization is not translation: it
+encompasses string management infrastructure, font and text rendering for
+diverse scripts, UI layout adaptation for text expansion, voice-over
+production across languages, cultural sensitivity review, and a quality
+assurance process that validates every localized build.
+
+Localization decisions have deep technical implications that must be resolved
+before content production begins. String externalization must be built into
+the code architecture — retrofitting it after thousands of hardcoded strings
+exist is prohibitively expensive. Font atlases must support target scripts
+(CJK characters alone require thousands of glyphs). UI layouts must
+accommodate text expansion (German text is typically 30% longer than English;
+some languages expand by 50% or more). Right-to-left (RTL) scripts (Arabic,
+Hebrew) require mirrored UI layouts. These are not cosmetic adjustments —
+they are architectural requirements that affect every system touching text.
+
+Three localization depth tiers exist:
+
+1. **Text-only localization**: All in-game text is translated, but audio
+   remains in the original language (with subtitles). Most cost-effective,
+   suitable for indie and mid-scale games.
+2. **Partial VO localization**: Text is fully translated, and key narrative
+   audio (cinematics, main story) is re-recorded in target languages. Secondary
+   audio (barks, incidental dialogue) uses original language with subtitles.
+3. **Full VO localization**: All spoken content is re-recorded in every target
+   language. Highest cost, required for AAA titles targeting global markets.
+
+## Conditional Evaluation
+Enable when: the project config indicates more than one supported locale
+(`supportedLocales.length > 1`) — the game will ship in multiple languages,
+requiring string externalization, font support, UI adaptation, and a
+localization pipeline.
+
+Skip when: the game ships in a single language only. Games with no text (pure
+visual/musical experiences) or games explicitly scoped to one market with no
+localization plans do not need this specification.
+
+## Inputs
+- docs/game-design.md (required) — narrative scope, text volume, VO volume, cultural setting informing adaptation needs
+- docs/plan.md (required) — target markets and languages, localization budget and timeline constraints
+- docs/game-ui-spec.md (optional, forward-read) — UI layout system, text rendering approach, font pipeline
+- docs/narrative-bible.md (optional, forward-read) — dialogue volume, character voice profiles, cultural references requiring adaptation
+
+## Expected Outputs
+- docs/localization-plan.md — target languages, string management pipeline,
+  font strategy, UI adaptation guidelines, VO localization approach, cultural
+  adaptation process, and LQA plan
+
+## Quality Criteria
+- (mvp) Target languages listed with priority tiers: Tier 1 (ship languages), Tier 2 (post-launch), Tier 3 (community-contributed), with rationale for each tier based on market analysis
+- (mvp) String management pipeline specified: string externalization format (JSON, XLIFF, PO, proprietary), key naming convention, pluralization and gender rules, interpolation/variable syntax, context annotations for translators
+- (mvp) Font strategy documented: font families per script category (Latin, CJK, Cyrillic, Arabic, Devanagari), font atlas generation pipeline, fallback chain, dynamic font loading for memory-constrained platforms
+- (mvp) UI text expansion handling: layout system accommodates 30-50% text growth, truncation and overflow strategy, minimum touch targets preserved regardless of text length, RTL layout mirroring plan (if applicable)
+- (mvp) Localization build pipeline: how localized assets are packaged (per-language bundles, on-demand download, embedded), language switching at runtime (restart required vs hot-swap)
+- (deep) VO localization plan: localization depth per language (text-only, partial VO, full VO), casting direction per language, lip-sync adaptation approach (re-animation, procedural, blend shapes), recording specification (sample rate, format, naming)
+- (deep) Cultural adaptation guidelines: content sensitivity review process, region-specific content variants (violence/gore rating adjustments, culturally inappropriate symbols, color symbolism), legal requirements per market (age rating localization, loot box probability disclosure language)
+- (deep) LQA (Linguistic Quality Assurance) process: in-context review workflow (translators play the build), bug taxonomy (truncation, overlap, mistranslation, placeholder visible, encoding error), severity levels, sign-off criteria per language
+- (deep) Translation memory and terminology management: TM/glossary tooling, term consistency enforcement, brand name and proper noun lock lists, style guide per language
+- (deep) Pseudolocalization testing: automated pseudo-loc pass (accented characters, text expansion simulation, RTL simulation) integrated into CI, visual regression testing for localized UI
+
+## Methodology Scaling
+- **deep**: Full localization plan covering tiered language strategy, string
+  management with TM/glossary tooling, comprehensive font strategy for all
+  target scripts, UI adaptation with RTL support, VO localization with lip-sync
+  plan, cultural adaptation guidelines, LQA process with in-context review,
+  pseudolocalization in CI, and localization analytics. 15-25 pages.
+- **mvp**: Target languages, string externalization format, font strategy for
+  primary scripts, UI text expansion guidelines, and basic localization build
+  pipeline. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: target language list and string externalization format only.
+  - Depth 2: add font strategy, UI text expansion handling, and localization build pipeline.
+  - Depth 3: add VO localization plan, cultural adaptation guidelines, and pluralization/gender rule system.
+  - Depth 4: add LQA process, translation memory tooling, RTL layout mirroring, and pseudolocalization testing.
+  - Depth 5: full specification with localization analytics (translation coverage, LQA defect rates, language launch readiness dashboard), community translation infrastructure, and per-region content variant management.
+
+## Mode Detection
+Check for docs/localization-plan.md. If it exists, operate in update mode:
+read existing plan and diff against current GDD language targets and narrative
+scope. Preserve existing string management format, font strategy, and VO
+decisions. Update target language tiers if market analysis changed. Add font
+support for new scripts if languages added require them.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/localization-plan.md exists
+- **Preserve**: string management format and key naming convention, font
+  families and atlas generation pipeline, VO localization depth per language,
+  LQA process and bug taxonomy, cultural adaptation decisions
+- **Triggers for update**: GDD changed target markets or added languages,
+  narrative-bible changed dialogue volume or added culturally sensitive content,
+  game-ui-spec changed text rendering or layout system, VO scope changed
+  (text-only to partial VO, or partial to full), new platform added with
+  different font or text rendering constraints
+- **Conflict resolution**: if adding a new target language requires a script
+  not currently supported by the font pipeline (e.g., adding Thai requires
+  complex text shaping), document the font engineering cost explicitly and
+  propose a phased approach — never add a language to the target list without
+  confirming the text rendering pipeline can support its script requirements