@zigrivers/scaffold 3.4.1 → 3.5.0

package/content/methodology/custom-defaults.yml

@@ -81,3 +81,28 @@ steps:
   multi-agent-resume: { enabled: true }
   quick-task: { enabled: true }
   new-enhancement: { enabled: true }
+  # Game development steps (enabled via game overlay)
+  game-design-document: { enabled: false }
+  review-gdd: { enabled: false }
+  performance-budgets: { enabled: false }
+  narrative-bible: { enabled: false }
+  netcode-spec: { enabled: false }
+  review-netcode: { enabled: false }
+  ai-behavior-design: { enabled: false }
+  game-accessibility: { enabled: false }
+  input-controls-spec: { enabled: false }
+  game-ui-spec: { enabled: false }
+  review-game-ui: { enabled: false }
+  content-structure-design: { enabled: false }
+  art-bible: { enabled: false }
+  audio-design: { enabled: false }
+  economy-design: { enabled: false }
+  review-economy: { enabled: false }
+  online-services-spec: { enabled: false }
+  modding-ugc-spec: { enabled: false }
+  save-system-spec: { enabled: false }
+  localization-plan: { enabled: false }
+  playtest-plan: { enabled: false }
+  analytics-telemetry: { enabled: false }
+  live-ops-plan: { enabled: false }
+  platform-cert-prep: { enabled: false }

package/content/methodology/deep.yml

@@ -80,3 +80,28 @@ steps:
   multi-agent-resume: { enabled: true }
   quick-task: { enabled: true }
   new-enhancement: { enabled: true }
+  # Game development steps (enabled via game overlay)
+  game-design-document: { enabled: false }
+  review-gdd: { enabled: false }
+  performance-budgets: { enabled: false }
+  narrative-bible: { enabled: false }
+  netcode-spec: { enabled: false }
+  review-netcode: { enabled: false }
+  ai-behavior-design: { enabled: false }
+  game-accessibility: { enabled: false }
+  input-controls-spec: { enabled: false }
+  game-ui-spec: { enabled: false }
+  review-game-ui: { enabled: false }
+  content-structure-design: { enabled: false }
+  art-bible: { enabled: false }
+  audio-design: { enabled: false }
+  economy-design: { enabled: false }
+  review-economy: { enabled: false }
+  online-services-spec: { enabled: false }
+  modding-ugc-spec: { enabled: false }
+  save-system-spec: { enabled: false }
+  localization-plan: { enabled: false }
+  playtest-plan: { enabled: false }
+  analytics-telemetry: { enabled: false }
+  live-ops-plan: { enabled: false }
+  platform-cert-prep: { enabled: false }

package/content/methodology/game-overlay.yml

@@ -0,0 +1,145 @@
+# methodology/game-overlay.yml
+name: game
+description: >
+  Game development overlay — adds game-specific steps, injects game knowledge
+  into existing steps, and remaps artifact references for game projects.
+project-type: game
+
+# ---------------------------------------------------------------------------
+# step-overrides
+# ---------------------------------------------------------------------------
+# Enable all 24 game-specific steps (12 always-on, 12 conditional).
+# Disable 3 web-centric steps that game projects replace.
+step-overrides:
+  # --- Always-enabled game steps (12) ---
+  game-design-document: { enabled: true }
+  review-gdd: { enabled: true }
+  performance-budgets: { enabled: true }
+  game-accessibility: { enabled: true }
+  input-controls-spec: { enabled: true }
+  game-ui-spec: { enabled: true }
+  review-game-ui: { enabled: true }
+  content-structure-design: { enabled: true }
+  art-bible: { enabled: true }
+  audio-design: { enabled: true }
+  playtest-plan: { enabled: true }
+  analytics-telemetry: { enabled: true }
+
+  # --- Conditional game steps (12) ---
+  narrative-bible: { enabled: true, conditional: "if-needed" }
+  netcode-spec: { enabled: true, conditional: "if-needed" }
+  review-netcode: { enabled: true, conditional: "if-needed" }
+  ai-behavior-design: { enabled: true, conditional: "if-needed" }
+  economy-design: { enabled: true, conditional: "if-needed" }
+  review-economy: { enabled: true, conditional: "if-needed" }
+  save-system-spec: { enabled: true, conditional: "if-needed" }
+  localization-plan: { enabled: true, conditional: "if-needed" }
+  online-services-spec: { enabled: true, conditional: "if-needed" }
+  modding-ugc-spec: { enabled: true, conditional: "if-needed" }
+  live-ops-plan: { enabled: true, conditional: "if-needed" }
+  platform-cert-prep: { enabled: true, conditional: "if-needed" }
+
+  # --- Disabled (replaced by game equivalents) ---
+  design-system: { enabled: false }
+  ux-spec: { enabled: false }
+  review-ux: { enabled: false }
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Map game knowledge entries into existing pipeline steps so that game domain
+# expertise is injected during prompt assembly.
+knowledge-overrides:
+  create-prd:
+    append: [game-design-document]
+  user-stories:
+    append: [game-design-document, game-accessibility]
+  tech-stack:
+    append: [game-engine-selection, game-performance-budgeting]
+  coding-standards:
+    append: [game-engine-selection]
+  tdd:
+    append: [game-testing-strategy]
+  project-structure:
+    append: [game-project-structure]
+  git-workflow:
+    append: [game-asset-pipeline, game-project-structure]
+  dev-env-setup:
+    append: [game-project-structure]
+  add-e2e-testing:
+    append: [game-testing-strategy]
+  domain-modeling:
+    append: [game-domain-patterns, game-save-systems]
+  adrs:
+    append: [game-engine-selection]
+  system-architecture:
+    append: [game-domain-patterns, game-engine-selection]
+  review-architecture:
+    append: [game-performance-budgeting]
+  security:
+    append: [game-networking]
+  review-security:
+    append: [game-networking]
+  operations:
+    append: [game-liveops-analytics]
+  review-operations:
+    append: [game-liveops-analytics]
+  database-schema:
+    append: [game-save-systems, game-networking]
+  api-contracts:
+    append: [game-networking]
+  review-database:
+    append: [game-save-systems]
+  review-api:
+    append: [game-networking]
+  platform-parity-review:
+    append: [game-platform-certification, game-networking]
+  implementation-plan:
+    append: [game-milestone-definitions, game-design-document]
+  implementation-playbook:
+    append: [game-milestone-definitions]
+  game-design-document:
+    append: [game-milestone-definitions]
+  playtest-plan:
+    append: [game-milestone-definitions]
+  story-tests:
+    append: [game-testing-strategy]
+  review-testing:
+    append: [game-testing-strategy, game-performance-budgeting]
+  create-evals:
+    append: [game-testing-strategy]
+  cross-phase-consistency:
+    append: [game-design-document]
+  critical-path-walkthrough:
+    append: [game-design-document]
+
+# ---------------------------------------------------------------------------
+# reads-overrides
+# ---------------------------------------------------------------------------
+# Remap artifact references so game steps read game-specific docs instead of
+# web-centric ones (e.g. ux-spec -> game-ui-spec).
+reads-overrides:
+  story-tests:
+    replace: { ux-spec: game-ui-spec }
+  create-evals:
+    replace: { ux-spec: game-ui-spec }
+  implementation-plan:
+    replace: { ux-spec: game-ui-spec }
+  implementation-playbook:
+    replace: { ux-spec: game-ui-spec, design-system: game-ui-spec }
+  new-enhancement:
+    replace: { ux-spec: game-ui-spec }
+  platform-parity-review:
+    replace: { design-system: game-ui-spec }
+  cross-phase-consistency:
+    replace: { ux-spec: game-ui-spec }
+
+# ---------------------------------------------------------------------------
+# dependency-overrides
+# ---------------------------------------------------------------------------
+# Adjust dependency graph so game review gates are wired correctly.
+dependency-overrides:
+  user-stories:
+    append: [review-gdd]
+  platform-parity-review:
+    replace: { review-ux: review-game-ui }

package/content/methodology/mvp.yml

@@ -80,3 +80,28 @@ steps:
   multi-agent-resume: { enabled: true }
   quick-task: { enabled: true }
   new-enhancement: { enabled: true }
+  # Game development steps (enabled via game overlay)
+  game-design-document: { enabled: false }
+  review-gdd: { enabled: false }
+  performance-budgets: { enabled: false }
+  narrative-bible: { enabled: false }
+  netcode-spec: { enabled: false }
+  review-netcode: { enabled: false }
+  ai-behavior-design: { enabled: false }
+  game-accessibility: { enabled: false }
+  input-controls-spec: { enabled: false }
+  game-ui-spec: { enabled: false }
+  review-game-ui: { enabled: false }
+  content-structure-design: { enabled: false }
+  art-bible: { enabled: false }
+  audio-design: { enabled: false }
+  economy-design: { enabled: false }
+  review-economy: { enabled: false }
+  online-services-spec: { enabled: false }
+  modding-ugc-spec: { enabled: false }
+  save-system-spec: { enabled: false }
+  localization-plan: { enabled: false }
+  playtest-plan: { enabled: false }
+  analytics-telemetry: { enabled: false }
+  live-ops-plan: { enabled: false }
+  platform-cert-prep: { enabled: false }

package/content/pipeline/architecture/ai-behavior-design.md

@@ -0,0 +1,87 @@
+---
+name: ai-behavior-design
+description: Design NPC AI architecture, pathfinding, perception systems, and difficulty scaling
+summary: "Documents AI architecture (behavior trees, GOAP, utility AI, state machines), pathfinding strategy, perception systems, difficulty scaling, and companion AI behavior."
+phase: "architecture"
+order: 717
+dependencies: [system-architecture, game-design-document]
+outputs: [docs/ai-behavior-design.md]
+conditional: "if-needed"
+reads: [performance-budgets]
+knowledge-base: [game-ai-patterns]
+---
+
+## Purpose
+Design the game AI architecture covering NPC behavior systems, pathfinding,
+perception, difficulty scaling, and companion/ally AI. Selects and documents
+the appropriate AI pattern (behavior trees, GOAP, utility AI, finite state
+machines, or hybrids) based on the game's complexity requirements and
+performance budgets. This specification drives the implementation of all
+non-player character behavior in the game.
+
+## Conditional Evaluation
+Enable when: the GDD or project config specifies `npcAiComplexity` as `simple`
+or `complex`. Simple AI projects produce basic behavior specifications (patrol
+patterns, trigger responses, state machines). Complex AI projects produce full
+behavior tree/GOAP specifications with perception systems and difficulty scaling.
+
+Skip when: the GDD or project config specifies `npcAiComplexity: none` — the
+game has no AI-controlled entities (e.g., pure PvP multiplayer, puzzle games
+with no NPCs, rhythm games, visual novels without AI opponents).
+
+## Inputs
+- docs/system-architecture.md (required) — component boundaries and update loop architecture
+- docs/game-design.md (required) — NPC roles, enemy types, companion behavior requirements
+- docs/performance-budgets.md (required) — CPU budget for AI systems, entity count targets
+- docs/domain-models/ (required) — entity definitions for AI-controlled characters
+
+## Expected Outputs
+- docs/ai-behavior-design.md — AI architecture selection, behavior specifications,
+  pathfinding strategy, perception systems, difficulty scaling, and performance
+  constraints
+
+## Quality Criteria
+- (mvp) AI architecture pattern selected and justified (behavior trees, GOAP, utility AI, FSM, or hybrid)
+- (mvp) Every NPC role from the GDD has a behavior specification
+- (mvp) Pathfinding strategy selected (A*, navmesh, flow fields) with rationale for game type
+- (mvp) AI CPU budget allocated within performance budget constraints
+- (deep) Perception system designed (sight cones, hearing radius, awareness states, stealth interaction)
+- (deep) Difficulty scaling strategy documented (parameter tuning, behavior variant selection, rubber banding)
+- (deep) Companion/ally AI behavior specified (follow, assist, independent action, player communication)
+- (deep) AI debugging and visualization tools specified (behavior tree inspector, navmesh overlay, perception cones)
+- (deep) Edge cases documented (stuck detection, recovery behaviors, group coordination, spawn/despawn transitions)
+
+## Methodology Scaling
+- **deep**: Full AI design with architecture selection rationale, per-role
+  behavior specifications, pathfinding with navmesh generation strategy,
+  perception system design, difficulty scaling curves, companion AI,
+  debugging tools, and edge case handling. 15-25 pages.
+- **mvp**: Architecture pattern selection, key NPC behavior summaries,
+  pathfinding choice, and AI budget allocation. 3-5 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: AI pattern selection and one-line behavior summary per NPC role.
+  - Depth 2: add pathfinding strategy and AI budget allocation.
+  - Depth 3: add per-role behavior specifications and perception system overview.
+  - Depth 4: add difficulty scaling, companion AI, and edge case handling.
+  - Depth 5: full specification with debugging tools, group coordination, and performance profiling plan.
+
+## Mode Detection
+Check for docs/ai-behavior-design.md. If it exists, operate in update mode:
+read existing design and diff against current GDD NPC requirements and
+performance budgets. Preserve established AI architecture decisions and
+pathfinding choices. Add behavior specs for new NPC roles. Update budgets
+if performance constraints changed. Never switch AI architecture pattern
+without explicit user approval.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/ai-behavior-design.md exists
+- **Preserve**: AI architecture pattern, pathfinding strategy, perception
+  system design, existing NPC behavior specifications, difficulty scaling
+  approach
+- **Triggers for update**: GDD added new NPC roles or enemy types, performance
+  budgets revised AI CPU allocation, system architecture changed update loop,
+  new companion mechanics introduced
+- **Conflict resolution**: if new NPC requirements exceed the AI CPU budget,
+  flag the budget conflict with options (optimize existing behaviors, increase
+  budget, reduce NPC count); present to user rather than silently degrading
+  existing behaviors

package/content/pipeline/architecture/netcode-spec.md

@@ -0,0 +1,86 @@
+---
+name: netcode-spec
+description: Design network topology, tick rate, prediction, reconciliation, and anti-cheat architecture
+summary: "Specifies client-server or P2P topology, tick rate, client prediction, server reconciliation, lag compensation, bandwidth budgets, and anti-cheat architecture for multiplayer games."
+phase: "architecture"
+order: 715
+dependencies: [system-architecture]
+outputs: [docs/netcode-spec.md]
+conditional: "if-needed"
+reads: [tech-stack, performance-budgets]
+knowledge-base: [game-networking]
+---
+
+## Purpose
+Design the complete network architecture for multiplayer games. Specifies the
+network topology (client-server authoritative, P2P, relay hybrid), tick rate
+and simulation frequency, client-side prediction and server reconciliation
+strategy, lag compensation techniques, bandwidth budgets per connection, and
+anti-cheat architecture. This document bridges the system architecture and
+the implementation of all networked gameplay systems.
+
+## Conditional Evaluation
+Enable when: the GDD or project config specifies `multiplayerMode` as `online`
+or `hybrid` (online + local). Any game requiring network communication between
+players needs this specification.
+
+Skip when: the GDD or project config specifies `multiplayerMode` as `none`
+(single-player only) or `local` (local multiplayer only using shared screen,
+split screen, or local network without internet). Local multiplayer uses shared
+game state without network serialization.
+
+## Inputs
+- docs/system-architecture.md (required) — system component boundaries and data flows
+- docs/tech-stack.md (required) — networking library/framework choices, transport protocol
+- docs/performance-budgets.md (required) — latency targets, bandwidth constraints, tick rate goals
+- docs/game-design.md (required) — multiplayer mode, player count, gameplay mechanics requiring sync
+
+## Expected Outputs
+- docs/netcode-spec.md — network topology, tick rate, prediction/reconciliation
+  strategy, lag compensation, bandwidth budgets, anti-cheat architecture, and
+  connection lifecycle
+
+## Quality Criteria
+- (mvp) Network topology selected and justified (client-server, P2P, or hybrid) with rationale
+- (mvp) Tick rate specified with justification based on game genre and latency requirements
+- (mvp) Client prediction strategy defined for player-controlled entities
+- (mvp) Server reconciliation approach documented (snapshot interpolation, rollback, or hybrid)
+- (mvp) Bandwidth budget per connection specified and within performance budget constraints
+- (deep) Lag compensation techniques documented (input delay, rollback, entity interpolation)
+- (deep) Anti-cheat architecture covers input validation, server authority boundaries, and detection heuristics
+- (deep) Connection lifecycle specified (matchmaking handshake, session join, reconnection, graceful disconnect, timeout)
+- (deep) Network serialization format defined with size budgets per message type
+- (deep) Edge cases documented (host migration for P2P, region failover, NAT traversal)
+
+## Methodology Scaling
+- **deep**: Full netcode specification with topology rationale, tick rate
+  analysis, prediction/reconciliation deep dive, lag compensation techniques,
+  bandwidth budgets per message type, anti-cheat architecture, connection
+  lifecycle, network serialization format, edge case handling, and load
+  testing plan. 15-25 pages.
+- **mvp**: Topology selection, tick rate, basic prediction/reconciliation
+  approach, and bandwidth budget. 3-5 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: topology selection with rationale and tick rate only.
+  - Depth 2: add client prediction and server reconciliation approach.
+  - Depth 3: add bandwidth budgets and connection lifecycle.
+  - Depth 4: add lag compensation, anti-cheat architecture, and serialization format.
+  - Depth 5: full specification with edge cases, load testing plan, and region failover strategy.
+
+## Mode Detection
+Check for docs/netcode-spec.md. If it exists, operate in update mode: read
+existing spec and diff against current system architecture and performance
+budgets. Preserve established topology decisions, tick rate, and protocol
+choices. Update prediction/reconciliation if gameplay mechanics changed.
+Never change network topology without explicit user approval.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/netcode-spec.md exists
+- **Preserve**: network topology decision, tick rate, transport protocol,
+  serialization format, anti-cheat strategy, bandwidth budgets
+- **Triggers for update**: system architecture changed networking components,
+  performance budgets revised latency targets, GDD added new multiplayer
+  modes or increased player count, tech stack changed networking library
+- **Conflict resolution**: if architecture changes require a different
+  topology, flag the breaking change with migration impact analysis;
+  present options to user rather than silently switching

package/content/pipeline/architecture/review-netcode.md

@@ -0,0 +1,78 @@
+---
+name: review-netcode
+description: Review netcode specification for latency tolerance, bandwidth, cheat resistance, and edge cases
+summary: "Multi-pass review of netcode spec checking latency tolerance, bandwidth compliance, cheat resistance, determinism verification, and connection edge cases."
+phase: "architecture"
+order: 716
+dependencies: [netcode-spec]
+outputs: [docs/reviews/architecture-review-netcode.md]
+conditional: "if-needed"
+reads: []
+knowledge-base: [review-netcode, review-step-template, multi-model-review-dispatch]
+---
+
+## Purpose
+Multi-pass review of the netcode specification targeting networking-specific
+failure modes: latency tolerance violations, bandwidth budget overruns, cheat
+surface exposure, determinism gaps in simulation, connection edge case omissions,
+and inconsistencies with the system architecture and performance budgets.
+
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
+## Conditional Evaluation
+Enable when: netcode-spec is enabled (i.e., `multiplayerMode` is `online` or
+`hybrid`). If netcode-spec runs, this review must follow it.
+
+Skip when: netcode-spec is skipped (i.e., `multiplayerMode` is `none` or
+`local`). No netcode spec means no netcode review.
+
+## Inputs
+- docs/netcode-spec.md (required) — netcode specification to review
+- docs/performance-budgets.md (required) — latency and bandwidth constraints for compliance checking
+- docs/system-architecture.md (required) — for cross-referencing component boundaries
+- docs/game-design.md (required) — multiplayer mechanics that must be supported
+
+## Expected Outputs
+- docs/reviews/architecture-review-netcode.md — findings and resolution log
+- docs/netcode-spec.md — updated with fixes
+- docs/reviews/netcode/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/netcode/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/netcode/gemini-review.json (depth 4+, if available) — raw Gemini findings
+
+## Quality Criteria
+- (mvp) Latency tolerance verified (prediction window covers target round-trip time)
+- (mvp) Bandwidth budget compliance verified (per-connection budget within performance constraints)
+- (mvp) Cheat surface audit completed (server authority boundaries cover all game-critical state)
+- (mvp) Every finding categorized P0-P3 with specific section and issue. Severity definitions: P0 = Breaks downstream work. P1 = Prevents quality milestone. P2 = Known tech debt. P3 = Polish.
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to netcode-spec.md and re-validated
+- (deep) Determinism verification completed (simulation produces identical results given identical inputs)
+- (deep) Connection edge cases audited (reconnection, host migration, NAT traversal, timeout handling)
+- (deep) Serialization size audit (message sizes within per-type budgets)
+- (deep) Cross-reference with system architecture verified (no orphaned network components)
+- (depth 4+) Multi-model findings synthesized: Consensus (all models agree), Majority (2+ models agree), or Divergent (models disagree — present to user for decision)
+
+## Methodology Scaling
+- **deep**: All 7 review passes (Latency Tolerance, Bandwidth Compliance,
+  Cheat Surface Audit, Determinism Verification, Connection Edge Cases,
+  Serialization Size Audit, Architecture Cross-Reference). Multi-model
+  review dispatched to Codex and Gemini if available, with graceful fallback
+  to Claude-only enhanced review.
+- **mvp**: Three passes — Latency Tolerance, Bandwidth Compliance, and Cheat
+  Surface Audit only.
+- **custom:depth(1-5)**:
+  - Depth 1: two passes — Latency Tolerance and Bandwidth Compliance only.
+  - Depth 2: three passes — add Cheat Surface Audit.
+  - Depth 3: five passes — add Determinism Verification and Connection Edge Cases.
+  - Depth 4: all 7 passes + one external model (if CLI available).
+  - Depth 5: all 7 passes + multi-model with reconciliation.
+
+## Mode Detection
+Re-review mode if previous review exists. If multi-model review artifacts exist
+under docs/reviews/netcode/, preserve prior findings still valid.
+
+## Update Mode Specifics
+- **Detect**: `docs/reviews/architecture-review-netcode.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/content/pipeline/foundation/performance-budgets.md

@@ -0,0 +1,91 @@
+---
+name: performance-budgets
+description: Define frame budgets, memory budgets, GPU budgets, and platform-specific performance targets
+summary: "Establishes per-system frame time allocations, per-platform memory budgets, GPU/draw call limits, loading time targets, and thermal constraints. Every budget has a measurement method and alert threshold."
+phase: "foundation"
+order: 225
+dependencies: [review-gdd, tech-stack]
+outputs: [docs/performance-budgets.md]
+conditional: null
+reads: [game-design-document]
+knowledge-base: [game-performance-budgeting]
+---
+
+## Purpose
+Define concrete, measurable performance budgets for every target platform. This
+covers frame time budgets (per-system millisecond allocations within the target
+frame rate), memory budgets (per platform), GPU and draw call budgets, loading
+time targets, storage size targets, bandwidth budgets (for online titles),
+thermal and battery constraints (for mobile), and VR-specific targets (90 fps,
+stereo rendering overhead, motion-to-photon latency). Each budget entry includes
+the system, its allocation, rationale, measurement method, and alert threshold
+so that performance regressions are caught automatically.
+
+## Inputs
+- docs/game-design-document.md (required) — core systems, target platforms,
+  visual fidelity targets, multiplayer scope
+- docs/tech-stack.md (required) — engine, renderer, target hardware, platform
+  SDK constraints
+- User preferences (gathered via questions) — target frame rate, minimum spec
+  hardware, acceptable loading times, network conditions
+
+## Expected Outputs
+- docs/performance-budgets.md — complete performance budget reference containing:
+  - Target frame rate and per-system frame time breakdown table
+  - Per-platform memory budget tables (RAM, VRAM, texture streaming)
+  - GPU budget (draw calls, triangle counts, shader complexity)
+  - Loading time targets (initial load, level transitions, fast travel)
+  - Storage size targets per platform
+  - Bandwidth budgets (if online: tick rate, packet size, sync model)
+  - Thermal and battery budgets (if mobile/handheld)
+  - VR-specific budgets (if applicable: 90 fps, stereo rendering, motion-to-photon)
+  - Hitch and stutter budget (maximum frame time spikes, frequency)
+  - Measurement methods and profiling tool recommendations
+  - Alert thresholds for CI performance regression detection
+
+## Quality Criteria
+- (mvp) Target frame rate explicitly defined for each target platform
+- (mvp) Per-system frame time breakdown sums to at most the frame budget (e.g., 16.6 ms at 60 fps)
+- (mvp) Memory budget defined for every target platform
+- (mvp) Hitch/stutter budget defined (max spike duration, acceptable frequency)
+- (mvp) Every budget entry has a measurement method (tool, metric, command)
+- (mvp) Every budget entry has an alert threshold (the number that triggers investigation)
+- (deep) GPU budget with draw call and triangle count limits per scene type
+- (deep) Loading time targets for every transition type
+- (deep) Storage and bandwidth budgets where applicable
+- (deep) Thermal/battery constraints for mobile platforms
+- (deep) VR budgets with motion-to-photon latency target (if VR platform)
+- (deep) CI integration plan for automated performance regression detection
+
+## Methodology Scaling
+- **deep**: Full per-system breakdown across all target platforms. Per-platform
+  matrices for memory, GPU, loading, storage, and bandwidth. Profiling tool
+  recommendations with CI performance regression pipeline. Thermal and VR
+  budgets where applicable. 8-15 pages with concrete tables.
+- **mvp**: Target frame rate and top-level memory budget per platform. Frame
+  time breakdown for the 3-5 most expensive systems. Hitch budget. Concrete
+  tables, not prose. 2-4 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: Target frame rate + total memory budget per platform. Single summary table. 1 page.
+  - Depth 2: Depth 1 + per-system frame time breakdown for top 3-5 systems + hitch budget. Concrete tables. 2-3 pages.
+  - Depth 3: Full per-system frame time breakdown + GPU budget (draw calls, triangles) + loading time targets. 4-6 pages.
+  - Depth 4: Per-platform matrices for all budget categories + profiling tool recommendations + CI perf regression thresholds. 6-10 pages.
+  - Depth 5: Full budget suite including thermal/battery, VR, bandwidth. CI pipeline config. Per-scene-type budgets. Profiling tool integration guides. 10-15 pages.
+
+## Mode Detection
+Update mode if docs/performance-budgets.md exists. In update mode: preserve
+existing budget allocations unless the user explicitly requests changes, add new
+budget categories without removing existing ones, update measurement methods if
+tooling changed.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/performance-budgets.md exists
+- **Preserve**: all existing budget allocations, per-system breakdowns,
+  measurement methods, alert thresholds, CI integration configuration
+- **Triggers for update**: new target platform added, GDD scope change
+  affecting system count or complexity, tech stack change (new engine/renderer),
+  profiling revealed original budgets were infeasible, new system added
+  (e.g., adding multiplayer introduces bandwidth budgets)
+- **Conflict resolution**: if a new system pushes the frame time total over
+  budget, document the overage and propose rebalancing options with trade-off
+  analysis — never silently reduce another system's allocation

package/content/pipeline/modeling/narrative-bible.md

@@ -0,0 +1,84 @@
+---
+name: narrative-bible
+description: Document world lore, characters, dialogue systems, and narrative pacing
+summary: "Creates a narrative bible covering world lore, character profiles, dialogue system design, branching narrative structure, and narrative pacing. Conditional on narrative depth."
+phase: "modeling"
+order: 515
+dependencies: [domain-modeling]
+outputs: [docs/narrative-bible.md]
+conditional: "if-needed"
+reads: [game-design-document]
+knowledge-base: [game-narrative-design]
+---
+
+## Purpose
+Create a comprehensive narrative bible that documents the world, characters,
+dialogue systems, and story structure for games with narrative content. This
+artifact translates the GDD's narrative vision into implementable specifications
+that downstream steps (architecture, content pipeline, dialogue systems) can
+consume. Covers world lore, character profiles with arcs and relationships,
+dialogue system design (branching, bark, cinematic), narrative pacing aligned
+to gameplay loops, and localization considerations.
+
+## Conditional Evaluation
+Enable when: the GDD or project config specifies `narrative` as `light` or
+`heavy`. Light narrative projects produce a minimal bible (world context, key
+characters, bark/dialogue catalog). Heavy narrative projects produce the full
+bible with branching story graphs, character relationship maps, and pacing
+curves.
+
+Skip when: the GDD or project config specifies `narrative: none` — the project
+has no story, dialogue, or character content (e.g., pure puzzle games, abstract
+arcade games, sports simulations without story mode).
+
+## Inputs
+- docs/game-design.md (required) — narrative pillars, world overview, character concepts
+- docs/domain-models/ (required) — entities that may include characters, items, locations
+- docs/plan.md (required) — scope and feature list to gauge narrative breadth
+
+## Expected Outputs
+- docs/narrative-bible.md — world lore, character profiles, dialogue system
+  design, branching narrative structure, pacing plan, and localization notes
+
+## Quality Criteria
+- (mvp) World lore section establishes setting, tone, and key locations
+- (mvp) Every named character in the GDD has a profile with role, motivation, and arc summary
+- (mvp) Dialogue system type identified (branching, linear, bark, cinematic) with implementation approach
+- (mvp) Narrative pacing aligns with core gameplay loop from GDD
+- (deep) Character relationship map with faction/alliance dynamics
+- (deep) Branching narrative graph with critical path and optional branches identified
+- (deep) Dialogue state tracking requirements documented (flags, variables, conditions)
+- (deep) Localization strategy for narrative content (string table structure, cultural considerations)
+- (deep) Narrative content pipeline defined (authoring tools, review workflow, integration format)
+
+## Methodology Scaling
+- **deep**: Full narrative bible with world lore, complete character profiles
+  with arcs, branching story graph, dialogue system specification, pacing
+  curves mapped to gameplay progression, localization strategy, and content
+  pipeline. 15-25 pages.
+- **mvp**: World context, key character profiles, dialogue system type, and
+  narrative pacing outline. 3-5 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: world setting paragraph and character name/role list only.
+  - Depth 2: world lore section and character profiles with motivations.
+  - Depth 3: add dialogue system design and narrative pacing outline.
+  - Depth 4: add branching narrative structure and character relationship map.
+  - Depth 5: full bible with localization strategy and content pipeline definition.
+
+## Mode Detection
+Check for docs/narrative-bible.md. If it exists, operate in update mode: read
+existing bible and diff against current GDD narrative sections. Preserve
+established lore, character profiles, and dialogue system decisions. Add new
+characters or story elements from updated GDD. Update pacing if gameplay loop
+changed. Never alter established world canon without explicit user approval.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/narrative-bible.md exists
+- **Preserve**: established world lore, character profiles, dialogue system
+  type, branching structure decisions, localization strategy
+- **Triggers for update**: GDD narrative sections changed, new characters
+  introduced, gameplay loop restructured affecting pacing, new dialogue
+  system requirements
+- **Conflict resolution**: if GDD changes contradict established lore, flag
+  the contradiction and present both versions for user decision; never
+  silently overwrite canon