Shared Messaging

"Agents communicate via file-based message queues using Glob, Read, and Write tools."

Message Queue Directory

.claude/session/messages/
├── pm/                 # PM's inbox
├── developer/          # Developer's inbox
├── qa/                 # QA's inbox
├── techartist/         # Tech Artist's inbox
├── gamedesigner/       # Game Designer's inbox
└── watchdog/           # Watchdog's inbox (acknowledgments)

Pattern: .claude/session/messages/{recipient}/msg-{recipient}-{timestamp}-{seq}.json

Message Format (Single Definition)

{
  "id": "msg-developer-20260126-120000-001",
  "from": "pm",
  "to": "developer",
  "type": "task_assign",
  "priority": "normal",
  "payload": {
    "taskId": "feat-001",
    "title": "Feature title",
    "acceptanceCriteria": ["Criterion 1", "Criterion 2"]
  },
  "timestamp": "2026-01-26T12:00:00.000Z",
  "status": "pending"
}

Fields

| Field | Type | Description | | ----------- | ------ | -------------------------------------------------------------------------------- | | id | string | msg-{recipient}-{YYYYMMDD-HHMMSS}-{seq} | | from | string | Sender agent (pm, developer, qa, techartist, gamedesigner, watchdog) | | to | string | Recipient agent | | type | string | Message type (see catalog below) | | priority | string | low, normal, high, urgent | | payload | object | Type-specific data | | timestamp | string | ISO 8601 UTC format | | status | string | pending, processing, completed |

Reading Messages

Use Glob + Read tools:

1. Glob: .claude/session/messages/{your-agent}/msg-*.json
2. For each file: Read the content
3. Parse JSON and extract fields
4. Process based on message type
5. Send acknowledgment to watchdog
6. Delete the file

Complete Example

# Step 1: Find messages
Glob: .claude/session/messages/pm/msg-*.json

# Step 2: Read each file
Read: .claude/session/messages/pm/msg-pm-20260126-120000-001.json

# Step 3: Parse and process
{
  "id": "msg-pm-001",
  "from": "developer",
  "to": "pm",
  "type": "task_complete",
  "payload": { "taskId": "feat-001", "success": true },
  "timestamp": "2026-01-26T12:00:00.000Z"
}

# Step 4: Process by type
# task_complete → Trigger retrospective
# bug_report → Reassign to worker
# question → Research and respond

# Step 5: Send acknowledgment (see below)

# Step 6: Delete the file

Message Acknowledgment

CRITICAL: Immediately after reading messages, confirm receipt to watchdog:

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

# Get your messages
$messages = Get-PendingMessages -Agent "{your-agent}"

# CRITICAL: Confirm receipt immediately after reading
Confirm-MessageReceipt -Agent "{your-agent}" -Messages $messages

# Now process messages...
foreach ($msg in $messages) {
    # ... process message ...
    Invoke-AcknowledgeMessage -MessageId $msg.id -Agent "{your-agent}"
}

Why Receipt Confirmation is Required

Prevents duplicates: Message locking ensures only one agent processes each message
Delivery tracking: Watchdog tracks which messages were successfully received
Crash recovery: Lease files expire if agent crashes, allowing retry
Dead letter queue: Failed messages are automatically retried with exponential backoff

Sending Messages

Use Write tool to create message file in recipient's queue:

Task Assignment (PM → Worker)

{
  "id": "msg-developer-20260126-120000-001",
  "from": "pm",
  "to": "developer",
  "type": "task_assign",
  "priority": "normal",
  "payload": {
    "taskId": "feat-001",
    "title": "Feature title",
    "acceptanceCriteria": ["Criterion 1", "Criterion 2"]
  },
  "timestamp": "2026-01-26T12:00:00.000Z",
  "status": "pending"
}

Task Completion (Worker → PM)

{
  "id": "msg-pm-20260126-120200-001",
  "from": "developer",
  "to": "pm",
  "type": "task_complete",
  "priority": "normal",
  "payload": {
    "taskId": "feat-001",
    "success": true,
    "summary": "Implementation complete"
  },
  "timestamp": "2026-01-26T12:02:00.000Z",
  "status": "pending"
}

Question (Any → PM)

{
  "id": "msg-pm-20260126-120100-001",
  "from": "developer",
  "to": "pm",
  "type": "question",
  "priority": "high",
  "payload": {
    "question": "How should I handle X?",
    "context": "Current situation..."
  },
  "timestamp": "2026-01-26T12:01:00.000Z",
  "status": "pending"
}

Bug Report (QA → PM)

{
  "id": "msg-pm-20260126-120300-001",
  "from": "qa",
  "to": "pm",
  "type": "bug_report",
  "priority": "high",
  "payload": {
    "taskId": "feat-001",
    "bugs": [{ "file": "src/App.tsx", "line": 42, "issue": "Type error" }]
  },
  "timestamp": "2026-01-26T12:03:00.000Z",
  "status": "pending"
}

Heartbeat Protocol

"Your heartbeat proves you're alive - update it or PM thinks you're dead."

For Worker Agents (Developer, QA, Tech Artist, Game Designer)

DO NOT read prd.json - Update your state file instead.

Step 1: Read your state file

Read: .claude/session/current-task-{your-agent}.json

Step 2: Update the state object

{
  "state": {
    "status": "working",
    "lastSeen": "2026-01-27T12:00:00.000Z",
    "currentTaskId": "feat-001",
    "pid": 0
  }
}

Step 3: Write updated state

Write: .claude/session/current-task-{your-agent}.json

When to Update

| Situation | Set state.status to | Update state.lastSeen | | ---------------------- | --------------------- | ----------------------- | | Start working on task | "working" | ✅ Yes, to NOW | | Finish a task | "idle" | ✅ Yes, to NOW | | Blocked/waiting for PM | "awaiting_pm" | ✅ Yes, to NOW | | Idle/monitoring | "idle" | No |

Message Types Catalog

Core Types

| Type | Direction | Purpose | | -------------------- | ----------- | --------------------- | | task_assign | PM → Worker | Assign a task | | task_complete | Worker → PM | Report completion | | validation_request | PM → QA | Request validation | | bug_report | QA → PM | Report bugs | | question | Any → PM | Ask for clarification | | answer | PM → Worker | Respond to question | | wake_up | PM → Worker | Wake idle worker |

PM Receives

| Type | From | Action | | ---------------------------- | ------------ | -------------------------------- | | task_complete | qa/developer | Trigger retrospective if success | | bug_report | qa | Reassign to developer | | question | any | Research and respond | | retrospective_contribution | any | Collect for synthesis | | playtest_report | gamedesigner | Review findings |

Workers Receive

| Type | From | Action | | ------------------------ | ---- | --------------------------- | | task_assign | pm | Read task, begin work | | bug_report | qa | Fix bugs, re-submit | | answer | pm | Apply response, continue | | validation_request | pm | Run validation | | wake_up | pm | Resume if idle | | retrospective_initiate | pm | Contribute to retrospective |

Watchdog Receives

| Type | From | Action | | ---------------------- | ---- | ------------------------------- | | message_acknowledged | any | Mark message processed, delete | | status_update | any | Update agent status in prd.json |

Watchdog Sends

| Type | To | Purpose | | ------------------------ | --- | --------------------------------- | | retrospective_complete | pm | All workers contributed | | agent_timeout | pm | Agent timed out awaiting response |

Priority Levels

| Priority | Use Case | | -------- | --------------------------------- | | urgent | Critical failures, agent timeouts | | high | Questions, bug reports | | normal | Task assignments, completions | | low | Status updates, heartbeats |

Processing Order

URGENT - Handle immediately (e.g., agent_timeout)
HIGH - Respond promptly (e.g., question, bug_report)
NORMAL - Process in order (e.g., task_assign, task_complete)
LOW - Log and continue (e.g., wake_up, status updates)

Message Flow Patterns

Task Completion Flow

PM → task_assign → Developer
Developer → task_complete → PM
PM → validation_request → QA
QA → task_complete (pass) OR bug_report (fail) → PM

Question/Answer Flow

Worker → question → PM
PM → answer → Worker

Retrospective Flow

PM → retrospective_initiate → Workers
Workers → retrospective_contribution → PM
Watchdog (tracks all contributions) → retrospective_complete → PM

Processing Rules

Priority First - Process urgent before normal
FIFO within Priority - Older messages before newer
Acknowledge Before Delete - Send message_acknowledged, then watchdog deletes
Idempotent Handlers - Safe to reprocess (check status before acting)

No Messages Found

Glob returns empty → No messages waiting
Continue normal workflow or exit (watchdog will spawn you when messages arrive)

Message Cleanup

Delete the messages after acknowledge them
Don't leave processed messages (prevents re-processing)

Anti-Patterns

| Don't | Do Instead | | ----------------------------- | ------------------------------ | | Use PowerShell helper scripts | Use Glob/Read/Write tools | | Modify other agents' messages | Only write to recipient queues | | Forget acknowledgment | Always send to watchdog | | Delete without acknowledging | Acknowledge first, then delete |