@zigrivers/scaffold 3.4.1 → 3.5.0

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

@@ -0,0 +1,89 @@
+---
+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
+
+## 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

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,83 @@
+---
+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: []
+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
+
+## 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