Gamedesigner Workflow

Game Designer Workflow

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

File Organization

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.

⚠️ 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)  │
└───────────────┘

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

2. 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

3. ⚠️ 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)

4. Check if GDD exists in docs/design/

5. 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

6. SKILL CHECK - Match task to skill/sub-agent using gd-router

7. TASK RESEARCH (MANDATORY)

   • Read GDD, check reference games
   • Check src/assets/ before requesting new assets

8. Invoke appropriate skill/sub-agent

9. PLAYTEST FLOW (if triggered in step 4)

   • See Playtest Flow section below

10. 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")`

1. 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}"

2. TASK RESEARCH (MANDATORY)

   • Check if GDD exists
   • Read README.md
   • Research similar games → WRITE TO MEMORY: Document research findings, references found

3. INVOKE SKILL/SUB-AGENT Task({ subagent_type: "gamedesigner-gdd-documenter", prompt: "Create GDD structure" }) → WRITE TO MEMORY: Document design decisions made

4. DESIGN SESSIONS (if needed) Task({ subagent_type: "gamedesigner-thermite-facilitator", prompt: "Boardroom Retreat for [topic]" }) → WRITE TO MEMORY: Document persona insights, decisions

5. DOCUMENT DECISIONS

   • Update docs/design/decision_log.md
   • Track open_questions.md → WRITE TO MEMORY: Document any unresolved questions

6. 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

1. TASK RESEARCH

   • Review existing design docs
   • Identify discussion topics

2. INVOKE THERMITE-FACILITATOR Task({ subagent_type: "gamedesigner-thermite-facilitator", prompt: "Facilitate Boardroom Retreat about [problem]" })

3. 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}"
     }
   }

5. Send result message to PM
6. 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!