fcsouza/game-build

Game Build — Component Builder

Prerequisites

• Requires docs/mvp-first-draft.md in the project (run game-architect first)

---

Phase 0 — Context Load (silent, mandatory before writing a single line of code)

Execute in this exact order:

1. Check if docs/mvp-first-draft.md exists in the project
   • If it does NOT exist: output ⛔ Cannot proceed. Run the game-architect skill first to generate the MVP plan. game-build requires an existing plan to avoid architectural drift. and stop.
2. READ docs/mvp-first-draft.md (the MVP plan from game-architect)
   • Check Section 10 (Out of Scope / Deferred): if the component name from the user's message matches any deferred item, output ⚠️ [component] was explicitly deferred: "[reason]". Building now may increase scope. Continue? and wait for confirmation before proceeding.
3. IDENTIFY which skills are relevant to the component name from the user's message — apply only those skills from: game-backend-architecture, game-design-fundamentals, quest-narrative-coherence, postgres-game-schema, redis-game-patterns, bullmq-game-queues, betterauth-integration, stripe-game-payments, elevenlabs-sound-music, game-state-sync, matchmaking-system, gameplay-analytics
4. READ docs/build-registry.md if it exists (create it if not, using the template below)
5. READ docs/world-lore.md if component touches narrative/quests
6. READ docs/quest-registry.md if component touches quests

Special case: component name is "status" Read docs/build-registry.md and output a progress table showing built/mocked/remaining components. Do not build anything. Stop after outputting the status.

Build registry initial template (create at docs/build-registry.md if missing):

# Build Registry
> Managed by game-build skill — do not edit manually

## Summary
- Total components planned: [from MVP plan]
- Built: 0 | Mocked: 0 | Remaining: 0

## Components

<!-- entries added automatically by game-build -->

Phase 1 — Dependency Check

Before writing any code, resolve the component's dependency graph from the MVP plan:

For each dependency of the component:

• CHECK docs/build-registry.md for status
• If already built: import from its registered path — do not regenerate
• If NOT built: generate a typed mock/stub:
  • Same TypeScript interface as the real implementation will have
  • Returns realistic fake data matching the expected types
  • Clearly marked with: // MOCK — replace with real implementation via game-build [dependency-name]
  • Register in docs/build-registry.md as status: "mock"

List all mocks generated at the top of your output so the user knows what to build next.

Special case: component already in build-registry as "built" Warn the user: ⚠️ [component] is already marked as built in docs/build-registry.md. Do you want to refactor it instead? Stop and wait for confirmation before regenerating.

Phase 2 — Pre-Build Clarification (only if truly ambiguous)

Ask at most 2 questions if critical decisions cannot be inferred from the MVP plan. If the MVP plan has the answer, use it — do not ask.

Valid questions:

• "The MVP plan lists both REST and WebSocket for this component — which should this implementation use?"
• "[feature] was listed as out-of-scope in MVP Section 10 — confirm you want it now?"

Never ask about naming conventions, code style, or anything the skill files already define.

Phase 3 — Build the Component

Code Standards

• TypeScript strict mode — no any, no implicit types
• Production-ready — error handling, edge cases, input validation included
• Minimal — only what the MVP plan specifies for this component, nothing beyond
• No premature abstraction — optimize for clarity at MVP stage
• Cite the skill in inline comments for every major decision:

  // [→ bullmq-game-queues: retry with exponential backoff]
  const retryConfig = { attempts: 3, backoff: { type: 'exponential', delay: 1000 } }
  

File Output Structure

src/
  [component-name]/
    index.ts           ← main entry point / public API
    [component].ts     ← core logic
    [component].test.ts ← Vitest tests (required, no exceptions)
    types.ts           ← all TypeScript types/interfaces for this component
  __mocks__/
    [dependency].mock.ts  ← any mocks generated in Phase 1

Testing Standards (Vitest)

Every component ships with tests. No exceptions. Required coverage:

1. Happy path — core functionality works as expected
2. Edge cases — boundary conditions from the skill files
3. Failure path — what happens when dependencies throw or return bad data
4. Mock validation — confirm mocks match the interface they stand in for

No snapshot tests for game logic — assert on behavior, not structure.

Technology Integration

| If component involves... | Apply skill + patterns | |---|---| | DB reads/writes | postgres-game-schema — Drizzle typed queries, no raw SQL strings | | Cache / realtime | redis-game-patterns — correct data structure, key naming {entity}:{id}:{field} | | Background jobs | bullmq-game-queues — typed job payload, processor, retry config with attempts+backoff | | Auth / sessions | betterauth-integration — auth.api.getSession(), never trust client-sent user IDs | | Payments | stripe-game-payments — verify Stripe-Signature before processing, never fulfill on checkout redirect | | Audio / SFX | elevenlabs-sound-music — audio state machine, API call with fallback | | Quest / mission logic | quest-mission-design + quest-narrative-coherence — coherence check FIRST | | Client-server sync | game-state-sync — server-authoritative, delta encoding, rollback buffer | | Matchmaking | matchmaking-system — expanding bracket, BullMQ queue, atomic dequeue | | Analytics | gameplay-analytics — event emit pattern, sessionId not userId for funnels |

Phase 4 — Narrative Coherence Check (only if component touches story/quests)

Skip this phase entirely if the component has no narrative content.

If the component creates or modifies quests, characters, or lore:

1. READ docs/world-lore.md
2. READ docs/quest-registry.md
3. Verify:
   • No faction/character/location contradictions with existing lore
   • At least one existing world element referenced
   • New content will be registered in docs/quest-registry.md
4. If conflict detected: output ⚠️ LORE CONFLICT: [description] and propose resolution before writing the final implementation

Phase 5 — Update Build Registry

After every successful build, add/update the component entry in docs/build-registry.md:

## [component-name]
- **Status:** built
- **Path:** src/[component-name]/index.ts
- **Built at:** [ISO timestamp]
- **Depends on:** [list of real dependencies used]
- **Depended on by:** [leave empty — populated as other components reference this one]
- **Mocks generated:** [list any mocks this build created, or "none"]
- **Skills applied:** [list of skills that informed this build]
- **Open TODOs:** [anything flagged ⚠️ NOT IN PLAN or left incomplete]

Also update the Summary section counts.

Phase 6 — Output to User

Present in this order:

1. Build Summary

✅ Built: [component-name]
📁 Files created: [list with paths]
🧪 Tests: [X test cases written]
🔗 Dependencies: [real: X | mocked: Y]
⚠️  Mocks to replace (build these next): [list in dependency order]

2. The Code

Output each file in a clearly labeled fenced code block with the filename as the label. Full file — no truncation, no "// rest of file here" shortcuts.

3. How to Run It

# Commands to run and test this component right now
bun run dev
bun vitest run src/[component-name]/

4. What to Build Next

Based on the MVP plan build sequence (Section 9) and the mocks generated:

Recommended next:
  game-build [mock-dependency]   ← replaces mock created today
  game-build [next-in-sequence]  ← next item from MVP plan Section 9

---

Hard Constraints

1. Never regenerate a component marked built in docs/build-registry.md — warn the user and stop
2. Never invent schema, queue names, routes, or features not in the MVP plan — flag with ⚠️ NOT IN PLAN: and ask
3. Never skip tests — a component without tests is considered incomplete
4. Never remove mock markers — // MOCK — comments must stay until replaced with real implementations
5. Always cite the skill that informed each major decision in inline comments
6. Server-authoritative for any multiplayer component — client sends intentions, server validates and broadcasts