Message Handling (V2)

"Messages delivered via named pipes – connect, process, exit, repeat."

When to Use This Skill

Use when:

• Connecting to the watchdog as a Ralph agent
• Sending messages to other agents
• Processing received messages
• Understanding message flow in V2 event-driven mode

Use proactively:

• At agent startup to establish connection
• When implementing message handlers
• When debugging communication issues

Quick Start

Example 2: Worker completes work

Developer sends → { type: "WorkComplete", to: "pm", payload: { taskId: "feat-001" } }
PM receives → Sets status: "awaiting_qa", forwards to QA

Example 3: QA validation result

QA sends → { type: "ValidationResult", to: "pm", payload: { passed: true } }
PM receives → Triggers retrospective phase

Agent Connection

Step 1: Source Runtime Library

. "$PSScriptRoot\..\..\scripts\agent-runtime.ps1"

Step 2: Connect to Watchdog

Connect-ToWatchdog -AgentName "developer" -SessionDir ".\.claude\session"

Step 3: Enter Message Loop

Enter-AgentLoop -MessageHandler {
    param($Message)

    switch ($Message.type) {
        "WorkAssign" {
            $taskId = $Message.payload.taskId
            # ... do work ...
        }
        "Query" {
            # Handle question
        }
        "System" {
            if ($Message.payload.systemEvent -eq "shutdown") {
                # Loop exits automatically
            }
        }
    }
}

Message Types Reference

PM Receives

Developer Receives

QA Receives

Sending Messages

Use functions from agent-runtime.ps1:

# Send work complete
Send-WorkComplete -TaskId "feat-001" -Result "success" -Notes "Complete"

# Send query
Send-Message -To "pm" -Type "Query" -Payload @{
    question = "Edge case handling?"
    context = @{ taskId = "feat-001" }
}

# Send problem report
Send-ProblemReport -TaskId "feat-001" -ProblemType "bug" -Severity "high"

Message Processing Priority

V2 Message Format

{
  "id": "msg-20250125-120000-001",
  "type": "WorkAssign",
  "from": "pm",
  "to": "developer",
  "timestamp": "2025-01-25T12:00:00Z",
  "payload": {
    "taskId": "feat-001",
    "workType": "implementation",
    "title": "Implement feature"
  },
  "inReplyTo": "msg-20250125-115500-042"
}

Troubleshooting

Connection Timeout

• Verify watchdog V2 is running
• Check .claude/session/ exists
• Ensure pipe name: ralph-{agent}-main

No Messages Received

• Verify PM is sending messages to your agent
• Check watchdog logs: .claude/session/logs/watchdog.log
• Verify pipe is connected

Unexpected Shutdown

• Check for unhandled exceptions in message handler
• Verify event log for crash details
• Supervisor will restart automatically

Anti-Patterns

❌ DON'T:

• Use file-based message queues
• Manually create/delete message files
• Poll for messages (loop handles this)
• Stay running after work is complete

✅ DO:

• Use agent-runtime.ps1 for connection
• Use Enter-AgentLoop for message processing
• Use Send-* functions to send messages
• Exit when work is complete

Related Skills