@zigrivers/scaffold 3.4.1 → 3.5.1

package/content/pipeline/quality/analytics-telemetry.md

@@ -0,0 +1,98 @@
+---
+name: analytics-telemetry
+description: Define event taxonomy, crash telemetry, KPI funnels, data pipeline, and privacy compliance for game analytics
+summary: "Defines the game analytics layer — event taxonomy with schema versioning, crash telemetry for all games, expanded KPIs and funnels for live-service, data pipeline architecture, offline buffering, and privacy compliance (GDPR/COPPA)."
+phase: "quality"
+order: 962
+dependencies: [game-design-document]
+outputs: [docs/analytics-plan.md]
+conditional: null
+reads: [system-architecture, operations, economy-design]
+knowledge-base: [game-liveops-analytics]
+---
+
+## Purpose
+Define the analytics and telemetry strategy that provides data-driven insight
+into player behavior, game health, and business performance. Analytics exists on
+a spectrum: every game needs crash telemetry and basic session tracking, while
+live-service games need full KPI dashboards, funnel analysis, A/B testing
+infrastructure, and real-time alerting.
+
+This plan establishes a structured event taxonomy — a shared vocabulary of
+named events with versioned schemas — so that every system emitting telemetry
+uses consistent event names, payload shapes, and semantic conventions. Without
+a taxonomy, analytics data becomes a disorganized collection of ad-hoc events
+that analysts cannot reliably query.
+
+The plan also addresses the data pipeline end-to-end: client-side event
+buffering (critical for mobile and offline scenarios), transport and ingestion,
+storage and querying, and privacy compliance. GDPR consent flows, COPPA
+age-gating, and data retention policies must be designed into the telemetry
+system — not retrofitted after launch.
+
+## Inputs
+- docs/game-design.md (required) — core loop, progression, monetization model informing which events to track
+- docs/plan.md (required) — target platforms, target markets (privacy jurisdiction), business model
+- docs/system-architecture.md (optional, forward-read) — backend service topology for data pipeline integration
+- docs/operations-runbook.md (optional, forward-read) — monitoring and alerting infrastructure to extend
+- docs/economy-design.md (optional, forward-read) — transaction events, currency flow metrics, monetization KPIs
+
+## Expected Outputs
+- docs/analytics-plan.md — event taxonomy, crash telemetry specification, KPI
+  definitions, data pipeline architecture, offline buffering strategy, QA
+  validation plan, and privacy compliance
+
+## Quality Criteria
+- (mvp) Event taxonomy defined: hierarchical naming convention (category.action.label), payload schema per event, schema version field for forward compatibility
+- (mvp) Crash telemetry specified for all platforms: crash report collection (stack traces, device info, game state snapshot), symbolication pipeline, crash-free session rate target
+- (mvp) Session tracking: session start/end events, session duration, platform and device metadata, build version
+- (mvp) QA validation plan: how to verify events fire correctly (debug overlay, event log viewer, automated event assertion tests), schema validation at ingestion
+- (mvp) Privacy compliance: GDPR consent flow (opt-in before tracking in EU), COPPA handling (no PII collection for under-13), data retention policy with deletion capability
+- (deep) KPI definitions for live-service: DAU/MAU, retention (D1/D7/D30), session length distribution, revenue per user (ARPU/ARPPU), conversion funnel stages
+- (deep) Funnel analysis: player progression funnel (tutorial → first session → core loop engagement → retention), monetization funnel (browse → view item → purchase → repeat purchase), churn prediction signals
+- (deep) A/B testing infrastructure: experiment assignment, variant tracking, statistical significance methodology, guardrail metrics that halt experiments
+- (deep) Data pipeline architecture: client-side batching and offline buffering (queue events when offline, flush on reconnect with deduplication), transport (HTTPS batch POST with retry), ingestion service, storage (event warehouse), query layer
+- (deep) Real-time alerting: crash rate spike detection, revenue anomaly detection, concurrent player count monitoring, automated incident creation from telemetry thresholds
+
+### Live-Service Conditional Sections
+When the game includes live-service elements (battle passes, seasonal content,
+live events, real-money monetization), the analytics plan expands to include:
+- Economy health metrics: currency inflation rate, sink/faucet ratio tracking, whale concentration index
+- Content engagement metrics: event participation rate, content completion rate, seasonal retention lift
+- Matchmaking quality metrics: queue times, skill rating accuracy, match satisfaction survey correlation
+
+## Methodology Scaling
+- **deep**: Full analytics plan with comprehensive event taxonomy, crash
+  telemetry, live-service KPI suite, funnel analysis, A/B testing
+  infrastructure, data pipeline architecture with offline buffering, real-time
+  alerting, and privacy compliance per jurisdiction. 15-25 pages.
+- **mvp**: Event taxonomy, crash telemetry, session tracking, QA validation
+  plan, and privacy compliance essentials. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: crash telemetry and session tracking with basic event naming convention.
+  - Depth 2: add structured event taxonomy with schema versioning and privacy compliance.
+  - Depth 3: add KPI definitions, progression funnel, QA validation plan, and offline buffering strategy.
+  - Depth 4: add A/B testing infrastructure, data pipeline architecture, monetization funnel, and real-time alerting.
+  - Depth 5: full specification with economy health metrics, matchmaking quality metrics, churn prediction, and multi-jurisdiction privacy compliance.
+
+## Mode Detection
+Check for docs/analytics-plan.md. If it exists, operate in update mode: read
+existing plan and diff against current GDD features and system architecture.
+Preserve existing event taxonomy entries, KPI definitions, and privacy
+compliance decisions. Add events for new gameplay systems. Update pipeline
+architecture if system-architecture changed backend topology.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/analytics-plan.md exists
+- **Preserve**: event taxonomy entries (never rename events that may already be
+  in production), KPI definitions and thresholds, privacy compliance decisions,
+  crash telemetry configuration, data retention policy
+- **Triggers for update**: GDD added new gameplay systems (new events needed),
+  system architecture changed backend topology (pipeline integration needs
+  updating), economy design added new transaction types (new monetization
+  events), target markets changed (new privacy jurisdictions), operations
+  runbook changed monitoring infrastructure
+- **Conflict resolution**: if a new feature requires an event name that
+  conflicts with an existing taxonomy entry, version the new event rather than
+  renaming the existing one; never break backward compatibility of event
+  schemas already in production

package/content/pipeline/quality/live-ops-plan.md

@@ -0,0 +1,99 @@
+---
+name: live-ops-plan
+description: Plan content cadence, event systems, hotfix deployment, maintenance windows, and content update pipeline
+summary: "Plans the live operations strategy — content cadence aligned to player retention, event system design, hotfix deployment procedures, maintenance windows, and the content update pipeline from creation through certification to release."
+phase: "quality"
+order: 963
+dependencies: [game-design-document, analytics-telemetry]
+outputs: [docs/live-ops-plan.md]
+conditional: "if-needed"
+reads: [operations]
+knowledge-base: [game-liveops-analytics]
+---
+
+## Purpose
+Define the live operations strategy that sustains the game after launch. Live
+ops is the practice of operating a game as a service — delivering regular
+content updates, running time-limited events, deploying hotfixes without
+extended downtime, and using analytics data to inform the content roadmap.
+
+This plan bridges the gap between development (building the game) and
+operations (running the game). It requires input from game design (what
+content to deliver), analytics (which metrics indicate health), and
+infrastructure (how to deploy updates safely). Without a live-ops plan,
+post-launch content delivery becomes reactive and ad-hoc, leading to player
+churn and operational incidents.
+
+The plan covers five areas: content cadence (what ships and when), event
+system design (how time-limited events are authored, scheduled, and
+delivered), hotfix deployment (how to ship critical fixes outside the regular
+cadence), maintenance windows (how to communicate and execute downtime), and
+the content update pipeline (the workflow from content creation through QA,
+certification, staging, and release).
+
+## Conditional Evaluation
+Enable when: the project configuration `onlineServices` includes `live-ops`,
+or the GDD describes any of the following — seasonal content drops, battle
+passes, live events, post-launch content roadmap, games-as-a-service model,
+regular content updates, or any ongoing content delivery after initial release.
+
+Skip when: the game is a ship-and-done product with no planned post-launch
+content updates — premium single-player titles, arcade games, or any project
+where the launch build is the final build (aside from bug-fix patches).
+
+## Inputs
+- docs/game-design.md (required) — content types, event mechanics, seasonal structure
+- docs/analytics-plan.md (required) — KPIs that drive live-ops decisions, player retention metrics
+- docs/plan.md (required) — launch timeline, post-launch support commitment
+- docs/operations-runbook.md (optional, forward-read) — deployment pipeline, rollback procedures, monitoring infrastructure
+
+## Expected Outputs
+- docs/live-ops-plan.md — content cadence, event system design, hotfix
+  deployment procedures, maintenance windows, and content update pipeline
+
+## Quality Criteria
+- (mvp) Content cadence defined: update frequency (weekly/biweekly/seasonal), content types per cadence tier (minor balance patches vs. major content drops), and target release day/time
+- (mvp) Event system design: how time-limited events are authored (data-driven, not code-driven), event lifecycle (announcement → active → wind-down → rewards), event scheduling (calendar-based with remote config)
+- (mvp) Hotfix deployment procedure: criteria for emergency hotfix (severity classification), approval chain, deployment steps, rollback trigger, player communication template
+- (mvp) Maintenance window policy: scheduled maintenance cadence, advance notice period, expected duration, communication channels (in-game, social media, status page)
+- (deep) Content update pipeline: creation (design + art + engineering) → internal QA → playtest → certification (if console) → staging → canary release → full rollout → post-release monitoring
+- (deep) Content versioning and compatibility: how clients handle version mismatches, forced update vs. graceful degradation, asset bundle versioning for hot-loaded content
+- (deep) Live-ops calendar: quarterly content roadmap template with theme, headline feature, supporting events, and target retention metric per update
+- (deep) Feature flag and remote config integration: how live-ops uses feature flags for gradual rollout, kill switches for broken features, A/B testing for content variants
+- (deep) Incident response for live-ops: when a content update causes issues (broken economy, exploitable event, server instability), escalation path, rollback decision tree, and player compensation policy
+
+## Methodology Scaling
+- **deep**: Full live-ops plan with quarterly content calendar, event system
+  architecture, content update pipeline with certification gates, hotfix
+  procedures with severity classification, maintenance window policy, feature
+  flag integration, live-ops incident response, and player compensation
+  framework. 15-25 pages.
+- **mvp**: Content cadence, basic event system design, hotfix deployment
+  procedure, and maintenance window policy. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: content update frequency and basic hotfix deployment procedure.
+  - Depth 2: add event system design and maintenance window policy.
+  - Depth 3: add content update pipeline, content versioning strategy, and live-ops calendar template.
+  - Depth 4: add feature flag integration, incident response for live-ops, and certification gates in content pipeline.
+  - Depth 5: full plan with player compensation framework, A/B testing for content variants, retention-driven content prioritization, and cross-platform content delivery synchronization.
+
+## Mode Detection
+Check for docs/live-ops-plan.md. If it exists, operate in update mode: read
+existing plan and diff against current GDD content plans and analytics KPIs.
+Preserve existing content cadence, event system design, and hotfix procedures.
+Update pipeline stages if operations runbook changed deployment infrastructure.
+Add new event types if GDD expanded seasonal content.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/live-ops-plan.md exists
+- **Preserve**: content cadence and release schedule, event system design,
+  hotfix deployment procedures, maintenance window policy, live-ops calendar
+  entries, player compensation precedents
+- **Triggers for update**: GDD added new content types or event mechanics,
+  analytics plan changed KPIs that drive content decisions, operations runbook
+  changed deployment pipeline, target platforms changed (new certification
+  requirements in content pipeline)
+- **Conflict resolution**: if content cadence changes conflict with
+  certification timelines (e.g., weekly updates impossible with console cert
+  turnaround), document the constraint and propose a cadence that accommodates
+  all target platforms; never promise a cadence the pipeline cannot sustain

package/content/pipeline/quality/platform-cert-prep.md

@@ -0,0 +1,129 @@
+---
+name: platform-cert-prep
+description: Per-platform certification checklists for console, mobile, VR/AR, and PC storefronts
+summary: "Prepares platform certification checklists — Sony TRC, Microsoft XR, Nintendo Lotcheck, App Store, Google Play, Steam Deck compatibility — covering sign-in/out, entitlements, achievements, parental controls, ratings, controller disconnect, suspend/resume, and error messages."
+phase: "quality"
+order: 964
+dependencies: [game-accessibility, performance-budgets, game-ui-spec, input-controls-spec]
+outputs: [docs/platform-cert-checklist.md]
+conditional: "if-needed"
+reads: [save-system-spec, netcode-spec, audio-design, localization-plan, online-services-spec, modding-ugc-spec]
+knowledge-base: [game-platform-certification, review-platform-cert, game-vr-ar-design]
+---
+
+## Purpose
+Prepare per-platform certification checklists that ensure the game passes
+first-party submission requirements on every target platform. Platform
+certification (also called Technical Requirements Checklists, or TRCs) is the
+mandatory review process that console manufacturers, mobile storefronts, and
+VR/AR platforms require before a title can be published. Failing certification
+delays launch by weeks or months.
+
+Each platform has unique requirements that touch nearly every system in the
+game: user account sign-in/out flow, entitlement and DLC verification,
+achievement/trophy integration, parental controls and age rating compliance,
+controller disconnect handling, suspend/resume lifecycle, error message
+standards, and platform-specific shell behavior (Quick Resume on Xbox,
+Activities on PlayStation, etc.).
+
+This step consolidates requirements from across the codebase — accessibility,
+performance budgets, UI, input controls, save systems, networking, audio,
+localization, online services, and modding — into per-platform checklists
+that QA teams can verify systematically before submission.
+
+## Conditional Evaluation
+Enable when: `targetPlatforms` includes any console (PlayStation, Xbox,
+Nintendo Switch), mobile (iOS, Android), VR/AR (Meta Quest, PlayStation VR2,
+Apple Vision Pro), or PC storefronts with compatibility review programs
+(Steam Deck Verified). Desktop-only games distributed through open platforms
+(itch.io, self-hosted) without certification programs do not need this step.
+
+Skip when: the game targets only open PC platforms (Windows/macOS/Linux via
+direct distribution or itch.io) with no storefront certification requirements.
+Steam itself does not have a formal certification process (beyond basic content
+review), but Steam Deck Verified is a certification program and triggers this
+step.
+
+## Inputs
+- docs/game-accessibility.md (required) — accessibility features to verify against platform accessibility requirements
+- docs/performance-budgets.md (required) — frame rate and memory targets per platform
+- docs/game-ui-spec.md (required) — UI flows for sign-in, error messages, platform shell integration
+- docs/input-controls-spec.md (required) — controller support, input remapping, disconnect handling
+- docs/plan.md (required) — target platforms and target ratings
+- docs/save-system-spec.md (optional, forward-read) — save/load, cloud save, platform storage integration
+- docs/netcode-spec.md (optional, forward-read) — network error handling, NAT traversal, platform networking APIs
+- docs/audio-design.md (optional, forward-read) — audio output requirements, platform audio policies (e.g., mute on focus loss)
+- docs/localization-plan.md (optional, forward-read) — supported languages per platform, platform-mandated language requirements
+- docs/online-services-spec.md (optional, forward-read) — platform service integration (PSN, Xbox Live, Nintendo Online)
+- docs/modding-ugc-spec.md (optional, forward-read) — UGC policies per platform, content moderation requirements
+
+## Expected Outputs
+- docs/platform-cert-checklist.md — per-platform certification checklists
+  with specific requirements, verification steps, and pass/fail criteria
+
+## Quality Criteria
+- (mvp) Per-platform checklist generated for every target platform: each requirement has a description, verification step, and pass/fail criterion
+- (mvp) Sign-in/out flow verified: platform account sign-in on boot, sign-out during gameplay (return to title screen or graceful disconnect), account switching (where platform supports it)
+- (mvp) Controller disconnect handling: game pauses or shows reconnection prompt, no input loss or crash, reconnection resumes correctly
+- (mvp) Suspend/resume lifecycle: game state preserved on suspend, no data loss, network reconnection on resume, no stale UI
+- (mvp) Error messages follow platform guidelines: platform-specific error codes where required, user-friendly language, no raw exception text, retry/cancel options
+- (deep) Entitlement and DLC verification: license check on boot and periodically during gameplay, graceful handling of revoked entitlements, DLC content gating
+- (deep) Achievement/trophy integration: unlock conditions mapped to platform achievement APIs, offline unlock queuing, no duplicate unlocks, required platinum/1000G structure (PlayStation/Xbox)
+- (deep) Parental controls and age rating: respect platform-level restrictions (communication, purchases, content visibility), age rating compliance (ESRB, PEGI, CERO, GRAC, USK) per target market
+- (deep) Platform-specific shell behavior: Quick Resume (Xbox), Activities (PlayStation), sleep mode (Nintendo Switch), App Clips (iOS), Instant Apps (Android)
+- (deep) Performance certification: frame rate within platform-mandated minimums (30fps floor on console, thermal throttling handling on mobile), memory within platform limits, load time requirements
+- (deep) Accessibility certification: platform-mandated accessibility features (Xbox Accessibility Guidelines, PlayStation accessibility requirements, Apple accessibility standards)
+- (deep) Network certification: NAT type handling, platform matchmaking API compliance, graceful degradation on network loss, bandwidth limits
+
+### Console-Specific Sections
+- **PlayStation (TRC)**: PSN sign-in, trophy set structure, Activity Cards, suspend/resume with network reconnect, PS VR2 comfort settings (if VR), content restriction API
+- **Xbox (XR)**: Xbox Live sign-in, achievement structure (1000G base + DLC), Quick Resume support, Game Pass considerations, Xbox Accessibility Guidelines compliance
+- **Nintendo Switch (Lotcheck)**: Nintendo Account integration, controller grip modes (handheld, tabletop, docked), sleep mode save, touch screen support (handheld), HD Rumble guidelines
+
+### Mobile-Specific Sections
+- **iOS (App Store Review)**: App Store Review Guidelines compliance, in-app purchase via StoreKit (no external payment links), privacy nutrition labels, App Tracking Transparency, Universal Links, background audio policy
+- **Android (Google Play)**: Google Play policies, billing library integration, target API level requirements, adaptive icons, back gesture handling, foldable/tablet layout
+
+### PC Storefront Sections
+- **Steam Deck Verified**: controller-native UI (no mandatory mouse/keyboard), readable text at 7" 800p, default graphics preset within thermal envelope, Proton compatibility, suspend/resume via OS
+
+### VR/AR-Specific Sections
+- **Meta Quest**: comfort rating (comfortable/moderate/intense), guardian boundary handling, passthrough integration, hand tracking fallback, performance targets (72/90/120Hz)
+- **Apple Vision Pro**: visionOS design guidelines, spatial UI placement, eye tracking privacy, SharePlay integration
+
+## Methodology Scaling
+- **deep**: Comprehensive per-platform checklists with every TRC/XR/Lotcheck
+  requirement mapped, verification procedures, automated compliance test
+  suggestions, platform-specific shell integration, and certification
+  submission timeline with resubmission contingency. 20-35 pages.
+- **mvp**: Core certification requirements per platform (sign-in, controller
+  disconnect, suspend/resume, error messages) with basic verification steps.
+  5-10 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: sign-in/out, controller disconnect, and suspend/resume checklists per platform.
+  - Depth 2: add error message compliance, entitlement verification, and basic achievement integration.
+  - Depth 3: add parental controls, age rating compliance, performance certification targets, and platform shell behavior.
+  - Depth 4: add accessibility certification, network certification, platform-specific detailed requirements, and automated compliance test suggestions.
+  - Depth 5: full checklists with certification submission timeline, resubmission contingency plan, platform relationship management notes, and cross-platform compliance matrix.
+
+## Mode Detection
+Check for docs/platform-cert-checklist.md. If it exists, operate in update
+mode: read existing checklists and diff against current platform targets,
+accessibility features, performance budgets, and input controls. Preserve
+existing pass/fail results and verification notes. Add checklists for new
+target platforms. Update requirements if platform SDKs or policies changed.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/platform-cert-checklist.md exists
+- **Preserve**: existing pass/fail verification results, platform-specific
+  implementation notes, certification submission history, waiver/exception
+  records, platform contact information
+- **Triggers for update**: target platforms changed (new platform added or
+  removed), accessibility spec updated (new features to verify), performance
+  budgets changed (new targets to certify), input controls spec changed
+  (controller handling updates), platform SDK or policy update (new TRC/XR
+  version), save system or networking spec changed
+- **Conflict resolution**: if a requirement from one platform conflicts with
+  another platform's requirement (e.g., different mandatory button mappings),
+  document both requirements and propose a platform-adaptive implementation;
+  never sacrifice one platform's certification for another

package/content/pipeline/quality/playtest-plan.md

@@ -0,0 +1,84 @@
+---
+name: playtest-plan
+description: Design playtest strategy with types, scheduling, feedback collection, FTUE observation, and balance testing
+summary: "Designs your playtest strategy — internal, focused, and external playtests tied to milestone gates — with feedback templates, FTUE observation protocols, balance testing methodology, and participant recruitment plans."
+phase: "quality"
+order: 961
+dependencies: [game-design-document, user-stories]
+outputs: [docs/playtest-plan.md]
+conditional: null
+reads: [analytics-telemetry]
+knowledge-base: [game-testing-strategy, game-milestone-definitions]
+---
+
+## Purpose
+Define the complete playtesting strategy that validates game feel, balance,
+usability, and fun throughout development. Playtesting is distinct from QA
+testing (which validates correctness) — playtesting validates that the game is
+enjoyable, understandable, and appropriately challenging for the target audience.
+
+This plan covers three playtest tiers: internal playtests (team members testing
+daily builds), focused playtests (targeted sessions with specific test goals
+and recruited participants), and external playtests (public or semi-public
+tests for scale validation and market feedback). Each tier maps to development
+milestones — internal playtests begin at First Playable, focused playtests at
+Alpha, and external playtests at Beta.
+
+The plan also establishes feedback collection methodology — standardized
+templates, observation protocols, and metrics — so that playtest data drives
+design decisions rather than anecdotal impressions.
+
+## Inputs
+- docs/game-design.md (required) — core loop, progression, difficulty model, target audience
+- docs/user-stories.md (required) — acceptance criteria defining expected player experience
+- docs/plan.md (required) — milestone schedule and target platforms
+
+## Expected Outputs
+- docs/playtest-plan.md — playtest types, schedule, feedback templates, FTUE
+  observation protocol, balance testing methodology, and recruitment plan
+
+## Quality Criteria
+- (mvp) Three playtest tiers defined (internal, focused, external) with distinct goals, participant profiles, and session formats
+- (mvp) Playtest schedule tied to project milestones: which tier runs at which milestone, with minimum session count per gate
+- (mvp) Feedback template defined with structured fields: task completion (yes/no), difficulty rating (scale), confusion points (free-text), fun rating (scale), and session metadata (build version, platform, duration)
+- (mvp) FTUE (First-Time User Experience) observation protocol: what to observe (time-to-first-action, tutorial completion rate, first death/failure point), how to record (screen capture + observer notes), and when to intervene (never during observation, debrief after)
+- (deep) Balance testing methodology: metrics to collect per gameplay system (win rates, resource accumulation curves, time-to-completion per level/encounter), acceptable variance ranges, and rebalancing trigger thresholds
+- (deep) Participant recruitment plan: target demographics matching game audience, recruitment channels, screening criteria, compensation/incentive structure, NDA requirements for pre-release tests
+- (deep) Playtest environment specification: hardware requirements, network conditions to simulate, build distribution method (Steam playtest, TestFlight, side-loading), telemetry collection during sessions
+- (deep) Playtest-to-design feedback loop: how findings are triaged (critical/major/minor), who owns resolution, turnaround time targets between playtest and design response
+- (deep) Accessibility playtest sessions: dedicated sessions with players using assistive technologies to validate accessibility features from game-accessibility spec
+- (deep) Telemetry integration specified: which analytics events are collected during playtest sessions, how automated metrics complement observer notes
+
+## Methodology Scaling
+- **deep**: Full playtest plan covering all three tiers with detailed schedules,
+  observation protocols, balance testing with statistical methodology, recruitment
+  pipeline, environment specs, and feedback-to-design triage process. 12-20 pages.
+- **mvp**: Internal and focused playtest definitions, milestone-linked schedule,
+  basic feedback template, and FTUE observation checklist. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: internal playtest cadence and basic feedback template only.
+  - Depth 2: add focused playtest definition and FTUE observation protocol.
+  - Depth 3: add milestone-linked schedule, balance testing metrics, and participant screening criteria.
+  - Depth 4: add external playtest plan, recruitment pipeline, environment specification, and accessibility playtest sessions.
+  - Depth 5: full plan with statistical balance methodology, feedback-to-design triage process, and playtest iteration tracking across milestones.
+
+## Mode Detection
+Check for docs/playtest-plan.md. If it exists, operate in update mode: read
+existing plan and diff against current GDD progression/difficulty model and
+milestone schedule. Preserve existing feedback templates, observation protocols,
+and recruitment criteria. Update schedule if milestones shifted. Add new
+playtest sessions if GDD added new gameplay systems requiring validation.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/playtest-plan.md exists
+- **Preserve**: feedback templates, FTUE observation protocol, recruitment
+  criteria, balance testing thresholds, participant compensation structure,
+  existing playtest results and findings
+- **Triggers for update**: GDD changed core loop or difficulty model (balance
+  testing needs revision), milestone schedule shifted (playtest dates need
+  updating), user stories changed acceptance criteria (new scenarios to test),
+  accessibility spec updated (new assistive technology sessions needed)
+- **Conflict resolution**: if milestone changes compress the playtest schedule,
+  prioritize focused playtests over external playtests and flag the reduced
+  testing coverage for user decision; never remove a playtest tier without
+  approval

package/content/pipeline/specification/art-bible.md

@@ -0,0 +1,87 @@
+---
+name: art-bible
+description: Define art style, per-type asset specifications, naming conventions, DCC pipeline, LOD strategy, and collision layers
+summary: "Establishes the visual identity and technical art standards — art style pillars, per-type asset specs (3D models, 2D sprites, VFX, animation), naming conventions, DCC pipeline, LOD strategy, Git LFS mapping, and hitbox/collision layer definitions."
+phase: "specification"
+order: 866
+dependencies: [game-design-document, performance-budgets, content-structure-design]
+outputs: [docs/art-bible.md]
+conditional: null
+reads: []
+knowledge-base: [game-asset-pipeline, game-performance-budgeting, game-binary-vcs-strategy, review-art-bible]
+---
+
+## Purpose
+Define the complete art bible for the project — the authoritative reference for
+visual identity, technical art standards, and asset production workflows. This
+document bridges the creative vision from the GDD with the technical constraints
+from performance budgets to produce actionable specifications that every artist
+on the team follows.
+
+Games require per-type asset specifications because a character model, an
+environment prop, a VFX particle, and a UI sprite each have fundamentally
+different polygon budgets, texture requirements, animation constraints, and
+optimization strategies. Without an art bible, artists produce assets with
+inconsistent quality, naming, and technical specs — leading to pipeline
+failures, performance regressions, and visual incoherence.
+
+## Inputs
+- docs/game-design.md (required) — art style direction, world setting, character roster, environment types
+- docs/performance-budgets.md (required) — polygon budgets, texture memory budgets, draw call limits per platform
+- docs/content-structure/ (required) — content organization, asset directory structure, naming taxonomy
+- docs/plan.md (required) — target platforms informing quality tiers and LOD requirements
+
+## Expected Outputs
+- docs/art-bible.md — art style guide, per-type asset specs, naming conventions,
+  DCC pipeline, LOD strategy, Git LFS mapping, and collision layer definitions
+
+## Quality Criteria
+- (mvp) Art style pillars defined with concrete specifications: color palette as hex/RGB ranges, character proportion ratios, material property ranges (roughness, metallic), and reference images or "do/don't" visual descriptions per asset category
+- (mvp) Per-type asset specs documented: 3D models (poly budget, texture resolution, material slots), 2D sprites (resolution, atlas packing, animation frames), VFX (particle count, draw call budget, shader complexity), animation (bone count, clip length, blend tree structure)
+- (mvp) Naming conventions defined per asset type following content-structure-design taxonomy
+- (mvp) DCC pipeline documented: source tool → export format → engine import → validation
+- (mvp) LOD strategy defined with distance thresholds, poly reduction targets, and LOD count per asset category
+- (mvp) Hitbox and collision layer definitions for gameplay-critical assets (characters, projectiles, interactables, terrain)
+- (deep) Git LFS tracking rules mapped per file type with size thresholds and binary file extensions
+- (deep) Texture compression formats specified per platform (BCn for desktop/console, ASTC for mobile, ETC2 fallback)
+- (deep) Material and shader standards documented (PBR metallic-roughness vs specular-glossiness, shader LOD, material instance hierarchy)
+- (deep) Color grading and post-processing reference targets for consistent look across lighting scenarios
+- (deep) Asset validation automation: import hooks that reject out-of-budget assets before they enter version control
+
+## Methodology Scaling
+- **deep**: Full art bible with style guide, per-type asset specs for all
+  categories (character, environment, prop, VFX, UI, animation), DCC pipeline
+  with tool-specific export settings, LOD strategy with platform-specific
+  distance tables, Git LFS configuration, texture compression matrix,
+  material standards, collision layer map, and automated validation rules.
+  15-25 pages.
+- **mvp**: Art style pillars, per-type specs for primary asset categories,
+  naming conventions, basic LOD strategy, and collision layer definitions.
+  4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: art style pillars and primary asset type polygon/texture budgets only.
+  - Depth 2: add naming conventions, basic DCC export pipeline, and collision layer definitions.
+  - Depth 3: add LOD strategy with distance thresholds, Git LFS mapping, and per-platform texture formats.
+  - Depth 4: add material/shader standards, animation specs, VFX budgets, and asset validation automation.
+  - Depth 5: full art bible with color grading targets, cinematic asset specs, destructible environment specs, and art QA checklist.
+
+## Mode Detection
+Check for docs/art-bible.md. If it exists, operate in update mode: read
+existing art bible and diff against current GDD visual direction and
+performance budgets. Preserve existing art style pillars, naming conventions,
+and DCC pipeline decisions. Update per-type budgets if performance budgets
+changed. Add specs for new asset categories introduced by GDD changes.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/art-bible.md exists
+- **Preserve**: art style pillars, existing per-type asset specs, naming
+  conventions, DCC pipeline configuration, material standards, collision layer
+  definitions
+- **Triggers for update**: GDD changed visual direction or added new asset
+  categories, performance budgets revised polygon or texture memory limits,
+  content-structure-design changed directory layout or naming taxonomy, target
+  platforms changed (affects LOD tiers and texture compression)
+- **Conflict resolution**: if performance budget reductions require lowering
+  per-type asset specs, document the impact on visual quality with before/after
+  comparison notes and propose tiered quality settings rather than universal
+  downgrade; never silently lower art specs without flagging the visual impact

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

@@ -0,0 +1,97 @@
+---
+name: audio-design
+description: Define audio direction, SFX categories, adaptive music, middleware config, spatial audio, VO plan, and platform loudness targets
+summary: "Establishes audio direction, SFX category taxonomy, adaptive music system, middleware configuration (Wwise/FMOD), spatial audio setup, voice-over pipeline, platform-specific loudness targets (LUFS), and memory budget allocation from performance budgets."
+phase: "specification"
+order: 867
+dependencies: [game-design-document, performance-budgets, content-structure-design]
+outputs: [docs/audio-design.md]
+conditional: null
+reads: [narrative-bible]
+knowledge-base: [game-audio-design]
+---
+
+## Purpose
+Define the complete audio design specification — the authoritative reference for
+audio direction, middleware configuration, asset production standards, and
+runtime behavior. This document translates the emotional and mechanical needs
+from the GDD into concrete audio architecture decisions.
+
+Audio is a primary player feedback channel: it communicates spatial awareness
+(enemy footsteps behind you), game state (health low warning), emotional tone
+(rising tension before a boss), and mechanical timing (attack wind-up cues).
+Unlike visual assets which players consciously evaluate, audio operates
+subconsciously — players feel bad audio as "something is off" without
+identifying the cause. This makes early audio planning critical: middleware
+selection, bus hierarchy, and adaptive music architecture cannot be easily
+retrofitted once content production begins.
+
+**Note on forward-reads**: `narrative-bible` is listed as an optional read. On
+first generation it may not exist yet — in that case, define placeholder VO
+categories (protagonist, NPCs, narration) and mark them with
+`<!-- pending: narrative-bible -->` for a future update pass. When
+narrative-bible becomes available, these placeholders are filled in during
+update mode.
+
+## Inputs
+- docs/game-design.md (required) — mechanics, core loop, world setting, emotional tone informing audio direction
+- docs/performance-budgets.md (required) — audio memory budget, CPU budget for audio processing, streaming constraints
+- docs/content-structure/ (required) — audio asset directory structure, naming taxonomy
+- docs/plan.md (required) — target platforms informing loudness targets and format requirements
+- docs/narrative-bible.md (optional, forward-read) — character roster, dialogue structure, VO volume and language requirements
+
+## Expected Outputs
+- docs/audio-design.md — audio direction, SFX categories, adaptive music system,
+  middleware config, spatial audio, VO plan, loudness targets, and memory budget
+
+## Quality Criteria
+- (mvp) Audio direction defined: emotional tone per game context (exploration, combat, menu, cinematic), reference tracks or descriptive style pillars
+- (mvp) SFX categories defined with priority tiers: gameplay-critical (weapon, footstep, UI feedback), ambient (environment, weather), and cosmetic (character emotes, incidental)
+- (mvp) Adaptive music system documented: layered stems, horizontal re-sequencing, or vertical remixing approach with transition rules between game states
+- (mvp) Middleware selection documented with rationale (Wwise, FMOD, or engine-native) and bus hierarchy (master, music, SFX, ambient, VO, UI)
+- (mvp) Platform-specific loudness targets specified: -24 LUFS +/-2 for console, -18 LUFS +/-2 for mobile, with metering approach
+- (mvp) Audio memory budget allocated from performance budgets: streaming vs resident pools, per-platform limits
+- (deep) Spatial audio configuration: HRTF profiles, occlusion/obstruction model, attenuation curves, reverb zone strategy
+- (deep) VO pipeline documented: casting direction, recording spec (sample rate, bit depth, format), naming convention, localization workflow per language
+- (deep) Audio format matrix per platform: codec (Vorbis, Opus, ADPCM, platform-native), quality settings, streaming chunk size
+- (deep) Dynamic range management: compressor/limiter settings per bus, ducking rules (VO ducks music, gameplay SFX ducks ambient)
+- (deep) Accessibility audio: audio descriptions, mono downmix option, visual indicators for critical audio cues
+- (deep) SFX variation strategy documented: minimum variant count per sound event category, randomization rules (no-repeat, round-robin, weighted random), pitch and volume variation ranges
+
+## Methodology Scaling
+- **deep**: Full audio design with style guide, complete SFX taxonomy with
+  per-category specs, adaptive music system with state machine, middleware
+  configuration with bus hierarchy and effects chains, spatial audio setup,
+  VO pipeline with localization plan, per-platform loudness and format matrix,
+  dynamic range strategy, memory budget breakdown, and accessibility audio
+  plan. 15-25 pages.
+- **mvp**: Audio direction, primary SFX categories, basic adaptive music
+  approach, middleware selection, loudness targets, and memory budget
+  allocation. 4-8 pages.
+- **custom:depth(1-5)**:
+  - Depth 1: audio direction pillars and primary SFX category list only.
+  - Depth 2: add middleware selection, bus hierarchy, and loudness targets.
+  - Depth 3: add adaptive music system, memory budget allocation, and audio format per platform.
+  - Depth 4: add spatial audio configuration, VO pipeline, dynamic range management, and accessibility audio.
+  - Depth 5: full specification with localization VO plan, per-context audio profiling targets, procedural audio specs, and audio QA checklist.
+
+## Mode Detection
+Check for docs/audio-design.md. If it exists, operate in update mode: read
+existing audio design and diff against current GDD emotional direction and
+performance budgets. Preserve existing middleware selection, bus hierarchy,
+and adaptive music architecture. Update memory budgets if performance budgets
+changed. Fill VO placeholders when narrative-bible becomes available.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/audio-design.md exists
+- **Preserve**: middleware selection, bus hierarchy, adaptive music architecture,
+  spatial audio configuration, loudness targets, audio format decisions
+- **Triggers for update**: GDD changed emotional tone or added new game states
+  requiring music transitions, performance budgets revised audio memory or CPU
+  limits, content-structure-design changed audio asset organization,
+  narrative-bible created (fill VO placeholder sections), target platforms
+  changed (affects loudness targets and format requirements)
+- **Conflict resolution**: if performance budget reductions require lowering
+  audio memory allocation, document the impact on simultaneous voice count
+  and streaming quality with concrete tradeoff analysis; propose quality
+  tiers (high/medium/low) rather than universal quality reduction