@zigrivers/scaffold 3.4.1 → 3.5.1

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, game-design-document]
+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: [performance-budgets, system-architecture, game-design-document]
+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, Disconnect/Reconnect Handling,
+  Matchmaking Fairness Assessment, Bandwidth Spike Resilience). 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.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

package/content/pipeline/pre/game-design-document.md

@@ -0,0 +1,90 @@
+---
+name: game-design-document
+description: Create game design document with pillars, core loop, mechanics, progression, and world overview
+summary: "Transforms PRD product requirements into a game design bible covering game pillars, core gameplay loop, mechanics catalog, progression systems, and game world overview. Review step validates pillar coherence and mechanic clarity."
+phase: "pre"
+order: 115
+dependencies: [review-prd]
+outputs: [docs/game-design.md]
+conditional: null
+reads: [create-vision, create-prd]
+knowledge-base: [game-design-document, game-milestone-definitions, game-domain-patterns, game-engine-selection, game-project-structure]
+---
+
+## Purpose
+Transform the PRD into a Game Design Document (GDD) that defines the game's
+identity through design pillars, core gameplay loop, mechanics catalog,
+progression systems, and game world overview. The GDD is the authoritative
+source of truth for what the game is, how it plays, and why its systems exist.
+This step focuses on gameplay systems — art direction, audio design, and
+narrative detail are covered by separate downstream steps.
+
+## Inputs
+- docs/plan.md (required) — PRD with features, personas, and requirements
+- docs/vision.md (optional) — vision document for strategic alignment
+- docs/user-stories.md (optional) — user stories for behavioral context
+
+## Expected Outputs
+- docs/game-design.md — Game design document covering pillars, core loop,
+  mechanics, progression, and world overview
+
+## Quality Criteria
+- (mvp) Game pillars are phrased as "X over Y" tradeoffs that constrain decisions — each pillar excludes at least one plausible mechanic
+- (mvp) Core loop is closed: engage -> challenge -> reward -> repeat with no dead ends where the player has nothing meaningful to do next
+- (mvp) Every mechanic is documented with inputs, rules, outputs, and feedback — precise enough for an engineer to implement without guessing
+- (mvp) Game modes and win/fail states are defined
+- (mvp) Camera model is documented (perspective, movement constraints, zoom range)
+- (deep) Mechanics include numeric ranges, state transitions, and edge cases
+- (deep) Progression systems define XP/level curves or equivalent with explicit formulas
+- (deep) Achievements/trophies schema is present with unlock conditions
+- (deep) Competitive analysis references specific titles and structural differentiation
+- (deep) Feature priority matrix included (must-have, should-have, nice-to-have per milestone) and top-5 risk register with likelihood, impact, and mitigation strategies
+
+## Methodology Scaling
+- **deep**: Full GDD bible. Design pillars with exclusion rationale, multi-tier
+  core loop (moment-to-moment, session, metagame), complete mechanics catalog
+  with numeric specifications, progression curves with formulas, world overview,
+  game modes, competitive analysis, achievements schema. 20-40 pages.
+- **mvp**: Pillars + core loop + key mechanics. Enough to start prototyping.
+  2-3 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: Pillars and core loop only. 1-2 pages. Enough to validate the game concept.
+  - Depth 2: Pillars, core loop, and key mechanics with inputs/rules/outputs. 2-3 pages.
+  - Depth 3: Add progression systems, world overview, game modes, win/fail states, camera model. 5-10 pages.
+  - Depth 4: Full mechanics catalog with numeric specs, competitive analysis with named titles, achievements schema, multi-model review of pillar coherence. 15-25 pages.
+  - Depth 5: Complete GDD bible — all of depth 4 plus systems interaction matrix, difficulty scaling formulas, content volume estimates, and separate reference files for complex subsystems. 25-40 pages.
+
+## Mode Detection
+If docs/game-design.md exists, operate in update mode: read existing content,
+identify what has changed or been learned since it was written, propose targeted
+updates. Preserve existing design pillars and mechanic definitions unless
+explicitly revisiting them.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/game-design.md exists
+- **Preserve**: design pillars, existing mechanic definitions, core loop
+  structure, progression formulas, and enhancement markers
+  (`<!-- enhancement: ... -->`) unless user explicitly requests changes
+- **Triggers for update**: PRD features added or changed, playtest feedback
+  received, scope adjustment requested, new mechanics needed for user stories
+- **Conflict resolution**: new mechanics are appended to the catalog with clear
+  versioning; changed mechanics document the rationale for change and impact on
+  dependent systems
+
+### Understand the Design Context
+
+**If `docs/vision.md` exists**: Read it completely. The vision establishes the
+player experience, target audience, and guiding principles. Ensure every pillar
+and mechanic aligns with the stated vision. Reference the vision when making
+tradeoff decisions.
+
+**If `docs/plan.md` exists**: Read it completely. The PRD defines features,
+personas, and requirements. Every PRD feature should trace to at least one
+mechanic in the GDD. Personas inform the target player profile and skill
+assumptions.
+
+**Discovery questions** (ask if context is insufficient):
+- What is the core fantasy — what does the player get to be or do that they cannot in real life?
+- What is the primary interaction verb (shoot, build, solve, explore, manage)?
+- What makes a play session feel complete — what is the natural stopping point?
+- What existing games are closest to your vision, and where does this game diverge?

package/content/pipeline/pre/review-gdd.md

@@ -0,0 +1,74 @@
+---
+name: review-gdd
+description: Multi-pass review of game design document for pillar coherence, mechanic clarity, and scope feasibility
+summary: "Stress-tests the GDD through multiple review passes checking pillar coherence, core loop closure, mechanic implementability, progression feasibility, scope assessment, and downstream readiness for user stories."
+phase: "pre"
+order: 116
+dependencies: [game-design-document]
+outputs: [docs/reviews/pre-review-gdd.md, docs/reviews/gdd/review-summary.md, docs/reviews/gdd/codex-review.json, docs/reviews/gdd/gemini-review.json]
+conditional: null
+reads: []
+knowledge-base: [review-methodology, review-game-design, review-step-template, multi-model-review-dispatch]
+---
+
+## Purpose
+Deep multi-pass review of the Game Design Document, targeting the specific
+failure modes of game design artifacts. Identify issues with pillar coherence,
+core loop closure, mechanic ambiguity, progression feasibility, scope reality,
+competitive differentiation, and systems interactions. Create a fix plan,
+execute fixes, and re-validate. Ensures the GDD is implementable, internally
+consistent, and ready for downstream consumption by user stories, architecture,
+and art/audio specifications.
+
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
+## Inputs
+- docs/game-design.md (required) — GDD to review
+- docs/plan.md (required) — PRD for cross-referencing features and scope
+- docs/reviews/gdd/ artifacts (optional) — prior review findings in update mode
+
+## Expected Outputs
+- docs/reviews/pre-review-gdd.md — review findings, fix plan, and resolution log
+- docs/game-design.md — updated with fixes
+- docs/reviews/gdd/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/gdd/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/gdd/gemini-review.json (depth 4+, if available) — raw Gemini findings
+
+## Quality Criteria
+- (mvp) Passes 1-2 executed with findings documented (Pillar Coherence, Core Loop Closure)
+- (deep) All 7 review passes executed with findings documented
+- (mvp) Every finding categorized by severity: P0 = Breaks downstream work. P1 = Prevents quality milestone. P2 = Known tech debt. P3 = Polish.
+- (mvp) Fix plan created for P0 and P1 findings
+- (mvp) Fixes applied and re-validated
+- (mvp) Downstream readiness confirmed (user stories and architecture can proceed)
+- (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 from the knowledge base (Pillar Coherence, Core
+  Loop Closure, Mechanic Ambiguity Detection, Progression Curve Feasibility,
+  Scope vs Reality Check, Competitive Differentiation, Systems Interaction
+  Audit). Full findings report with severity categorization. Fixes applied and
+  re-validated. Multi-model review dispatched to Codex and Gemini if available,
+  with graceful fallback to Claude-only enhanced review.
+- **mvp**: Passes 1-2 only (Pillar Coherence, Core Loop Closure). Focus on
+  blocking gaps — pillars that do not constrain and loops that do not close.
+- **custom:depth(1-5)**:
+  - Depth 1: Pass 1 only (Pillar Coherence). One review pass.
+  - Depth 2: Passes 1-2 (Pillar Coherence, Core Loop Closure). Two review passes.
+  - Depth 3: Passes 1-4 (add Mechanic Ambiguity Detection, Progression Curve Feasibility). Four review passes.
+  - Depth 4: All 7 passes + one external model review (if CLI available).
+  - Depth 5: All 7 passes + multi-model review with reconciliation.
+
+## Mode Detection
+If docs/reviews/pre-review-gdd.md exists, this is a re-review. Read previous
+findings, check which were addressed, run review passes again on updated GDD.
+If multi-model review artifacts exist under docs/reviews/gdd/, preserve prior
+findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/pre-review-gdd.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