@zigrivers/scaffold 3.4.0 → 3.5.0

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

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

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

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

package/content/pipeline/specification/modding-ugc-spec.md

@@ -0,0 +1,116 @@
+---
+name: modding-ugc-spec
+description: Specify mod API surface, packaging format, sandboxing, versioning, content moderation, and distribution channels
+summary: "Specifies the modding and user-generated content system — mod API surface and capability tiers, packaging format and validation, runtime sandboxing, compatibility and versioning strategy, content moderation pipeline, and distribution channels (Steam Workshop, mod.io, local file-based) with platform certification implications."
+phase: "specification"
+order: 872
+dependencies: [system-architecture]
+outputs: [docs/modding-spec.md]
+conditional: "if-needed"
+reads: [game-design-document]
+knowledge-base: [game-modding-ugc]
+---
+
+## Purpose
+Specify the modding and user-generated content (UGC) system — the APIs,
+packaging formats, runtime boundaries, and distribution infrastructure that
+allow players and third-party creators to extend the game safely and
+sustainably.
+
+Modding support is an architectural commitment, not a feature toggle. The mod
+API surface determines what creators can change (textures, levels, gameplay
+rules, UI), the packaging format determines how mods are distributed and
+validated, and the sandboxing model determines what damage a malicious or
+buggy mod can inflict. These decisions cascade into security requirements,
+platform certification constraints, and long-term versioning strategy.
+
+Three categories of modding complexity exist, each with different engineering
+costs:
+
+1. **Asset replacement**: Swapping textures, models, audio, or localization
+   strings. Lowest risk — mods cannot execute code, only replace data.
+2. **Content authoring**: Creating new levels, quests, items, or game entities
+   using structured data formats (JSON, YAML, custom editors). Medium risk —
+   mods define data that the engine interprets, with schema validation as the
+   safety boundary.
+3. **Scripted mods**: Running custom logic via a scripting layer (Lua, C#,
+   WASM). Highest risk — mods execute code, requiring sandboxing, resource
+   limits, and capability-based permission models.
+
+This specification must also address the tension between openness and platform
+certification: console platforms restrict arbitrary code execution and require
+content moderation for UGC, which constrains what modding features can ship on
+each platform.
+
+## Conditional Evaluation
+Enable when: the project config indicates modding support (`hasModding` is
+true) — the GDD describes mod support, workshop integration, user-generated
+content, level editors, or any system allowing players to create, share, or
+install content beyond the shipped game.
+
+Skip when: the game has no modding or UGC features — players can only
+experience developer-created content. Games with cosmetic customization
+(character creators, paint jobs) that use built-in assets do not require a
+modding specification.
+
+## Inputs
+- docs/system-architecture.md (required) — engine architecture, asset loading pipeline, scripting runtime, security boundaries
+- docs/plan.md (required) — target platforms informing modding feasibility per platform (PC vs console vs mobile)
+- docs/game-design.md (optional, forward-read) — moddable systems, expected mod types, community creation goals
+- docs/security.md (optional, forward-read) — threat model, sandboxing requirements, anti-cheat considerations for modded game states
+
+## Expected Outputs
+- docs/modding-spec.md — mod API surface, packaging format, sandboxing model,
+  versioning strategy, content moderation pipeline, and distribution channel
+  integration
+
+## Quality Criteria
+- (mvp) Mod capability tiers defined: which game systems are moddable (asset replacement, content authoring, scripted logic) with explicit boundaries for each tier
+- (mvp) Packaging format specified: mod manifest schema, directory structure, required metadata (name, version, author, compatibility range, permissions)
+- (mvp) Runtime sandboxing model documented: what mods can and cannot access (filesystem, network, memory), resource limits (CPU time, memory allocation), and failure isolation (one mod crash does not crash the game)
+- (mvp) Mod loading and conflict resolution: load order management, asset override priority, incompatible mod detection, graceful degradation when mods fail validation
+- (mvp) Distribution channel integration for at least one channel: Steam Workshop, mod.io, or local file-based sideloading
+- (deep) Versioning and compatibility strategy: semantic versioning for mod API, compatibility matrix (which game versions support which mod API versions), migration tooling for mod authors when API breaks
+- (deep) Content moderation pipeline: automated scanning (file type validation, size limits, known-malware signatures), community reporting, manual review queue, takedown process
+- (deep) Platform certification analysis: which modding features are permitted per platform (PC unrestricted, console UGC requires certification-compliant moderation, mobile requires app store policy compliance)
+- (deep) Mod development toolkit: editor tools, debugging support, documentation generation, sample mods, mod template scaffolding
+- (deep) Multiplayer mod compatibility: mod-matching in matchmaking (only connect players with identical mod sets), server-authoritative mod validation, anti-cheat interaction with modded game states
+
+## Methodology Scaling
+- **deep**: Full modding specification covering all three capability tiers,
+  comprehensive sandboxing with capability-based permissions, multi-channel
+  distribution, content moderation pipeline, platform certification analysis,
+  versioning strategy with migration tooling, mod development toolkit, and
+  multiplayer mod compatibility. 15-25 pages.
+- **mvp**: Mod capability tiers, packaging format, basic sandboxing, single
+  distribution channel, and load-order conflict resolution. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: asset replacement tier only with local file-based sideloading.
+  - Depth 2: add content authoring tier with packaging format and manifest schema.
+  - Depth 3: add scripted mod tier with sandboxing model, conflict resolution, and second distribution channel.
+  - Depth 4: add content moderation pipeline, versioning strategy, platform certification analysis, and mod development toolkit.
+  - Depth 5: full specification with multiplayer mod compatibility, automated mod testing infrastructure, mod analytics (install rates, crash rates, popularity), and community curation tools.
+
+## Mode Detection
+Check for docs/modding-spec.md. If it exists, operate in update mode: read
+existing modding spec and diff against current system architecture and GDD
+modding requirements. Preserve existing API surface definitions, packaging
+format, and distribution channel integrations. Update sandboxing model if
+security requirements changed. Add new capability tiers if GDD expanded
+moddable systems.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/modding-spec.md exists
+- **Preserve**: mod API surface definitions, packaging format and manifest
+  schema, sandboxing model, distribution channel integrations, versioning
+  strategy, content moderation pipeline
+- **Triggers for update**: system architecture changed asset loading or
+  scripting runtime, GDD expanded or narrowed moddable systems, security
+  requirements changed sandboxing constraints, target platforms changed
+  (affects platform certification analysis), distribution channel added or
+  removed
+- **Conflict resolution**: if platform certification requirements conflict
+  with desired modding features (e.g., console prohibiting scripted mods),
+  document the per-platform capability matrix explicitly — never silently
+  reduce PC modding capability to match console restrictions; instead, define
+  platform-specific mod capability tiers with clear feature parity documentation

package/content/pipeline/specification/online-services-spec.md

@@ -0,0 +1,104 @@
+---
+name: online-services-spec
+description: Specify identity/auth, leaderboards, matchmaking, entitlements, remote config, moderation, and cloud save
+summary: "Specifies online service infrastructure — identity and authentication, leaderboards, matchmaking, entitlements and DLC, remote config, content moderation, and cloud save — bridging system architecture with platform-specific service requirements."
+phase: "specification"
+order: 871
+dependencies: [system-architecture]
+outputs: [docs/online-services-spec.md]
+conditional: "if-needed"
+reads: [game-design-document, netcode-spec]
+knowledge-base: [game-networking, game-liveops-analytics]
+---
+
+## Purpose
+Specify the online services layer that sits between the game client and backend
+infrastructure. Online services are the platform-facing systems that handle
+player identity, persistent state, social features, and content delivery —
+distinct from the netcode layer (which handles real-time gameplay
+synchronization) and the economy layer (which handles virtual currency and
+progression).
+
+Every online service has platform-specific requirements: Xbox Live, PlayStation
+Network, Steam, Epic Online Services, Apple Game Center, and Google Play Games
+each have mandatory integration points for identity, achievements, entitlements,
+and cloud saves. Abstracting these behind a unified service layer prevents
+platform-specific code from spreading throughout the game codebase.
+
+This specification covers: identity and authentication (platform SSO, cross-play
+identity linking), leaderboards (submission, anti-cheat validation, seasonal
+resets), matchmaking (skill-based, region-based, queue management), entitlements
+and DLC (purchase verification, content unlocking), remote configuration
+(feature flags, A/B testing, live tuning), content moderation (chat filtering,
+reporting, sanctions), and cloud save (conflict resolution, migration).
+
+## Conditional Evaluation
+Enable when: the game requires any online service beyond local storage — online
+multiplayer, leaderboards, cloud saves, in-app purchases requiring server
+verification, remote configuration, or any feature requiring server
+communication outside of real-time gameplay.
+
+Skip when: the game is entirely offline with no online features — no
+leaderboards, no cloud saves, no server-verified purchases, no remote config.
+Games using only local save files and platform-native achievement systems
+(which are handled by platform SDKs without custom backend) do not need this
+specification.
+
+## Inputs
+- docs/system-architecture.md (required) — backend service boundaries and data flow
+- docs/plan.md (required) — target platforms informing platform-specific service requirements
+- docs/game-design.md (optional, forward-read) — multiplayer modes, social features, progression requiring persistence
+- docs/netcode-spec.md (optional, forward-read) — matchmaking requirements, session management, connection lifecycle
+
+## Expected Outputs
+- docs/online-services-spec.md — service specifications for identity, leaderboards,
+  matchmaking, entitlements, remote config, moderation, and cloud save
+
+## Quality Criteria
+- (mvp) Identity and authentication flow documented: platform SSO integration per target platform, session token lifecycle, guest-to-account upgrade path
+- (mvp) Every online service specifies: API contract (request/response), failure modes and fallback behavior, data ownership and retention policy
+- (mvp) Cloud save strategy documented: save format, conflict resolution (last-write-wins, merge, user-choice), platform-specific cloud save API mapping
+- (mvp) Entitlement verification flow documented: purchase validation, content unlocking, receipt verification per platform
+- (deep) Leaderboard specification: submission validation (anti-cheat checks before write), ranking algorithm, seasonal reset strategy, regional vs global boards
+- (deep) Matchmaking specification: skill rating system (Elo, Glicko-2, TrueSkill), queue management, region selection, party handling, backfill strategy
+- (deep) Remote configuration specification: feature flag schema, A/B test segmentation, rollout strategy, emergency kill switches
+- (deep) Content moderation specification: text filtering (blocklist + ML classification), player reporting workflow, sanction tiers (warning, mute, temp ban, permanent ban), appeal process
+- (deep) Cross-play identity linking: account merging strategy, entitlement portability, platform TOS compliance for cross-platform purchases
+- (deep) Service degradation strategy: graceful fallback when individual services are unavailable (offline mode, cached leaderboards, local save fallback)
+
+## Methodology Scaling
+- **deep**: Full online services specification covering all seven service
+  domains with platform-specific integration details, failure mode analysis,
+  cross-play considerations, moderation pipeline, and service degradation
+  strategy. 15-25 pages.
+- **mvp**: Identity/auth, cloud save, and entitlement verification for primary
+  platform. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: identity/auth flow and cloud save strategy for primary platform only.
+  - Depth 2: add entitlement verification and basic leaderboard submission.
+  - Depth 3: add matchmaking specification, remote config, and multi-platform identity mapping.
+  - Depth 4: add content moderation pipeline, cross-play identity linking, and service degradation strategy.
+  - Depth 5: full specification with A/B testing infrastructure, analytics event taxonomy for online services, and platform certification compliance checklist.
+
+## Mode Detection
+Check for docs/online-services-spec.md. If it exists, operate in update mode:
+read existing spec and diff against current system architecture and platform
+targets. Preserve existing service API contracts, identity flows, and cloud
+save strategy. Update matchmaking if netcode-spec changed session management.
+Add services for new platforms added to target list.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/online-services-spec.md exists
+- **Preserve**: identity/auth flow, cloud save conflict resolution strategy,
+  entitlement verification flow, leaderboard ranking algorithm, matchmaking
+  skill rating system, moderation sanction tiers
+- **Triggers for update**: system architecture changed backend service
+  boundaries, target platforms changed (new platform requires new SSO
+  integration), netcode-spec changed matchmaking or session management,
+  GDD added social features or new online modes, economy-design added
+  server-verified purchases
+- **Conflict resolution**: if platform requirements conflict across target
+  platforms (e.g., different cloud save APIs with incompatible merge
+  strategies), document the conflict and propose an abstraction layer that
+  accommodates all platforms; never implement platform-specific behavior
+  without the abstraction boundary

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

@@ -0,0 +1,87 @@
+---
+name: review-economy
+description: Review economy design for inflation trajectories, exploit vectors, ethical monetization, and legal compliance
+summary: "Multi-pass review of economy design checking inflation/deflation trajectories, exploit vectors, ethical monetization compliance, pay-to-win detection, legal compliance per market, progression-monetization separation, and live-service sustainability."
+phase: "specification"
+order: 869
+dependencies: [economy-design]
+outputs: [docs/reviews/specification-review-economy.md]
+conditional: "if-needed"
+reads: []
+knowledge-base: [review-game-economy, review-step-template, multi-model-review-dispatch]
+---
+
+## Purpose
+Multi-pass review of the economy design targeting economy-specific failure modes:
+unchecked inflation or deflation trajectories, exploitable currency conversion
+paths, predatory monetization patterns, pay-to-win competitive advantages,
+legal non-compliance per target market, broken progression-monetization
+separation, and unsustainable live-service economy plans.
+
+Economy bugs discovered in live service cost orders of magnitude more to fix
+than those caught at design time — a duplication exploit discovered post-launch
+can destroy an economy in hours, and rebalancing a live economy with real-money
+purchases has legal implications. This review catches these failures before
+implementation begins.
+
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
+## Conditional Evaluation
+Enable when: economy-design is enabled (i.e., the game has virtual currencies,
+resource systems, loot tables, or monetization mechanics). If economy-design
+runs, this review must follow it.
+
+Skip when: economy-design is skipped (i.e., the game has no resource economy).
+No economy design means no economy review.
+
+## Inputs
+- docs/economy-design.md (required) — economy specification to review
+- docs/game-design.md (required) — core loop and progression mechanics for cross-reference
+- docs/plan.md (required) — target markets and business model for legal compliance verification
+
+## Expected Outputs
+- docs/reviews/specification-review-economy.md — findings and resolution log
+- docs/economy-design.md — updated with fixes
+- docs/reviews/economy/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/economy/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/economy/gemini-review.json (depth 4+, if available) — raw Gemini findings
+
+## Quality Criteria
+- (mvp) Inflation/deflation trajectory verified: currency generation and removal rates produce a stable or managed economy over the player lifecycle
+- (mvp) Exploit vectors audited: duplication, overflow, conversion rate manipulation, and timing exploits identified and mitigated at design level
+- (mvp) Ethical monetization verified: no pay-to-win advantages in PvP contexts, spending limit awareness mechanisms present, no predatory patterns targeting vulnerable players
+- (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 economy-design.md and re-validated
+- (deep) Legal compliance verified per target market: probability disclosure, age-gating, spending limits, loot box classification
+- (deep) Progression-monetization separation verified: removing all real-money paths leaves a satisfying progression experience
+- (deep) Live-service sustainability checked: seasonal economy additions do not compound inflation, event currencies have clear expiration or conversion paths
+- (deep) Economy simulation formulas verified for mathematical consistency (no negative balances, no infinite loops, no unreachable milestones)
+- (mvp) Review report includes explicit Readiness Status section
+- (mvp) Downstream readiness confirmed — no unresolved P0 or P1 findings remain
+- (depth 4+) Multi-model findings synthesized: Consensus, Majority, or Divergent with user escalation
+
+## Methodology Scaling
+- **deep**: All 7 review passes (Inflation Trajectory, Exploit Vectors,
+  Ethical Monetization, Pay-to-Win Detection, Legal Compliance,
+  Progression-Monetization Separation, Live-Service Sustainability).
+  Multi-model review dispatched to Codex and Gemini if available, with
+  graceful fallback to Claude-only enhanced review.
+- **mvp**: Three passes — Inflation Trajectory, Exploit Vectors, and Ethical
+  Monetization only.
+- **custom:depth(1-5)**:
+  - Depth 1: two passes — Inflation Trajectory and Exploit Vectors only.
+  - Depth 2: three passes — add Ethical Monetization compliance.
+  - Depth 3: five passes — add Pay-to-Win Detection and Legal Compliance.
+  - 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/economy/, preserve prior findings still valid.
+
+## Update Mode Specifics
+- **Detect**: `docs/reviews/specification-review-economy.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/specification/review-game-ui.md

@@ -0,0 +1,73 @@
+---
+name: review-game-ui
+description: Review game UI specification for completeness, accessibility coverage, and controller navigation
+summary: "Multi-pass review of game UI spec checking HUD clarity, menu completeness, controller accessibility, settings coverage, FTUE effectiveness, state machine completeness, and platform shell compliance."
+phase: "specification"
+order: 864
+dependencies: [game-ui-spec]
+outputs: [docs/reviews/specification-review-game-ui.md]
+conditional: null
+reads: []
+knowledge-base: [review-game-design, game-accessibility, review-step-template, multi-model-review-dispatch]
+---
+
+## Purpose
+Review the game UI specification for completeness, accessibility compliance,
+and controller navigation coverage. This is a multi-pass review targeting
+game-UI-specific failure modes: HUD information overload, incomplete menu
+hierarchies, missing controller navigation paths, inadequate settings coverage,
+ineffective FTUE design, incomplete UI state machines, and platform shell
+non-compliance.
+
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
+## Inputs
+- docs/game-ui-spec.md (required) — spec to review
+- docs/game-design.md (required) — for mechanic-to-HUD coverage verification
+- docs/game-accessibility.md (required) — for accessibility requirement compliance
+- docs/input-controls-spec.md (required) — for controller navigation consistency
+
+## Expected Outputs
+- docs/reviews/specification-review-game-ui.md — findings and resolution log
+- docs/game-ui-spec.md — updated with fixes
+- docs/reviews/game-ui/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/game-ui/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/game-ui/gemini-review.json (depth 4+, if available) — raw Gemini findings
+
+## Quality Criteria
+- (mvp) Every GDD mechanic with player-visible feedback has a corresponding HUD element or UI flow
+- (mvp) Controller navigation verified: every menu screen is reachable and has defined focus order
+- (mvp) Accessibility requirements from game-accessibility.md are reflected in UI spec (colorblind palette, font scaling, subtitle rendering)
+- (mvp) Settings screen covers all five minimum categories (gameplay, video, audio, controls, accessibility)
+- (mvp) Every finding categorized P0-P3 with specific screen, element, and issue
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to game-ui-spec.md and re-validated
+- (deep) FTUE teaches all core loop mechanics — no mechanic requires undocumented player discovery
+- (deep) UI state machines cover all transitions (no orphaned states, no missing error/disconnect states)
+- (deep) Platform shell compliance verified (console certification UI requirements)
+- (mvp) Review report includes explicit Readiness Status section
+- (mvp) Downstream readiness confirmed — no unresolved P0 or P1 findings remain
+- (depth 4+) Multi-model findings synthesized: Consensus, Majority, or Divergent with user escalation
+
+## Methodology Scaling
+- **deep**: Full multi-pass review covering HUD clarity, menu completeness,
+  controller navigation, accessibility compliance, FTUE effectiveness, state
+  machine completeness, and platform shell compliance. Multi-model review
+  dispatched if available.
+- **mvp**: HUD coverage and controller navigation pass only.
+- **custom:depth(1-5)**:
+  - Depth 1: HUD-to-mechanic coverage and basic controller navigation pass (1 review pass)
+  - Depth 2: add settings completeness and accessibility compliance passes (2 review passes)
+  - Depth 3: add FTUE effectiveness and UI state machine passes (4 review passes)
+  - Depth 4: add external model review of UI completeness (4 review passes + external dispatch)
+  - Depth 5: multi-model review with reconciliation (4 review passes + multi-model synthesis)
+
+## Mode Detection
+Re-review mode if previous review exists. If multi-model review artifacts exist
+under docs/reviews/game-ui/, preserve prior findings still valid.
+
+## Update Mode Specifics
+- **Detect**: `docs/reviews/specification-review-game-ui.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