@zigrivers/scaffold 3.4.1 → 3.5.1

package/README.md

@@ -356,6 +356,97 @@ scaffold dashboard           # open a visual progress dashboard in your browser
 - **The pipeline is a guide, not a cage.** Skip steps that don't apply (`scaffold skip <step> --reason "..."`). Run them out of order if you know what you're doing. Scaffold tracks dependencies so it'll tell you if you're missing a prerequisite.
 - **Depth controls thoroughness.** Each step runs at a depth from 1 (focused, fast) to 5 (exhaustive). The mvp preset defaults to depth 1; deep defaults to 5. You can override per step or per session: `"Use depth 3 for everything"`.
 
+### Game Development
+
+Scaffold fully supports game development projects. When you select `game` as your project type, a **project-type overlay** activates 24 game-specific pipeline steps and injects game domain expertise into existing steps — all while keeping the standard pipeline workflow (status, next, rework, multi-model review) fully functional.
+
+#### Getting Started
+
+```bash
+# Interactive — the wizard asks about your engine, multiplayer, platforms, etc.
+scaffold init
+
+# Non-interactive with defaults (engine: custom, single-player, PC)
+scaffold init --project-type game --auto
+
+# Non-interactive with specific methodology
+scaffold init --project-type game --methodology deep --auto
+
+# Adopt an existing game project (auto-detects Unity/Unreal/Godot)
+scaffold adopt
+```
+
+#### How It Works
+
+Game support uses a **project-type overlay** architecture. You choose your methodology normally (`mvp`, `deep`, or `custom`), then `projectType: game` layers on top:
+
+- **Enables 24 game steps** — GDD, performance budgets, art bible, audio design, etc.
+- **Disables 3 web-centric steps** — `design-system`, `ux-spec`, `review-ux` (replaced by `game-ui-spec`)
+- **Injects 29 game knowledge entries** into existing steps (e.g., game engine evaluation into `tech-stack`, game testing patterns into `tdd`)
+- **Remaps artifact references** so downstream steps read game-specific docs instead of web ones
+
+A game jam project uses `mvp` + game overlay (fewer steps, lower depth). An AAA project uses `deep` + game overlay (all steps, max depth).
+
+#### Game Configuration
+
+During `scaffold init`, the wizard asks game-specific questions with progressive disclosure:
+
+| Category | Questions |
+|----------|-----------|
+| **Core** (always asked) | Game engine (Unity/Unreal/Godot/custom), multiplayer mode (none/local/online/hybrid), target platforms (PC/console/mobile/VR/AR) |
+| **Conditional** | Online services (if multiplayer), content structure (levels/open-world/procedural/endless), economy type (none/progression/monetized) |
+| **Advanced** (opt-in) | Narrative depth, supported locales, NPC AI complexity, mod support, persistence model |
+
+These answers control which conditional steps activate. A single-player puzzle game gets a different pipeline than a multiplayer live-service RPG.
+
+#### Game Pipeline Steps
+
+**Always enabled** (12 steps):
+
+| Step | Phase | What It Produces |
+|------|-------|-----------------|
+| `game-design-document` | Pre | Game pillars, core loop, mechanics catalog, progression systems |
+| `review-gdd` | Pre | Multi-pass review of GDD for pillar coherence, scope feasibility |
+| `performance-budgets` | Foundation | Frame budgets, memory budgets, GPU limits, loading targets per platform |
+| `game-accessibility` | Specification | XAG-aligned accessibility plan (visual, motor, cognitive, auditory) |
+| `input-controls-spec` | Specification | Input bindings, rebinding, haptics, dead zones, cross-play fairness |
+| `game-ui-spec` | Specification | HUD, menus, controller navigation, settings, FTUE/tutorial, UI states |
+| `review-game-ui` | Specification | Multi-pass review of game UI for completeness and accessibility |
+| `content-structure-design` | Specification | Level layouts, world regions, procedural rulesets, or mission templates |
+| `art-bible` | Specification | Art style, asset specs, naming conventions, DCC pipeline, LOD strategy |
+| `audio-design` | Specification | Audio direction, adaptive music, spatial audio, middleware config, VO |
+| `playtest-plan` | Quality | Playtest types, schedule, feedback templates, balance testing |
+| `analytics-telemetry` | Quality | Event taxonomy, crash telemetry, data pipeline, privacy compliance |
+
+**Conditional** (12 steps — activated by your game configuration):
+
+| Step | Activates When | What It Produces |
+|------|---------------|-----------------|
+| `narrative-bible` | Narrative is light/heavy | World lore, characters, dialogue systems, branching narrative |
+| `netcode-spec` | Multiplayer is online/hybrid | Network topology, tick rate, prediction, lag compensation, anti-cheat |
+| `review-netcode` | Netcode spec enabled | Latency tolerance, bandwidth, cheat resistance review |
+| `ai-behavior-design` | NPC AI is simple/complex | Behavior trees, pathfinding, perception, difficulty scaling |
+| `economy-design` | Economy is not none | Currencies, loot tables, monetization, legal compliance |
+| `review-economy` | Economy design enabled | Inflation analysis, exploit detection, ethical monetization review |
+| `online-services-spec` | Online services selected | Identity, leaderboards, matchmaking, moderation, cloud save |
+| `modding-ugc-spec` | Mod support enabled | Mod API, sandboxing, distribution, content moderation |
+| `save-system-spec` | Persistence is not none | Save format, cloud sync, corruption recovery, migration |
+| `localization-plan` | Multiple locales | String management, fonts (CJK/RTL), VO localization, LQA |
+| `live-ops-plan` | Live-ops selected | Content cadence, events, hotfix deployment, maintenance |
+| `platform-cert-prep` | Console/mobile/VR targets | Sony TRC, Xbox XR, Nintendo Lotcheck, store compliance checklists |
+
+#### Engine Detection
+
+`scaffold adopt` automatically detects game engines in existing projects:
+
+| Engine | Detection Signal |
+|--------|-----------------|
+| Unity | `Assets/*.meta` files |
+| Unreal | `*.uproject` file |
+| Godot | `project.godot` file |
+
+When detected, `scaffold adopt` sets `projectType: game` and `gameConfig.engine` in your config, enabling the full game overlay.
+
 ## The Pipeline
 
 ### Phase 0 — Product Vision (vision)

package/content/knowledge/game/game-accessibility.md

@@ -0,0 +1,328 @@
+---
+name: game-accessibility
+description: Xbox Accessibility Guidelines as best-practice guidance, game-specific a11y categories, CVAA scope, and low-cost high-impact features
+topics: [game-dev, accessibility, xag, cvaa, colorblind, remapping]
+---
+
+Game accessibility is about removing barriers that prevent players with disabilities from experiencing your game. The Xbox Accessibility Guidelines (XAG) provide the most comprehensive industry framework — not as a legal compliance checklist, but as best-practice guidance that Microsoft explicitly positions as aspirational. Every feature you implement opens your game to more players, and many accessibility features (subtitles, remapping, difficulty options) benefit all players regardless of ability.
+
+## Summary
+
+### XAG as Best-Practice Guidance (Not Compliance)
+
+The Xbox Accessibility Guidelines are published by Microsoft as voluntary guidance. They are NOT certification requirements, NOT legal mandates, and NOT a pass/fail checklist. Microsoft explicitly states that XAG is aspirational — studios should implement what makes sense for their game and audience. Treating XAG as a rigid compliance framework leads to "compliance theater" where teams check boxes without improving actual player experience.
+
+That said, XAG is the best-organized accessibility framework in games. It covers 23 guidelines across categories that map directly to disability types. Use it as a design reference and prioritization tool, not a certification gate.
+
+### CVAA: Scope Is Communication Features Only
+
+The 21st Century Communications and Video Accessibility Act (CVAA) applies specifically to communication features in games — voice chat, text chat, video chat, and related UI. If your game has no communication features, CVAA has minimal direct applicability. Games with voice or text chat must provide accessible alternatives (text-to-speech for chat, speech-to-text, visual indicators for voice activity). The FCC enforces CVAA, and waivers can be requested but require documented justification.
+
+### Accessibility Categories
+
+Game accessibility spans six distinct areas, each addressing different disability types:
+
+- **Visual**: Colorblind modes, high-contrast options, UI scaling, screen reader support, audio cues for visual events
+- **Motor**: Input remapping, one-handed play, hold-vs-toggle options, copilot mode, adjustable timing windows
+- **Cognitive**: Difficulty as accessibility, objective reminders, simplified UI modes, content warnings, adjustable game speed
+- **Auditory**: Subtitles with speaker identification, visual sound indicators, adjustable subtitle size, mono audio option
+- **Speech**: Text-to-speech for voice chat, ping systems as voice alternatives, preset communication phrases
+- **Photosensitivity**: Flash reduction, screen shake controls, motion reduction, high-contrast mode
+
+### Low-Cost High-Impact Features
+
+Not all accessibility features require massive engineering effort. The following have the best effort-to-impact ratio:
+
+- Subtitle options with size/background controls (benefits 15%+ of players)
+- Input remapping (often provided by engine frameworks)
+- Colorblind mode (affects ~8% of males, ~0.5% of females)
+- Hold-vs-toggle option for sustained inputs
+- UI text scaling
+- Screen shake intensity slider
+- Difficulty options with granular controls
+
+## Deep Guidance
+
+### Visual Accessibility
+
+Visual accessibility addresses blindness, low vision, and color vision deficiency. Color vision deficiency (colorblind) is the most common — affecting approximately 1 in 12 males and 1 in 200 females — but low vision and full blindness require different solutions.
+
+**Color vision deficiency (colorblind support):**
+
+The three main types are deuteranopia (red-green, most common), protanopia (red-green, less common), and tritanopia (blue-yellow, rare). Never use color alone to convey critical information. Every color-coded element should have a secondary differentiator: shape, pattern, label, or icon.
+
+```typescript
+// Colorblind-safe design pattern: never rely on color alone
+interface GameMarker {
+  color: string;         // Primary visual cue
+  shape: MarkerShape;    // Secondary cue — always present
+  label: string;         // Tertiary cue — screen reader accessible
+  pattern?: string;      // Optional pattern fill for map elements
+}
+
+type MarkerShape = "circle" | "triangle" | "square" | "diamond" | "star";
+
+// BAD: Only color distinguishes teams
+const badTeamIndicators = {
+  friendly: { color: "#00FF00" },  // Green
+  enemy: { color: "#FF0000" },     // Red — indistinguishable for deuteranopia
+};
+
+// GOOD: Color + shape + label
+const goodTeamIndicators = {
+  friendly: { color: "#00FF00", shape: "circle" as MarkerShape, label: "Friendly" },
+  enemy: { color: "#FF0000", shape: "diamond" as MarkerShape, label: "Enemy" },
+};
+
+// Colorblind mode palette swaps
+// These palettes are designed to be distinguishable across all three
+// major types of color vision deficiency
+const colorblindPalettes = {
+  deuteranopia: {
+    friendly: "#1B9E77",  // Teal (replaces green)
+    enemy: "#D95F02",     // Orange (replaces red)
+    neutral: "#7570B3",   // Purple
+    highlight: "#E6AB02", // Gold
+  },
+  protanopia: {
+    friendly: "#0072B2",  // Blue
+    enemy: "#E69F00",     // Amber
+    neutral: "#CC79A7",   // Pink
+    highlight: "#F0E442", // Yellow
+  },
+  tritanopia: {
+    friendly: "#009E73",  // Green
+    enemy: "#D55E00",     // Vermillion
+    neutral: "#56B4E9",   // Sky blue
+    highlight: "#CC79A7", // Pink
+  },
+};
+```
+
+**High-contrast mode:**
+
+Provide an option that increases contrast between game elements and backgrounds. This does not mean making everything black and white — it means ensuring foreground elements (characters, interactables, UI) have sufficient contrast against their surroundings. A dedicated high-contrast mode might add outlines, increase UI opacity, or simplify background detail.
+
+**UI scaling:**
+
+All text and UI elements should scale independently of render resolution. Minimum text size should be 28px at 1080p (per XAG guidance). Provide a UI scale slider from 75% to 200%. HUD elements should reflow or stack at larger scales rather than overlapping.
+
+**Screen reader support:**
+
+For menu navigation, screen readers need semantic structure: focusable elements with descriptive labels, logical tab order, and state announcements (selected, disabled, expanded). Most engines do not provide this natively — it requires a custom narration layer that reads UI element text via TTS.
+
+### Motor Accessibility
+
+Motor accessibility covers a wide spectrum from reduced dexterity to full paralysis. The common thread is that players may not be able to use standard input methods in standard ways.
+
+**Input remapping:**
+
+Full input remapping is the single most impactful motor accessibility feature. Every bindable action should be remappable to any button or key. Support modifier keys (Shift+X, Ctrl+A). Allow multiple inputs bound to the same action. Allow one input bound to multiple actions (player's choice to accept conflicts).
+
+```yaml
+# Remapping configuration structure
+input_remapping:
+  # Every game action is remappable
+  actions:
+    - name: jump
+      default_keyboard: Space
+      default_gamepad: A
+      remappable: true
+      category: movement
+
+    - name: interact
+      default_keyboard: E
+      default_gamepad: X
+      remappable: true
+      category: actions
+
+    - name: fire
+      default_keyboard: LeftMouse
+      default_gamepad: RightTrigger
+      remappable: true
+      category: combat
+      # Hold-vs-toggle is per-action, not global
+      input_mode: [hold, toggle]
+      default_mode: hold
+
+  # Global motor accessibility options
+  motor_options:
+    hold_to_toggle:
+      description: "Convert any sustained-press action to a toggle"
+      applies_to: [sprint, aim, crouch, fire]
+      default: false
+
+    copilot_mode:
+      description: "Two controllers act as one — second player assists"
+      enabled: false
+      # Both controllers send input; game merges them
+      # No actions are exclusive to either controller
+
+    auto_sprint:
+      description: "Sprint activates automatically when stick is fully tilted"
+      default: false
+
+    aim_assist_strength:
+      description: "Adjustable aim assist from 0 (off) to 100 (maximum)"
+      range: [0, 100]
+      default: 50
+
+    qte_auto_complete:
+      description: "Quick-time events complete automatically"
+      default: false
+
+    timing_window_multiplier:
+      description: "Multiplier for all timing-based inputs"
+      range: [1.0, 5.0]
+      default: 1.0
+```
+
+**One-handed play:**
+
+Support playing with one hand by allowing all essential actions to be bound to one side of the controller or keyboard. For gamepad, this means binding movement and camera to the same stick (with toggle) or using gyro for camera. For keyboard, bind everything to the left hand region (WASD + surrounding keys).
+
+**Copilot mode:**
+
+Xbox's copilot feature lets two controllers act as a single input. The game receives merged input from both. This lets a helper (parent, caregiver, friend) assist with actions the primary player cannot perform. The game does not need to implement copilot itself — Xbox provides it at the OS level — but the game must not break when receiving input from two devices simultaneously.
+
+### Cognitive Accessibility
+
+Cognitive accessibility helps players with learning disabilities, ADHD, autism, brain injuries, or simply unfamiliarity with game conventions.
+
+**Difficulty as accessibility:**
+
+Difficulty options are an accessibility feature, not a concession. Granular difficulty controls (separate sliders for enemy damage, player health, puzzle hints, timer length) are more accessible than a single Easy/Normal/Hard toggle. Players should be able to change difficulty at any time without penalty.
+
+**Objective reminders and guidance:**
+
+Players who lose track of objectives should be able to request a reminder at any time (waypoint, journal entry, NPC dialogue hint). Avoid punishing players for taking long breaks between sessions — provide session-start recaps or "story so far" summaries.
+
+**Content warnings:**
+
+Provide warnings for potentially distressing content (flashing lights, spiders, gore, loud sounds). Allow players to skip or modify these elements where possible. Content warnings are especially important for players with PTSD or anxiety disorders.
+
+### Auditory Accessibility
+
+**Subtitles best practices:**
+
+Subtitles should include speaker identification (name or color-coded labels, with shape differentiators for colorblind players). Provide background adjustable from transparent to fully opaque. Support size scaling from small to extra-large. Position subtitles consistently. For environmental audio, provide descriptive captions: "[explosion in distance]", "[footsteps approaching from left]".
+
+```typescript
+// Subtitle system configuration
+interface SubtitleOptions {
+  enabled: boolean;
+  size: "small" | "medium" | "large" | "extra-large";
+  // Font sizes at 1080p (scale proportionally at other resolutions)
+  // small: 24px, medium: 32px, large: 42px, extra-large: 56px
+
+  background: "transparent" | "semi-transparent" | "opaque";
+  // semi-transparent: rgba(0, 0, 0, 0.6)
+  // opaque: rgba(0, 0, 0, 0.9)
+
+  speakerIdentification: boolean;
+  // When true, prefix each line with speaker name in their assigned color
+  // "ELENA: We need to move, now."
+
+  directionIndicator: boolean;
+  // When true, show arrow or label indicating sound direction
+  // "[LEFT] ELENA: We need to move, now."
+
+  environmentalCaptions: boolean;
+  // When true, also display non-speech audio
+  // "[distant gunfire]", "[door creaks open]"
+
+  letterboxSafe: boolean;
+  // When true, position subtitles above any letterbox bars
+  // Prevents subtitles from being hidden during cutscenes
+}
+
+// Default configuration — accessible out of the box
+const defaultSubtitles: SubtitleOptions = {
+  enabled: true,          // On by default per XAG guidance
+  size: "medium",
+  background: "semi-transparent",
+  speakerIdentification: true,
+  directionIndicator: false,
+  environmentalCaptions: false,
+  letterboxSafe: true,
+};
+```
+
+**Visual sound indicators:**
+
+For deaf and hard-of-hearing players, provide visual representations of important game sounds. A radial indicator around the crosshair showing the direction and type of nearby sounds (footsteps, gunfire, voice) is the most common pattern. Sound visualization should be optional and non-distracting for players who do not need it.
+
+**Mono audio:**
+
+Players who are deaf in one ear lose spatial audio cues entirely with stereo output. A mono audio option collapses stereo/surround to a single channel, ensuring no audio information is lost. This should be a simple toggle.
+
+### Speech Accessibility
+
+**Alternatives to voice communication:**
+
+Not all players can or want to use voice chat. Provide robust alternatives:
+
+- Ping system: contextual pings (enemy here, go here, need help, danger) that communicate essential information without speech
+- Preset phrases: quick-select wheel of common callouts mapped to a button
+- Text-to-speech: read typed chat messages aloud to teammates
+- Speech-to-text: transcribe voice chat for players who cannot hear it
+
+### Photosensitivity
+
+Photosensitive epilepsy affects approximately 1 in 4,000 people. Game-triggered seizures are a liability and a safety concern.
+
+**Flash reduction:**
+
+Avoid rapid flashing patterns (more than 3 flashes per second in any 1-second period). When flashing effects are essential (explosions, lightning), reduce their intensity and frequency. Provide a "reduce flashing" option that dims or removes strobing effects.
+
+**Screen shake and camera motion:**
+
+Provide separate intensity sliders for screen shake (0-100%) and camera motion/bobbing (0-100%). Default values should be moderate. A motion sensitivity option that reduces all camera-driven motion effects to zero should be available.
+
+### Implementation Priority Matrix
+
+Not every feature is equally costly or impactful. Prioritize by effort-to-impact ratio:
+
+```markdown
+| Priority | Feature                        | Effort | Impact | Notes                            |
+|----------|--------------------------------|--------|--------|----------------------------------|
+| P0       | Subtitle options               | Low    | High   | Benefits 15%+ of all players     |
+| P0       | Input remapping                | Low    | High   | Engine frameworks often support   |
+| P0       | Colorblind mode                | Low    | High   | 8% of males affected             |
+| P1       | Hold-vs-toggle                 | Low    | Medium | Per-action, not global toggle     |
+| P1       | UI text scaling                | Medium | High   | Requires UI reflow support        |
+| P1       | Difficulty granularity         | Medium | High   | Separate sliders per dimension    |
+| P1       | Screen shake slider            | Low    | Medium | Trivial to implement              |
+| P2       | High-contrast mode             | Medium | Medium | Outline shaders, UI opacity       |
+| P2       | Visual sound indicators        | Medium | Medium | Radial indicator UI element       |
+| P2       | Mono audio                     | Low    | Low    | Simple audio mix change           |
+| P2       | Environmental captions         | High   | Medium | Requires tagging all sound events |
+| P3       | Screen reader / TTS menus      | High   | Medium | Custom narration layer needed     |
+| P3       | Copilot mode                   | Low    | Low    | Xbox provides OS-level; test only |
+| P3       | One-handed presets             | Medium | Low    | Remap presets + UI                |
+```
+
+### Testing Accessibility Features
+
+Accessibility features must be tested — not just implemented and forgotten.
+
+**Manual testing protocols:**
+- Play through the first 30 minutes with each colorblind simulation filter active (most GPUs provide built-in simulation)
+- Complete key gameplay sequences using only a keyboard (no mouse) and only a gamepad
+- Complete key gameplay sequences with audio muted — verify all critical information has visual representation
+- Test subtitle readability at minimum and maximum text sizes on both TV (3-meter viewing) and monitor (0.5-meter viewing) distances
+- Invite players with disabilities to playtest — automated testing cannot replace lived experience
+
+**Automated validation:**
+- Contrast ratio checking for all UI text (WCAG AA minimum: 4.5:1 for normal text, 3:1 for large text)
+- Flash detection in cutscenes and VFX (automated tools can flag sequences exceeding 3 flashes/second)
+- Input binding validation: ensure every game action has at least one binding in every remapping preset
+- UI overlap detection at maximum text scale
+
+### Common Pitfalls
+
+- **Colorblind "filter" overlays**: Applying a post-process color filter to the entire screen is inferior to designing distinct visual elements from the start. Filters make the whole game look washed out. Instead, use distinct shapes, patterns, and labels alongside color.
+- **Subtitles off by default**: XAG recommends subtitles ON by default or prompted during first launch. Many players who need subtitles do not know where to find the option.
+- **Binary difficulty**: "Easy or Hard" does not serve accessibility. A player who cannot execute rapid button presses but has no cognitive limitations needs different accommodations than a player who needs simpler puzzle solutions.
+- **Inaccessible menus**: If the options menu itself is not accessible (tiny text, no keyboard navigation, no screen reader), players cannot even enable the accessibility features.
+- **Testing only with default settings**: Every accessibility feature must be tested in combination with gameplay. Colorblind mode + high contrast + large text + remapped controls — do they all work together?