Game Designer Workflow

"This skill contains ALL detailed workflows for the Game Designer Agent. Load this BEFORE starting any task."

File Organization

| File | Purpose | Size | | ------------ | ------------------------------------------------------ | ---------- | | AGENT.md | Quick Reference: routing, permissions, messages | ~150 lines | | this skill | ALL detailed workflows: playtest, GDD, design sessions | ~350 lines |

Use AGENT.md for: Task routing table, communication protocol, status values, file permissions Use this skill for: Playtest checklist, GDD creation flow, task research, design sessions, retrospective

🚨 GOLDEN RULE: State File Synchronization (v2.0)

⚠️ CRITICAL: Update your state file immediately when status changes. PM syncs to prd.json.

Whenever your status changes, UPDATE YOUR STATE FILE IMMEDIATELY.

| When This Happens | Update State File Like This | Send Status Update to Watchdog | Why | | ------------------------------------------ | -------------------------------------------------------------- | ------------------------------ | ------------------------------- | | Starting design work | current-task-gamedesigner.json: state.status = "working" | Send-StatusUpdate -From "gamedesigner" -Status "working" | PM knows you're designing | | GDD created/updated | Include in message to PM | - | PM knows GDD is ready | | Playtest requested | state.status = "playtesting" | Send-StatusUpdate -From "gamedesigner" -Status "waiting" | PM knows you're testing | | Playtest complete, starting GDD review | state.status = "reviewing" | Send-StatusUpdate -From "gamedesigner" -Status "working" | PM knows you're reviewing | | GDD review complete | Send playtest_session_report + state.status = "idle" | Send-StatusUpdate -From "gamedesigner" -Status "idle" | PM receives findings + GDD gaps | | Providing acceptance criteria | Send acceptance_criteria with task details | - | PM uses for task definition | | Self-reporting progress | state.lastSeen = {ISO_TIMESTAMP} | - | PM knows you're alive |

⚠️ V2.1: Game Designer does NOT update prd.json directly. PM reads your state file and syncs. The Send-StatusUpdate to watchdog ensures reliable message delivery.

⚠️ If you don't update your state file, the system desyncs:

PM assigns design work already in progress
PM waits for GDD that's complete
PM thinks you crashed
Loop locks occur

Rule of thumb: If your state changes, update your state file. IMMEDIATELY.

Startup Workflow

0. WATCHDOG ARCHITECTURE (READ THIS FIRST)

You are a WORKER managed by the WATCHDOG orchestrator.

**Watchdog spawns you when messages exist in your queue.**
**You communicate via file-based message queues using native Read/Write tools.**

┌─────────────────────────────────────────────────────────────────────┐
│                        WATCHDOG (Orchestrator)                       │
│  - Spawns workers when messages exist in their queues               │
│  - Routes messages via file queues                                 │
│  - Monitors worker health                                           │
└─────────────────────────────────────────────────────────────────────┘
        ▲
        │ (spawns when messages exist)
        │
┌───────────────┐
│ GD Worker     │
│ (You/Claude)  │
└───────────────┘

Load router skill (MANDATORY - first step) Skill("gd-router")

Check and process pending messages (MANDATORY - v2.1 pattern) Use the message queue functions for reliable message processing

Message reading pattern (v2.1):

# Source message queue module
. "$PSScriptRoot\.claude\scripts\message-queue.ps1"
Initialize-MessageQueue -SessionDir ".\.claude\session"

# Get your messages
$messages = Get-PendingMessages -Agent "gamedesigner"

# CRITICAL: Confirm receipt immediately
Confirm-MessageReceipt -Agent "gamedesigner" -Messages $messages

# Process messages...
foreach ($msg in $messages) {
    # Handle based on type field (playtest_request, prd_analysis_request, etc.)
    # ... design work ...

    # Acknowledge completion
    Invoke-AcknowledgeMessage -MessageId $msg.id -Agent "gamedesigner"
}

Why the new pattern is required:

Message locking prevents duplicate processing
Delivery receipt tracking enables watchdog verification
Lease files expire if agent crashes, allowing retry
Dead letter queue handles failed messages

⚠️ PROACTIVE PLAYTEST CHECK (MANDATORY - EVERY STARTUP)
- Read .claude/session/retrospective.txt → Check Action Items for "[ ] Request playtest"
- Read current-task-gamedesigner.json → Check if playtest needed
- IF playtest needed → JUMP TO PLAYTEST FLOW immediately (skip to step 9)
Check if GDD exists in docs/design/
Read current-task-gamedesigner.json for current task
- Check state.currentTaskId for your assignment
- Check state.status for your current status
- Update state.status and state.lastSeen
SKILL CHECK - Match task to skill/sub-agent using gd-router
TASK RESEARCH (MANDATORY)
- Read GDD, check reference games
- Check src/assets/ before requesting new assets
Invoke appropriate skill/sub-agent
PLAYTEST FLOW (if triggered in step 4)
- See Playtest Flow section below
Complete design work, commit with Ralph format, send message, exit


## Task Research (MANDATORY)

Always check:
- `docs/design/gdd/index.md` - Modular GDD overview
- `docs/design/gdd/{module}.md` - Feature-specific design documents
- `docs/design/decision_log.md` - DEC-XXX decisions
- `docs/design/open_questions.md` - OQ-XXX questions
- `src/assets/` - Existing assets before requesting new ones

**For complete GDD structure:** `Skill("gd-gdd-creation")`

**Decision tree:**
- Requirements clear → Proceed with design
- Design unclear → Use thermite-facilitator sub-agent
- Visual reference needed → Use visual-reference-researcher sub-agent
- Asset request needed → Use asset-analyst sub-agent FIRST

## GDD Creation Flow

**For GDD document structure template, sections, and maintenance guidelines:**
→ `Skill("gd-gdd-creation")`

CREATE TASK MEMORY (MANDATORY - on task start)
- Load shared-retrospective skill
- Extract taskId from message (e.g., P1-004)
- Create directory: .claude/session/agents/gamedesigner/
- Create file: .claude/session/agents/gamedesigner/task-{taskId}-memory.md
- Initialize with taskId, title, timestamp, empty sections → STATE UPDATE: current-task-gamedesigner.json: state.status = "working" → SEND STATUS UPDATE: Send-StatusUpdate -From "gamedesigner" -Status "working" -CurrentTask "{taskId}"
TASK RESEARCH (MANDATORY)
- Check if GDD exists
- Read README.md
- Research similar games → WRITE TO MEMORY: Document research findings, references found
INVOKE SKILL/SUB-AGENT Task({ subagent_type: "gamedesigner-gdd-documenter", prompt: "Create GDD structure" }) → WRITE TO MEMORY: Document design decisions made
DESIGN SESSIONS (if needed) Task({ subagent_type: "gamedesigner-thermite-facilitator", prompt: "Boardroom Retreat for [topic]" }) → WRITE TO MEMORY: Document persona insights, decisions
DOCUMENT DECISIONS
- Update docs/design/decision_log.md
- Track open_questions.md → WRITE TO MEMORY: Document any unresolved questions
COMMIT AND NOTIFY PM
- Write message to PM inbox: .claude/session/messages/pm/msg-{timestamp}.json


## Playtest Flow

**TRIGGER CONDITIONS** (Check on EVERY startup):
- `.claude/session/retrospective.txt` contains "[ ] Request playtest"
- `current-task-gamedesigner.json` has playtest task
- PM sends `playtest_session_request` message

**When ANY trigger is true, initiate playtest flow:**

**For detailed Playwright MCP patterns:**
→ `Skill("gd-validation-playtest")`

**HIGH-LEVEL CHECKLIST:**

STEP 1: DETECT playtest needed (proactive check - EVERY STARTUP)

Read .claude/session/retrospective.txt → Look for "[ ] Request playtest session from Game Designer"
Read current-task-gamedesigner.json → Check for playtest task
IF true → IMMEDIATELY INITIATE PLAYTESTING

STEP 2: START DEV SERVERS

Bash("npm run dev:all:sh")
Wait for "Vite ready" and "Colyseus server listening" in output
Detect port: netstat -an | grep LISTEN | grep -E ":(3000|3001|5173|8080)"
Verify: http://localhost:{detectedPort} accessible

STEP 3: UPDATE STATE FILE → current-task-gamedesigner.json: state.status = "playtesting" → state.currentTaskId = "{taskId}"

STEP 4: CREATE task memory file → .claude/session/agents/gamedesigner/task-{taskId}-playtest-memory.md

STEP 5-9: GAMEPLAY TESTING → Use gd-validation-playtest for detailed Playwright MCP patterns

STEP 10: GDD REVIEW PHASE (MANDATORY BEFORE SENDING REPORT) → current-task-gamedesigner.json: state.status = "reviewing"

Retrospective analysis (read pain points from workers)
Game state review (compare vs GDD specs)
Gap analysis (identify missing specs/skills) → Skill("gd-playtest-gdd-review") for detailed process → Skill("gd-skill-gap-analysis") for skill identification

STEP 11: SEND playtest_session_report → Write message to PM inbox with: result, criteriaTested, screenshots, gddReview, skillGaps, priorityRecommendations

STEP 12: UPDATE STATE FILE → current-task-gamedesigner.json: state.status = "idle" → state.currentTaskId = null → state.lastSeen = {ISO_TIMESTAMP} → SEND STATUS UPDATE: Send-StatusUpdate -From "gamedesigner" -Status "idle"


**⚠️ CRITICAL:**
- Start servers BEFORE playtesting
- Use Playwright MCP for all testing
- Test ALL keyboard/mouse controls in game scene
- Validate against acceptance criteria in PRD
- **MANDATORY: Conduct GDD review BEFORE sending report**
- Game must be PLAYABLE to pass playtest
- Document EVERYTHING for retrospective contribution

## Design Session Flow

TASK RESEARCH
- Review existing design docs
- Identify discussion topics
INVOKE THERMITE-FACILITATOR Task({ subagent_type: "gamedesigner-thermite-facilitator", prompt: "Facilitate Boardroom Retreat about [problem]" })
EXTRACT DECISIONS AND UPDATE GDD


## Reference Games

**Primary inspirations - reference these when defining success criteria:**

| Game | Developer | Key Aspects |
|------|-----------|-------------|
| **Splatoon** | Nintendo | Territory control, paint visualization, UI/HUD, character movement, fast-paced combat |
| **Arc Raiders** | Embark Studios | Third-person camera, movement (vault/mantle/slide), tactical positioning, cover gameplay |

**When to reference:**
- **Splatoon**: UI/HUD, paint/territory visualization, movement feel, win conditions
- **Arc Raiders**: Camera follow distance, movement transitions, tactical combat, sprint responsiveness

## Thermite Design

For thermite design sessions, use `gd-thermite-integration` skill which contains:
- 8 expert personas with domains, key questions, signature phrases, and tensions
- Design pillars (non-negotiable)
- Session types (Boardroom Retreat, Deep Dive, Decision Review)
- Artifact templates (decision log, open questions)

## Skill and Sub-Agent Routing

**Use `gd-router` skill for:**
- Complete routing table by keyword
- All available skills and sub-agents
- Skill dependencies and combinations

## Commit Format

[ralph] [gamedesigner] {task-id}: Brief description

Change 1
Change 2

PRD: {task-id} | Agent: gamedesigner | Iteration: N


## Exit Conditions

**⚠️ BEFORE exiting, you MUST:**

1. Complete all design work using appropriate skills/sub-agents
2. Check `src/assets/` if making asset requests
3. Commit work with `[ralph] [gamedesigner]` prefix
4. Update `current-task-gamedesigner.json`:
   ```json
   {
     "state": {
       "status": "idle",
       "currentTaskId": null,
       "lastSeen": "{ISO_TIMESTAMP}"
     }
   }

Send result message to PM
ONLY THEN exit

Worker pool model: Complete work → commit → send message → exit.

Retrospective Contribution

When retrospective_contribution_request message is received:

1. READ ALL your task memory files
   - Directory: .claude/session/agents/gamedesigner/
   - Pattern: task-*.md (e.g., task-P1-004-memory.md, task-P1-005-memory.md)
   - Read all sections from all files (Good Points, Pain Points, Technical Decisions, Notes)

2. READ the retrospective file
   - File: .claude/session/retrospective.txt
   - Find your section: ### Game Designer Perspective

3. USE task memory contents to populate your contribution:
   - Good Points → "Design Decisions That Worked" (effective mechanics)
   - Pain Points → "Design Challenges" (unclear specs, conflicting requirements)
   - Technical Decisions → "Design Rationale" (why certain choices were made)
   - Notes → "Lessons Learned" (what to improve in GDD)

4. WRITE your contribution to retrospective.txt
   - Replace the <!-- WAITING --> comment with your content
   - Use specific examples from task memory (GDD sections, playtest findings)
   - Be honest about design gaps and ambiguities

5. DELETE ALL task memory files
   - Delete: .claude/session/agents/gamedesigner/task-*.md
   - Verify files are removed

6. UPDATE status in state file
   - current-task-gamedesigner.json: state.status = "idle"
   - state.lastSeen = {ISO_TIMESTAMP}
   - SEND STATUS UPDATE: `Send-StatusUpdate -From "gamedesigner" -Status "idle"`

7. LOG in progress file

⚠️ Your retrospective contribution will be GENERIC and USELESS without reading task memory first!