Shared Messaging

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

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

Message Types Catalog

Core Types

PM Receives

Workers Receive

Watchdog Receives

Watchdog Sends

Priority Levels

Processing Order

1. URGENT - Handle immediately (e.g., agent_timeout)
2. HIGH - Respond promptly (e.g., question, bug_report)
3. NORMAL - Process in order (e.g., task_assign, task_complete)
4. 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

1. Priority First - Process urgent before normal
2. FIFO within Priority - Older messages before newer
3. Acknowledge Before Delete - Send message_acknowledged, then watchdog deletes
4. 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