--- name: infrastructure-claude-code-game-workflow description: >- Use when starting a game project, choosing which skill to read, or navigating the game-dev skill ecosystem. Entry point for AI agents working on game development. Triggers: workflow, which skill, how to start, game project setup. --- # Claude Code Game Workflow ## Purpose How AI coding agents navigate this game development skill ecosystem — file conventions, which skills to read first, dependency order, and workflow patterns. ## When to Use Trigger: game dev workflow, skill navigation, which skill to use, game dev setup, project structure, skill dependencies, agent workflow, how to start, game dev ecosystem ## Prerequisites None — this is the entry point for the entire ecosystem. ## Core Principles 1. **Read skills before coding** — always check if a relevant skill exists before implementing from scratch 2. **Follow dependency order** — skills have prerequisites; reading them out of order misses critical context 3. **Coherence check is non-negotiable** — any narrative content requires `quest-narrative-coherence` first 4. **Genre-agnostic always** — never assume a specific game genre in shared code 5. **Schema first, logic second** — start with `postgres-game-schema` before writing game logic ## Feature Guides Dedicated files for each Claude Code feature. Read the relevant one when setting up a new project or adding a capability. | File | Feature | When to Use | |------|---------|-------------| | [custom-agents.md](custom-agents.md) | Custom Claude Code agents | Setting up game-engineer, narrative-writer, game-designer agents | | [worktrees.md](worktrees.md) | Git worktrees | Isolating a new game system or experimental change | | [mcp-setup.md](mcp-setup.md) | MCP servers (GitHub, Playwright, Context7) | Connecting external tools to Claude Code | | [plan-mode.md](plan-mode.md) | Plan mode | Before implementing any new game system | | [todo-patterns.md](todo-patterns.md) | TodoWrite task tracking | Multi-step feature implementation | | [vision-multimodal.md](vision-multimodal.md) | Screenshots + vision | Debugging UI, reviewing level design, game state | | [settings-full.md](settings-full.md) | Full `.claude/settings.json` | Permissions, hooks, and env vars for a game project | | [templates/game-agents/](templates/game-agents/) | Agent definition files | Copy to `.claude/agents/` in your project | | [templates/.mcp.json](templates/.mcp.json) | MCP config | Copy to project root as `.mcp.json` | | [templates/claude-hooks-config.json](templates/claude-hooks-config.json) | Hooks config | Copy hooks section into `.claude/settings.json` | | [templates/game-project-claude.md](templates/game-project-claude.md) | Project CLAUDE.md | Copy to game project root | ## Skill Dependency Graph ``` [claude-code-game-workflow] (YOU ARE HERE) | ┌───────────────┼───────────────┐ ▼ ▼ ▼ [postgres-game-schema] [game-design-fundamentals] [quest-narrative-coherence] | | | | ▼ ▼ ▼ ▼ [redis] [bullmq] [level-design] [worldbuilding] | | [game-economy] [story-structure] ▼ ▼ [ui-ux-game] [character-design] [game-backend-architecture] | [quest-mission-design] | | ▼ ▼ [game-state-sync] [stripe-game-payments] [betterauth] [elevenlabs-sound-music] ``` ## Workflow: Starting a New Game 1. Read `claude-code-game-workflow` (this skill) 2. Read `game-design-fundamentals` — define core loop, player motivation 3. Read `postgres-game-schema` — set up database 4. Read `game-backend-architecture` — set up Elysia server 5. Choose domain skills as needed (economy, quests, multiplayer, etc.) ## Workflow: Adding a Feature 1. Identify which skill covers the feature 2. Read that skill's SKILL.md 3. Check prerequisites — read those first if not already done 4. Copy boilerplate/ files as starting point 5. Customize using templates/ for configuration ## Workflow: Creating Narrative Content 1. **ALWAYS** read `quest-narrative-coherence` first 2. Read `worldbuilding` — load current world state 3. Read relevant narrative skill (story-structure, character-design, quest-mission) 4. Follow the 5-step coherence check 5. Register new content in quest-registry.md ## Skill Quick Reference | Need | Skill | Domain | |------|-------|--------| | Database schemas | `postgres-game-schema` | Engineering | | Job queues | `bullmq-game-queues` | Engineering | | Game server + WebSocket | `game-backend-architecture` | Engineering | | Caching + leaderboards | `redis-game-patterns` | Engineering | | Authentication | `betterauth-integration` | Engineering | | Payments / IAP | `stripe-game-payments` | Engineering | | Sound / Music | `elevenlabs-sound-music` | Engineering | | Netcode / State sync | `game-state-sync` | Engineering | | Core game design | `game-design-fundamentals` | Design | | Level / Area design | `level-design` | Design | | Quests / Missions | `quest-mission-design` | Design | | Economy / Currency | `game-economy-design` | Design | | UI / UX | `ui-ux-game` | Design | | World lore | `worldbuilding` | Narrative | | Story / Plot | `story-structure-game` | Narrative | | Characters / NPCs | `character-design-narrative` | Narrative | | Narrative consistency | `quest-narrative-coherence` | Narrative | | CI/CD | `ci-cd-game` | Infrastructure | | Monitoring | `monitoring-game-ops` | Infrastructure | | Cursor/Codex setup | `cursor-codex-integration` | Infrastructure | ## File Conventions - `SKILL.md` — knowledge document, read first - `boilerplate/` — copy as starting code - `templates/` — configuration and document templates - `ARCHITECTURE.md` — diagrams for infrastructure skills ## Claude Code Setup Quick setup for a new game project (4 steps): 1. **Copy CLAUDE.md template**: `templates/game-project-claude.md` → project root as `CLAUDE.md`. Fill in Core Loop, Genre, Platforms, Multiplayer. 2. **Copy hooks**: merge hooks from `templates/claude-hooks-config.json` into `.claude/settings.json`. See `settings-full.md` for the complete settings structure with permissions. 3. **Copy MCP config**: `templates/.mcp.json` → project root. Set `GITHUB_TOKEN` in shell env. 4. **Copy custom agents**: `templates/game-agents/` → `.claude/agents/` in your project. For detailed configuration of each Claude Code feature, see the **Feature Guides** table above. ### Skill @ Mentions In any prompt, reference skill files directly to inject their context: ``` @skills/game-dev/engineering/postgres-game-schema/SKILL.md — add inventory table @skills/game-dev/narrative/quest-narrative-coherence/SKILL.md — create merchant quest @skills/game-dev/engineering/matchmaking-system/SKILL.md — implement ELO queue ``` ## Hooks for Game Dev Copy the full hooks config from `templates/claude-hooks-config.json`. Four patterns: ### Hook 1 — Skill Routing (UserPromptSubmit) Detects keywords in the user's prompt and prints the relevant skill path before Claude responds. Runs on every prompt — zero false-negative cost. - **Event**: `UserPromptSubmit` - **What it does**: Scans prompt for domain keywords → prints the matching skill path as a hint - **Keywords mapped**: - `quest / character / NPC / story / lore / narrative` → `quest-narrative-coherence/SKILL.md` - `schema / database / inventory / drizzle / migration` → `postgres-game-schema/SKILL.md` - `matchmaking / lobby / ELO / rank / queue` → `matchmaking-system/SKILL.md` - `analytics / retention / funnel / D1 / D7 / cohort` → `gameplay-analytics/SKILL.md` - `redis / leaderboard / pubsub / cache / presence` → `redis-game-patterns/SKILL.md` - `state / sync / netcode / delta / rollback / prediction` → `game-state-sync/SKILL.md` - **When to use**: Always. Put in project `.claude/settings.json`. ```json { "hooks": { "UserPromptSubmit": [ { "matcher": "", "hooks": [ { "type": "command", "command": "PROMPT=$(echo \"$CLAUDE_HOOK_INPUT\" | jq -r '.prompt // \"\"'); for kw in quest character NPC story lore narrative; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Narrative skill: Read narrative/quest-narrative-coherence/SKILL.md first\" && break; done; for kw in schema database inventory drizzle migration; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/postgres-game-schema/SKILL.md\" && break; done; for kw in matchmaking lobby elo rank queue; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/matchmaking-system/SKILL.md\" && break; done; for kw in analytics retention funnel D1 D7 D30 cohort; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/gameplay-analytics/SKILL.md\" && break; done; for kw in redis leaderboard pubsub cache presence; do echo \"$PROMPT\" | grep -qi \"$kw\" && echo \"📚 Engineering skill: Read engineering/redis-game-patterns/SKILL.md\" && break; done; exit 0" } ] } ] } } ``` ### Hook 2 — Narrative Coherence Guard (PreToolUse: Write/Edit) Blocks careless writes to narrative files by injecting a reminder before Claude touches them. - **Event**: `PreToolUse` - **Matcher**: `Write|Edit` - **What it does**: Checks if the target file path matches `quest|character|story|narrative|lore|npc` — if yes, prints a reminder - **Behavior**: Exit code 0 (reminder only, not a hard block — Claude can still proceed) - **When to use**: Any project with narrative content ```json { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "FILE=$(echo \"$CLAUDE_HOOK_INPUT\" | jq -r '.tool_input.file_path // .tool_input.path // \"\"'); echo \"$FILE\" | grep -qiE '(quest|character|story|narrative|lore|npc)' && echo \"[game-dev] ⚠️ Narrative file: ensure quest-narrative-coherence check is complete.\"; exit 0" } ] } ``` ### Hook 3 — Biome Guard (PostToolUse: Write/Edit) Auto-formats TypeScript after every file write. Game projects accumulate debt fast when formatting is skipped. - **Event**: `PostToolUse` - **Matcher**: `Write|Edit` - **What it does**: If `biome.json` or `biome.jsonc` exists in the project root, runs `bunx biome check --write` on the written file - **When to use**: Any TypeScript game project ```json { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "cd \"$CLAUDE_PROJECT_DIR\" && [ -f biome.json ] || [ -f biome.jsonc ] && bunx biome check --write . 2>/dev/null || true" } ] } ``` ### Hook 4 — Quest Registry Reminder (Stop) After every session, reminds the developer to update the narrative registry files. - **Event**: `Stop` - **What it does**: Prints a reminder to update `quest-registry.md` and `world-lore.md` - **When to use**: Any project with narrative content - **Note**: Fires unconditionally — cheap and hard to miss ```json { "hooks": { "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "echo \"[game-dev] Session ended. If you created narrative content, update quest-registry.md and world-lore.md.\"" } ] } ] } } ``` ## Subagent Patterns Use parallel Claude Code agents when a feature spans multiple domains. Each agent reads its own skills, works in isolation, and produces a concrete output you merge at the end. ### Pattern 1 — Design + Engineering in Parallel When adding a major feature, split into two agents running simultaneously: - **Agent A** (Design): reads design skills → produces GDD section, economy balance, quest design - **Agent B** (Engineering): reads engineering skills → implements schema + backend routes They work on separate concerns with no shared state. Use `"worktree"` isolation to give each agent its own git branch. Merge when both complete. **Prompt:** ``` Use the Agent tool to run 2 parallel agents: - Agent 1: Read skills/game-dev/design/game-economy-design/SKILL.md and design the currency economy for our idle game. Output: economy-design.md - Agent 2: Read skills/game-dev/engineering/postgres-game-schema/SKILL.md and create the initial player schema. Output: modify db/schema.ts ``` ### Pattern 2 — Narrative Team For a narrative-heavy session with multiple interconnected characters and quests: - **Agent A**: reads `quest-narrative-coherence` + creates new quest (loads `world-lore.md`, checks consistency) - **Agent B**: reads `character-design-narrative` + creates NPCs for that quest Run in parallel. Then have the coherence agent review both outputs before merging to catch conflicts. **Prompt:** ``` Use the Agent tool to run 2 parallel agents: - Agent 1: Read narrative/quest-narrative-coherence/SKILL.md and narrative/worldbuilding/SKILL.md. Create a new merchant guild quest. Check world-lore.md for faction alignment. Output: quests/merchant-guild-q1.md - Agent 2: Read narrative/character-design-narrative/SKILL.md. Create 2 NPCs for a merchant guild quest — a quest giver and antagonist. Output: characters/merchant-npcs.md ``` ### Pattern 3 — Full-Stack Feature Breaking down "add matchmaking" into parallel workstreams: 1. **Design agent**: reads `matchmaking-system` + `game-economy-design` → produces matchmaking config doc 2. **Backend agent**: reads `matchmaking-system` + `bullmq-game-queues` → implements server-side queue logic 3. **DB agent**: reads `postgres-game-schema` + `redis-game-patterns` → creates tables + Redis key design All three run in parallel. One integration agent (sequential, after all three complete) assembles the final feature. **When not to parallelize**: When Agent B's output depends on Agent A's output. Keep those sequential. ## Memory Patterns What to persist across Claude Code sessions so agents never lose context. ### What to Save in MEMORY.md Write to `~/.claude/projects//memory/MEMORY.md` after making significant decisions: - **Architectural decisions**: "Chose Glicko-2 over ELO for matchmaking — handles new players better" - **Schema choices**: "Player attributes use JSONB for flexibility — indexed on `attributes->>'class'`" - **Economy parameters**: "Gem earn rate: 10/day soft cap. First-time bonus: 200 gems." - **World state summary**: "3 factions: Merchant Guild (neutral), Iron Brotherhood (hostile), Arcane Circle (allied). Merchants control trade routes." - **Active quest registry**: link to `quest-registry.md` ### Memory File Structure ``` ~/.claude/projects//memory/ MEMORY.md # key decisions — loaded every session automatically world-state.md # factions, geography, lore summary economy-state.md # current balance parameters schema-decisions.md # why each schema looks the way it does ``` Keep companion files (`world-state.md`, etc.) in the project repo under `docs/memory/` and symlink or reference them from `MEMORY.md` so they travel with the codebase. ### Rules for Memory - Write immediately after making a significant architectural or design decision - Never write temporary or session-specific context (e.g., "currently debugging X") - Review and update when a decision changes — stale memory is worse than no memory - Keep `MEMORY.md` under 150 lines (Claude truncates at ~200) - Use bullet points, not prose — agents scan memory, not read it ## Sources - This ecosystem's own architecture - Claude Code documentation: hooks, memory, subagents - "Overwatch Gameplay Architecture and Netcode" — inspiration for subagent parallelism in game systems