name: dev-coordination-message-formats description: JSON schemas for Ralph message system category: coordination

Message Formats

All messages use this standard format for the Ralph event-driven system.

Message Structure

{
  "id": "msg-{recipient}-{timestamp}-{seq}",
  "from": "sender",
  "to": "recipient",
  "type": "message_type",
  "priority": "normal|high|urgent",
  "payload": { },
  "timestamp": "2025-01-23T12:00:00.0000000Z",
  "status": "pending",
  "replyTo": null
}

Message ID Format

msg-{recipient}-{yyyyMMdd-HHmmss}-{sequence}

Examples:

• msg-developer-20250123-120000-001
• msg-qa-20250123-120005-001

Message Types

Task Messages

task_assign

PM → Developer: Assign a new task

{
  "type": "task_assign",
  "payload": {
    "taskId": "feat-001",
    "title": "Feature title",
    "description": "Description...",
    "acceptanceCriteria": [...],
    "worktree": "path/to/worktree"
  }
}

implementation_complete

Developer → QA: Implementation ready for validation

{
  "type": "implementation_complete",
  "payload": {
    "taskId": "feat-001",
    "summary": "Brief summary",
    "commitHash": "abc123",
    "branch": "developer-worktree",
    "filesModified": ["file1.ts", "file2.ts"]
  }
}

Validation Messages

validation_passed

QA → PM: Validation successful

{
  "type": "validation_passed",
  "payload": {
    "taskId": "feat-001",
    "results": {
      "typecheck": "pass",
      "lint": "pass",
      "test": "pass",
      "build": "pass"
    }
  }
}

bug_report

QA → Developer: Bugs found

{
  "type": "bug_report",
  "payload": {
    "taskId": "feat-001",
    "bugs": [
      { "file": "file.ts", "line": 10, "issue": "Bug description" }
    ]
  }
}

Coordination Messages

question

Any Agent → PM: Ask for clarification

{
  "type": "question",
  "payload": {
    "taskId": "feat-001",
    "question": "Question text..."
  }
}

answer

PM → Any Agent: Response to question

{
  "type": "answer",
  "payload": {
    "questionId": "...",
    "answer": "Answer text..."
  }
}

status_update

Any Agent → Watchdog: Status heartbeat

{
  "type": "status_update",
  "payload": {
    "agent": "developer",
    "status": "working|idle",
    "taskId": "feat-001"
  }
}

Priority Levels

• low - Background tasks
• normal - Standard work (default)
• high - Important work
• urgent - Critical issues/blocks

Message Locations

Messages are stored in inbox directories:

.claude/session/messages/
├── pm/           # PM's inbox
├── developer/    # Developer's inbox
├── qa/           # QA's inbox
└── watchdog/     # Watchdog's inbox (status updates)

Message Lifecycle

1. Created - Written to recipient's inbox
2. Delivered - Watchdog restarts recipient with message
3. Processed - Recipient handles message
4. Deleted - Removed from inbox after processing