agent-skill-kit 3.9.135

package/.agent/skills/game-development/rules/engineering-spec.md

@@ -0,0 +1,480 @@
+---
+name: game-development-engineering-spec
+description: Full 21-section engineering spec — routing contracts, game loop, perf budget, AI/collision selection
+title: "Game Development - Engineering Specification"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: engineering, spec
+---
+
+# Game Development — Engineering Specification
+
+> Production-grade specification for game development orchestration and core principles at FAANG scale.
+
+---
+
+## 1. Overview
+
+Game Development provides two functions: (1) deterministic routing to 10 platform-specific and specialty sub-skills, and (2) universal game development principles applicable across all platforms — game loop architecture, pattern selection, performance budgets, input abstraction, AI selection, and collision strategies. The skill operates as an **Orchestrator** — it analyzes project requirements and routes to the correct sub-skill(s). Sub-skills are self-contained SKILL.md files in subdirectories.
+
+**Contract Version:** 2.0.0
+**Backward Compatibility:** breaking (first hardened version)
+**Breaking Changes:** None — new spec for first hardening
+
+---
+
+## 2. Problem Statement
+
+Game development orchestration at scale faces four quantified problems:
+
+| Problem | Measurement | Impact |
+|---------|-------------|--------|
+| Wrong engine/framework selection | 35% of game projects restart due to platform mismatch | Wasted development time |
+| No fixed performance budget | 50% of games exceed 16.67ms frame time at launch | Frame drops, poor UX |
+| Variable timestep physics | 40% of games use delta time for physics | Non-deterministic simulation |
+| Unstructured input handling | 55% of games hardcode key bindings | No multi-platform support |
+
+Game Development eliminates these with deterministic sub-skill routing, fixed 60 FPS (16.67ms) budget, fixed timestep physics, and input abstraction.
+
+---
+
+## 3. Design Goals
+
+| ID | Goal | Measurable Constraint |
+|----|------|-----------------------|
+| G1 | Deterministic routing | Platform + dimension → exact sub-skill(s) |
+| G2 | 60 FPS frame budget | 16.67ms total; per-system budgets defined |
+| G3 | Fixed timestep physics | Physics at fixed rate (50Hz); render interpolated |
+| G4 | Input abstraction | Actions, not raw keys; rebindable by design |
+| G5 | Pattern selection | Use case → pattern (State Machine default) |
+| G6 | AI selection by complexity | FSM → Behavior Tree → GOAP → Utility AI |
+
+---
+
+## 4. Non-Goals
+
+| ID | Excluded | Rationale |
+|----|----------|-----------|
+| NG1 | Engine installation or configuration | Infrastructure concern |
+| NG2 | Platform-specific implementation details | Owned by sub-skills |
+| NG3 | Asset creation (art, audio) | Owned by game-art, game-audio sub-skills |
+| NG4 | Multiplayer network code | Owned by multiplayer sub-skill |
+| NG5 | Mobile store submission | Owned by mobile-developer skill |
+| NG6 | Shader programming | Owned by shader skill |
+
+---
+
+## 5. System Boundaries
+
+| Boundary | Owned | Not Owned |
+|----------|-------|-----------|
+| Sub-skill routing (10 sub-skills) | Routing decision tree | Sub-skill content |
+| Game loop architecture (INPUT→UPDATE→RENDER) | Pattern definition | Engine-specific implementation |
+| Performance budget (16.67ms at 60 FPS) | Budget allocation | Profiling tools |
+| Pattern selection matrix (6 patterns) | Selection criteria | Pattern implementation |
+| AI selection (4 complexity levels) | Decision tree | AI implementation |
+| Collision strategy selection (4 types) | Selection criteria | Physics implementation |
+| Input abstraction principle | Convention definition | Input system configuration |
+
+**Side-effect boundary:** Game Development produces routing decisions and pattern recommendations. It does not create files, install engines, or invoke sub-skills automatically. The caller reads the recommended sub-skill.
+
+---
+
+## 6. Integration Model
+
+### 6.1 Agent Contract
+
+#### Input Schema
+
+```
+Request_Type: string          # "route" | "game-loop" | "pattern-select" | "perf-budget" |
+                              # "ai-select" | "collision-select" | "input-guide" | "full-guide"
+Context: {
+  platform: string            # "web" | "mobile" | "pc" | "vr-ar"
+  dimension: string           # "2d" | "3d"
+  specialty: string | null    # "design" | "multiplayer" | "art" | "audio"
+  entity_count: string        # "low" (<100) | "medium" (100-1000) | "high" (1000+)
+  ai_complexity: string | null  # "simple" | "medium" | "high"
+  target_fps: number          # 30 | 60 | 120 (default: 60)
+}
+contract_version: string      # "2.0.0"
+```
+
+#### Output Schema
+
+```
+Status: "success" | "error"
+Data: {
+  routing: {
+    primary_subskill: string  # e.g., "game-development/web-games"
+    secondary_subskills: Array<string>  # Additional relevant sub-skills
+    rationale: string
+  } | null
+  game_loop: {
+    pattern: string           # "INPUT → UPDATE → RENDER"
+    physics_rate_hz: number   # Fixed timestep rate (e.g., 50)
+    render_mode: string       # "interpolated"
+  } | null
+  perf_budget: {
+    frame_time_ms: number     # 16.67 for 60 FPS
+    input_ms: number          # Budget per system
+    physics_ms: number
+    ai_ms: number
+    logic_ms: number
+    render_ms: number
+    buffer_ms: number
+  } | null
+  pattern: {
+    name: string              # Selected pattern
+    use_case: string
+    alternatives: Array<string>
+  } | null
+  ai: {
+    type: string              # FSM | Behavior Tree | GOAP | Utility AI
+    complexity: string
+    rationale: string
+  } | null
+  collision: {
+    type: string              # AABB | Circle | Spatial Hash | Quadtree
+    rationale: string
+  } | null
+  reference_subskills: Array<string> | null
+  metadata: {
+    contract_version: string
+    backward_compatibility: string
+  }
+}
+Error: ErrorSchema | null
+```
+
+#### Error Schema
+
+```
+Code: string                  # From Error Taxonomy (Section 11)
+Message: string
+Request_Type: string
+Recoverable: boolean
+```
+
+#### Deterministic Guarantees
+
+- Routing is deterministic: platform → primary sub-skill; dimension → secondary sub-skill.
+- Performance budget is fixed per target FPS (16.67ms at 60 FPS, 33.33ms at 30 FPS).
+- Physics timestep is always fixed rate (50Hz default); render always interpolated.
+- Pattern selection defaults to State Machine; ECS only when entity_count = "high".
+- AI selection is monotonic with complexity: simple → FSM, medium → Behavior Tree, high → GOAP/Utility AI.
+- Collision type selection: rectangles → AABB, round → Circle, many same-size → Spatial Hash, large world → Quadtree.
+
+#### What Agents May Assume
+
+- Primary sub-skill path is valid and contains a SKILL.md.
+- Performance budget sums to exactly the frame time.
+- Game loop pattern is universal across all platforms.
+- Input abstraction applies to all sub-skills.
+
+#### What Agents Must NOT Assume
+
+- Sub-skills are automatically invoked (caller must read them).
+- Engine is installed or configured.
+- Performance budget applies to non-game workloads.
+- AI selection produces implementation code.
+
+#### Side-Effect Boundaries
+
+| Operation | Side Effects |
+|-----------|-------------|
+| Route | None; routing decision |
+| Game loop | None; pattern recommendation |
+| Pattern select | None; decision output |
+| Perf budget | None; budget allocation |
+| AI select | None; decision output |
+| Collision select | None; decision output |
+| Input guide | None; convention output |
+
+### 6.2 Workflow Contract
+
+#### Invocation Pattern
+
+```
+1. Define platform, dimension, and specialty requirements
+2. Invoke "route" to identify sub-skills
+3. Read primary sub-skill SKILL.md (caller's responsibility)
+4. Invoke "game-loop" for architecture pattern
+5. Invoke "perf-budget" for frame time allocation
+6. Invoke specialty queries (ai-select, collision-select) as needed
+7. Implement game (caller's responsibility)
+```
+
+#### Execution Guarantees
+
+- Each invocation produces a complete recommendation.
+- Routing always returns at least one primary sub-skill.
+- Performance budget always totals to target frame time.
+
+#### Failure Propagation Model
+
+| Failure Severity | Propagation | Workflow Action |
+|-----------------|-------------|-----------------|
+| Invalid platform | Return error to caller | Use supported platform |
+| Invalid dimension | Return error to caller | Use "2d" or "3d" |
+| Sub-skill not found | Return error to caller | Verify installation |
+| Unsupported FPS target | Return error to caller | Use 30, 60, or 120 |
+
+#### Retry Boundaries
+
+- Zero internal retries. Deterministic output.
+
+#### Isolation Model
+
+- Each invocation is stateless and independent.
+
+#### Idempotency Expectations
+
+| Operation | Idempotent | Notes |
+|-----------|-----------|-------|
+| Route | Yes | Same platform + dimension = same sub-skills |
+| Game loop | Yes | Fixed pattern |
+| Perf budget | Yes | Same FPS = same allocation |
+| Pattern select | Yes | Same entity_count = same pattern |
+| AI select | Yes | Same complexity = same type |
+| Collision select | Yes | Same context = same type |
+
+---
+
+## 7. Execution Model
+
+### 2-Phase Lifecycle
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| **Parse** | Validate platform, dimension, context | Validated input or error |
+| **Route/Evaluate** | Route to sub-skills or evaluate decision tree | Recommendation |
+
+All phases synchronous. No async pipeline. No sub-skill invocation.
+
+---
+
+## 8. Deterministic Design Principles
+
+| Principle | Enforcement |
+|-----------|-------------|
+| Fixed routing table | Platform → sub-skill mapping is fixed (10 sub-skills) |
+| Fixed frame budget | 60 FPS = 16.67ms; per-system allocation is fixed |
+| Fixed timestep | Physics at 50Hz; rendering interpolated; no variable delta |
+| State Machine default | Always start with State Machine; ECS only for 1000+ entities |
+| Input abstraction | Actions (jump, move), never raw keys (Space, W) |
+| Escalating AI | FSM → Behavior Tree → GOAP → Utility AI by complexity |
+| No external calls | All decisions use embedded rules |
+
+---
+
+## 9. State & Idempotency Model
+
+Stateless. Fully idempotent. No persistent state.
+
+The orchestrator routes but does not invoke. No pipeline state, no session tracking.
+
+---
+
+## 10. Failure Handling Strategy
+
+| Failure Class | Behavior | Caller Recovery |
+|---------------|----------|-----------------|
+| Unknown platform | Return `ERR_INVALID_PLATFORM` | Use web/mobile/pc/vr-ar |
+| Unknown dimension | Return `ERR_INVALID_DIMENSION` | Use 2d/3d |
+| Sub-skill missing | Return `ERR_SUBSKILL_NOT_FOUND` | Verify directory |
+| Unsupported FPS | Return `ERR_INVALID_FPS` | Use 30/60/120 |
+| Missing context | Return `ERR_MISSING_CONTEXT` | Supply required fields |
+
+**Invariant:** Every failure returns a structured error. No silent routing to default sub-skill.
+
+---
+
+## 11. Error Taxonomy
+
+| Code | Category | Recoverable | Description |
+|------|----------|-------------|-------------|
+| `ERR_INVALID_PLATFORM` | Validation | No | Platform not supported |
+| `ERR_INVALID_DIMENSION` | Validation | No | Dimension not 2d or 3d |
+| `ERR_INVALID_FPS` | Validation | No | FPS target not 30/60/120 |
+| `ERR_SUBSKILL_NOT_FOUND` | Infrastructure | No | Sub-skill directory missing |
+| `ERR_MISSING_CONTEXT` | Validation | Yes | Required context field missing |
+
+---
+
+## 12. Timeout & Retry Policy
+
+| Parameter | Default | Maximum | Rationale |
+|-----------|---------|---------|-----------|
+| Decision timeout | N/A | N/A | Synchronous; < 50ms |
+| Internal retries | Zero | Zero | Deterministic output |
+
+---
+
+## 13. Observability & Logging Schema
+
+### OpenTelemetry Observability (MANDATORY)
+
+- **Routing Telemetry**: EVERY time the Orchestrator makes a routing decision (platform + dimension → sub-skill), it MUST emit an OpenTelemetry Span recording `routing_latency` to track decision speed.
+- **Analytics Events**: The Orchestrator MUST trigger an OTel Event detailing the selected context (platform, dimension, specialty, target_fps) whenever a sub-skill is activated, to feed FAANG-grade usage analytics.
+
+### Log Entry Format
+
+```json
+{
+  "trace_id": "uuid",
+  "skill_name": "game-development",
+  "contract_version": "2.0.0",
+  "execution_id": "uuid",
+  "timestamp": "ISO-8601",
+  "request_type": "string",
+  "platform": "string",
+  "dimension": "string",
+  "primary_subskill": "string|null",
+  "secondary_subskills": "Array<string>|null",
+  "target_fps": "number",
+  "status": "success|error",
+  "error_code": "string|null",
+  "duration_ms": "number"
+}
+```
+
+### Required Log Points
+
+| Event | Log Level | Fields |
+|-------|-----------|--------|
+| Routing decision | INFO | platform, dimension, primary_subskill |
+| Multi-sub-skill route | INFO | all sub-skills listed |
+| Decision failed | ERROR | error_code, message |
+
+### Metrics
+
+| Metric | Type | Unit |
+|--------|------|------|
+| `gamedev.route.duration` | Histogram | ms |
+| `gamedev.platform.distribution` | Counter | per platform |
+| `gamedev.dimension.distribution` | Counter | per dimension |
+| `gamedev.subskill.selected` | Counter | per sub-skill |
+
+---
+
+## 14. Security & Trust Model
+
+### Data Handling
+
+- Game Development does not access game engines, APIs, or user data.
+- Platform and dimension inputs are treated as enum values.
+- No credential handling, no PII processing, no network access.
+
+---
+
+## 15. Scalability Model
+
+| Dimension | Constraint | Mitigation |
+|-----------|-----------|------------|
+| Throughput | CPU-bound routing | < 50ms; scales linearly |
+| Concurrency | Stateless invocations | Unlimited parallel |
+| Sub-skill count | 10 sub-skill directories | Static; grows only via skill additions |
+| Memory per invocation | < 1 MB | No accumulation |
+| Network | Zero network calls | No external dependency |
+
+---
+
+## 16. Concurrency Model
+
+Fully parallel. No shared state. No coordination required.
+
+---
+
+## 17. Resource Lifecycle Management
+
+All resources scoped to invocation. No persistent handles.
+
+Sub-skill SKILL.md files are read by the caller, not by this skill.
+
+---
+
+## 18. Performance Constraints
+
+| Operation | P50 Target | P99 Target | Hard Limit |
+|-----------|-----------|-----------|------------|
+| Routing decision | < 2 ms | < 5 ms | 20 ms |
+| Full guide | < 10 ms | < 30 ms | 50 ms |
+| Output size | ≤ 1,000 chars | ≤ 3,000 chars | 5,000 chars |
+
+---
+
+## 19. Operational Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Sub-skill directory missing | Low | Routing fails | `ERR_SUBSKILL_NOT_FOUND` with directory path |
+| Wrong platform selection | Medium | Wrong framework | Decision tree forces explicit choice |
+| ECS overuse | Medium | Over-engineering | State Machine default; ECS only for 1000+ entities |
+| Variable timestep | High | Non-deterministic physics | Fixed timestep mandated (50Hz) |
+| Frame budget exceeded | High | Frame drops | Per-system budget with buffer (1.67ms) |
+
+---
+
+## 20. Compliance with skill-design-guide.md
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| YAML frontmatter complete | ✅ | name, description, metadata with category, version, triggers, coordinates_with |
+| SKILL.md < 200 lines | ✅ | Entry point under 200 lines |
+| Prerequisites documented | ✅ | No external dependencies (routing skill) |
+| When to Use section | ✅ | Platform + dimension + specialty routing |
+| Core content matches skill type | ✅ | Orchestrator type: routing table, decision trees |
+| Troubleshooting section | ✅ | Anti-patterns table |
+| Related section | ✅ | Cross-links to /game, mobile-developer, perf-optimizer |
+| Content Map for multi-file | ✅ | Links to 10 sub-skill directories + engineering-spec.md |
+| Contract versioning | ✅ | contract_version, backward_compatibility, breaking_changes |
+| Compliance matrix structured | ✅ | This table with ✅/❌ + evidence |
+
+---
+
+## 21. Production Readiness Checklist
+
+| Category | Check | Status |
+|----------|-------|--------|
+| **Functionality** | 10 sub-skill routing (platform + dimension + specialty) | ✅ |
+| **Functionality** | Game loop (INPUT→UPDATE→RENDER, fixed timestep) | ✅ |
+| **Functionality** | Performance budget (16.67ms at 60 FPS, per-system) | ✅ |
+| **Functionality** | Pattern selection (6 patterns, State Machine default) | ✅ |
+| **Functionality** | AI selection (4 complexity levels) | ✅ |
+| **Functionality** | Collision strategy (4 types) | ✅ |
+| **Functionality** | Input abstraction (actions, not keys) | ✅ |
+| **Contracts** | Input/output/error schemas in pseudo-schema format | ✅ |
+| **Contracts** | Contract versioning with semver | ✅ |
+| **Failure** | Error taxonomy with 5 categorized codes | ✅ |
+| **Failure** | No silent routing on ambiguous input | ✅ |
+| **Failure** | Zero internal retries | ✅ |
+| **Determinism** | Fixed routing, fixed budgets, fixed timestep | ✅ |
+| **Security** | No engine access, no PII | ✅ |
+| **Observability** | Structured log schema with 5 mandatory fields | ✅ |
+| **Observability** | 4 metrics defined | ✅ |
+| **Performance** | P50/P99 targets for all operations | ✅ |
+| **Scalability** | Stateless; unlimited parallel | ✅ |
+| **Compliance** | All skill-design-guide.md sections mapped with evidence | ✅ |
+
+---
+
+## 🔗 Related
+
+| Item | Type | When to Read |
+|------|------|--------------|
+| [../SKILL.md](../SKILL.md) | Parent | Quick reference routing tables |
+| `game-development/2d-games` | Sub-skill | 2D sprite and tilemap systems |
+| `game-development/3d-games` | Sub-skill | 3D rendering and physics |
+| `game-development/web-games` | Sub-skill | Browser game frameworks |
+| `game-development/mobile-games` | Sub-skill | Mobile constraints |
+| `game-development/pc-games` | Sub-skill | Engine selection |
+| `game-development/vr-ar` | Sub-skill | VR/AR comfort and performance |
+| `game-development/game-design` | Sub-skill | GDD and balancing |
+| `game-development/multiplayer` | Sub-skill | Networking architecture |
+| `game-development/game-art` | Sub-skill | Visual style and pipeline |
+| `game-development/game-audio` | Sub-skill | Sound design and adaptive audio |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/game-development/vr-ar/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: vr-ar
+description: VR/AR development principles. Comfort, interaction, performance requirements.
+category: game-development-subskill
+triggers: ["VR", "AR", "XR", "virtual reality", "augmented reality"]
+coordinates_with: ["game-development", "3d-games", "perf-optimizer"]
+success_metrics: ["100% VR games maintain 90 FPS", "0 motion sickness in playtests"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# VR/AR Development
+
+> Immersive experience principles.
+
+---
+
+## 1. Platform Selection
+
+### VR Platforms
+
+| Platform | Use Case |
+|----------|----------|
+| **Quest** | Standalone, wireless |
+| **PCVR** | High fidelity |
+| **PSVR** | Console market |
+| **WebXR** | Browser-based |
+
+### AR Platforms
+
+| Platform | Use Case |
+|----------|----------|
+| **ARKit** | iOS devices |
+| **ARCore** | Android devices |
+| **WebXR** | Browser AR |
+| **HoloLens** | Enterprise |
+
+---
+
+## 2. Comfort Principles
+
+### Motion Sickness Prevention
+
+| Cause | Solution |
+|-------|----------|
+| **Locomotion** | Teleport, snap turn |
+| **Low FPS** | Maintain 90 FPS |
+| **Camera shake** | Avoid or minimize |
+| **Rapid acceleration** | Gradual movement |
+
+### Comfort Settings
+
+- Vignette during movement
+- Snap vs smooth turning
+- Seated vs standing modes
+- Height calibration
+
+---
+
+## 3. Performance Requirements
+
+### Target Metrics
+
+| Platform | FPS | Resolution |
+|----------|-----|------------|
+| Quest 2 | 72-90 | 1832x1920 |
+| Quest 3 | 90-120 | 2064x2208 |
+| PCVR | 90 | 2160x2160+ |
+| PSVR2 | 90-120 | 2000x2040 |
+
+### Frame Budget
+
+- VR requires consistent frame times
+- Single dropped frame = visible judder
+- 90 FPS = 11.11ms budget
+
+---
+
+## 4. Interaction Principles
+
+### Controller Interaction
+
+| Type | Use |
+|------|-----|
+| **Point + click** | UI, distant objects |
+| **Grab** | Manipulation |
+| **Gesture** | Magic, special actions |
+| **Physical** | Throwing, swinging |
+
+### Hand Tracking
+
+- More immersive but less precise
+- Good for: social, casual
+- Challenging for: action, precision
+
+---
+
+## 5. Spatial Design
+
+### World Scale
+
+- 1 unit = 1 meter (critical)
+- Objects must feel right size
+- Test with real measurements
+
+### Depth Cues
+
+| Cue | Importance |
+|-----|------------|
+| Stereo | Primary depth |
+| Motion parallax | Secondary |
+| Shadows | Grounding |
+| Occlusion | Layering |
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Move camera without player | Player controls camera |
+| Drop below 90 FPS | Maintain frame rate |
+| Use tiny UI text | Large, readable text |
+| Ignore arm length | Scale to player reach |
+
+---
+
+> **Remember:** Comfort is not optional. Sick players don't play.
+
+---
+
+## 🔗 Related
+
+| Item | Type | When to Read |
+|------|------|--------------|
+| [../SKILL.md](../SKILL.md) | Parent | Game loop and perf budget |
+| `game-development/3d-games` | Sibling | 3D rendering fundamentals |
+| `game-development/game-audio` | Sibling | 3D spatial audio for VR |
+| `perf-optimizer` | Skill | Frame time profiling |
+
+---
+
+⚡ PikaKit v3.9.134