From 5601e6de12d263bf49b6841d0e177b107940fc3f Mon Sep 17 00:00:00 2001 From: Ibrahim Elsahafy Date: Wed, 31 Dec 2025 21:06:29 +0400 Subject: [PATCH] feat(core): add inter-agent messenger for formal handoffs - Add messenger-config.yaml with message types and routing rules - Add send-message.xml and receive-message.xml tasks - Add messenger.md documentation with usage examples - Support handoff, review, clarify, escalate, notify, collaborate messages --- src/core/messenger/messenger-config.yaml | 162 +++++++++++++++++ src/core/messenger/messenger.md | 212 +++++++++++++++++++++++ src/core/messenger/receive-message.xml | 68 ++++++++ src/core/messenger/send-message.xml | 72 ++++++++ 4 files changed, 514 insertions(+) create mode 100644 src/core/messenger/messenger-config.yaml create mode 100644 src/core/messenger/messenger.md create mode 100644 src/core/messenger/receive-message.xml create mode 100644 src/core/messenger/send-message.xml diff --git a/src/core/messenger/messenger-config.yaml b/src/core/messenger/messenger-config.yaml new file mode 100644 index 00000000..3ed11ee0 --- /dev/null +++ b/src/core/messenger/messenger-config.yaml @@ -0,0 +1,162 @@ +# Inter-Agent Messenger Configuration +# Enables formal handoff protocols between agents + +name: inter-agent-messenger +version: "1.0.0" +description: "Formal handoff and communication protocols between BMAD agents" + +# Message queue location +queue_dir: "{project-root}/_bmad-output/messenger" +queue_file: "{queue_dir}/message-queue.yaml" +archive_dir: "{queue_dir}/archive" + +# Message types +message_types: + handoff: + description: "Transfer work from one agent to another" + required_fields: + - from_agent + - to_agent + - artifact_path + - context_summary + - next_actions + priority: high + + review: + description: "Request review of completed work" + required_fields: + - from_agent + - to_agent + - artifact_path + - review_type + priority: medium + + clarify: + description: "Request clarification on requirements or decisions" + required_fields: + - from_agent + - to_agent + - question + - context + priority: high + + escalate: + description: "Escalate issue to user attention" + required_fields: + - from_agent + - issue + - severity + - recommendation + priority: critical + + notify: + description: "Inform other agents of status or decisions" + required_fields: + - from_agent + - to_agents # Can be list or "all" + - message + priority: low + + collaborate: + description: "Request collaborative input from multiple agents" + required_fields: + - from_agent + - to_agents + - topic + - deadline + priority: medium + +# Standard routing rules +routing: + # Phase 1 → Phase 2 handoffs + analyst_to_pm: + trigger: "Product brief complete" + from: analyst + to: pm + payload: + - product_brief_path + - key_insights + - recommended_priorities + + pm_to_architect: + trigger: "PRD complete" + from: pm + to: architect + payload: + - prd_path + - priority_features + - technical_constraints + - timeline_expectations + + pm_to_ux: + trigger: "PRD complete with UI" + from: pm + to: ux-designer + payload: + - prd_path + - user_personas + - key_user_flows + + # Phase 2 → Phase 3 handoffs + architect_to_sm: + trigger: "Architecture approved" + from: architect + to: sm + payload: + - architecture_path + - tech_decisions + - component_boundaries + - api_contracts + + ux_to_sm: + trigger: "UX design complete" + from: ux-designer + to: sm + payload: + - ux_design_path + - component_library + - interaction_patterns + + # Phase 3 → Phase 4 handoffs + sm_to_dev: + trigger: "Story ready for dev" + from: sm + to: dev + payload: + - story_path + - acceptance_criteria + - technical_notes + - dependencies + + dev_to_tea: + trigger: "Implementation complete" + from: dev + to: tea + payload: + - story_path + - files_changed + - test_coverage + - review_request + + # Review flows + tea_to_dev: + trigger: "Review complete with issues" + from: tea + to: dev + payload: + - review_findings + - severity_breakdown + - required_actions + +# Priority levels +priorities: + critical: 1 + high: 2 + medium: 3 + low: 4 + +# Message retention +retention: + active_messages_max: 100 + archive_after_days: 7 + delete_archived_after_days: 30 diff --git a/src/core/messenger/messenger.md b/src/core/messenger/messenger.md new file mode 100644 index 00000000..a31ff3e5 --- /dev/null +++ b/src/core/messenger/messenger.md @@ -0,0 +1,212 @@ +# Inter-Agent Messenger System + +## Overview + +The Inter-Agent Messenger enables formal handoff protocols between BMAD agents. It provides structured communication for work transitions, review requests, clarifications, and escalations. + +## Architecture + +``` +┌─────────────┐ ┌─────────────────┐ ┌─────────────┐ +│ Agent A │───▶│ Message Queue │───▶│ Agent B │ +│ (sender) │ │ (YAML file) │ │ (receiver) │ +└─────────────┘ └─────────────────┘ └─────────────┘ + │ + ▼ + ┌─────────────┐ + │ Archive │ + └─────────────┘ +``` + +## Message Types + +### handoff +Transfer work from one agent to another with full context. + +**Example:** +```yaml +type: handoff +from: pm +to: architect +payload: + artifact_path: "_bmad-output/planning-artifacts/prd.md" + context_summary: "PRD complete for user auth feature" + next_actions: + - Review technical requirements + - Identify infrastructure needs + - Propose architecture patterns +``` + +### review +Request review of completed work. + +**Example:** +```yaml +type: review +from: dev +to: tea +payload: + artifact_path: "_bmad-output/implementation-artifacts/stories/1-2-user-login.md" + review_type: "code-review" + files_changed: + - src/auth/login.ts + - src/auth/login.test.ts +``` + +### clarify +Request clarification on requirements or decisions. + +**Example:** +```yaml +type: clarify +from: dev +to: architect +payload: + question: "Should authentication use JWT or session cookies?" + context: "Story 1-2 requires user login but auth method not specified in architecture" +``` + +### escalate +Escalate issue to user attention (critical). + +**Example:** +```yaml +type: escalate +from: dev +to: user +payload: + issue: "Blocking dependency conflict between React 18 and legacy charting library" + severity: "blocker" + recommendation: "Either upgrade charting library or downgrade to React 17" + impact: "Cannot proceed with Epic 2 until resolved" +``` + +### notify +Inform agents of status or decisions. + +**Example:** +```yaml +type: notify +from: architect +to_agents: all +payload: + message: "Architecture decision: Using PostgreSQL with Prisma ORM" + decision_doc: "_bmad-output/planning-artifacts/architecture.md#database" +``` + +### collaborate +Request collaborative input from multiple agents. + +**Example:** +```yaml +type: collaborate +from: pm +to_agents: + - architect + - ux-designer + - tea +payload: + topic: "Feature complexity assessment for real-time collaboration" + deadline: "2025-01-16T17:00:00Z" + context: "Client requesting WebSocket-based real-time editing" +``` + +## Standard Handoff Routes + +### Phase 1 → Phase 2 + +| From | To | Trigger | Payload | +|------|-----|---------|---------| +| analyst | pm | Product brief complete | brief_path, key_insights | +| pm | architect | PRD complete | prd_path, priority_features | +| pm | ux-designer | PRD with UI complete | prd_path, user_personas | + +### Phase 2 → Phase 3 + +| From | To | Trigger | Payload | +|------|-----|---------|---------| +| architect | sm | Architecture approved | architecture_path, tech_decisions | +| ux-designer | sm | UX design complete | ux_path, component_library | + +### Phase 3 → Phase 4 + +| From | To | Trigger | Payload | +|------|-----|---------|---------| +| sm | dev | Story ready | story_path, acceptance_criteria | +| dev | tea | Implementation complete | story_path, files_changed | +| tea | dev | Review with issues | review_findings, required_actions | + +## Priority Levels + +| Priority | Value | Use Case | +|----------|-------|----------| +| critical | 1 | Blockers, escalations | +| high | 2 | Handoffs, clarifications | +| medium | 3 | Reviews, collaborations | +| low | 4 | Notifications | + +## Usage + +### Sending a Message + +```xml + + handoff + pm + architect + + artifact_path: "_bmad-output/planning-artifacts/prd.md" + context_summary: "PRD complete, ready for architecture" + next_actions: + - Review technical requirements + - Design system architecture + + +``` + +### Receiving Messages + +```xml + + architect + handoff + +``` + +## Queue File Structure + +```yaml +# _bmad-output/messenger/message-queue.yaml +messages: + - message_id: "MSG-20250115-a1b2" + type: "handoff" + from: "pm" + to: "architect" + priority: "high" + created: "2025-01-15T10:30:00Z" + status: "pending" + payload: + artifact_path: "_bmad-output/planning-artifacts/prd.md" + context_summary: "PRD complete" + next_actions: + - Review requirements + - Design architecture + + - message_id: "MSG-20250115-c3d4" + type: "notify" + from: "architect" + to_agents: "all" + priority: "low" + created: "2025-01-15T11:00:00Z" + status: "read" + payload: + message: "Using PostgreSQL with Prisma" +``` + +## Best Practices + +1. **Always include context** - Don't assume receiving agent knows the background +2. **Use appropriate priority** - Reserve critical for true blockers +3. **Include artifact paths** - Reference documents, not content +4. **Specify next actions** - Clear handoff means faster pickup +5. **Check messages at workflow start** - Agents should check queue before beginning work diff --git a/src/core/messenger/receive-message.xml b/src/core/messenger/receive-message.xml new file mode 100644 index 00000000..0dc5373e --- /dev/null +++ b/src/core/messenger/receive-message.xml @@ -0,0 +1,68 @@ + + + Receive and process messages from the messenger queue + + + {project-root}/_bmad/core/messenger/messenger-config.yaml + {project-root}/_bmad-output/messenger/message-queue.yaml + {project-root}/_bmad-output/messenger/archive + + + + + + + + + + + Load queue from {queue_file} + Return: "No messages in queue" + + + + Filter messages where: + - to == {agent} OR + - to_agents contains {agent} OR + - to_agents == "all" + + Filter by status == "pending" + Filter by type == {type_filter} + Sort by priority (critical first), then by created (oldest first) + + + + Return: "No pending messages for {agent}" + For each message: + - Display message summary + - If mark_read == true, update status to "read" + + + + + Save updated queue to {queue_file} + + + + Return list of messages with full payloads + + Messages for {agent}: {count} + + {for each message} + --- + [{priority}] {type} from {from_agent} + ID: {message_id} + Received: {created} + + {payload_summary} + --- + {end for} + + + + + + + + + diff --git a/src/core/messenger/send-message.xml b/src/core/messenger/send-message.xml new file mode 100644 index 00000000..18b58d37 --- /dev/null +++ b/src/core/messenger/send-message.xml @@ -0,0 +1,72 @@ + + + Send a message between BMAD agents using the messenger system + + + {project-root}/_bmad/core/messenger/messenger-config.yaml + {project-root}/_bmad-output/messenger/message-queue.yaml + + + + + + + + + + + + + + Load messenger config from {config_source} + Validate type is one of: handoff, review, clarify, escalate, notify, collaborate + Check required_fields for message type are present in payload + HALT with validation error message + + + + Generate unique message_id: "MSG-{timestamp}-{random4}" + Build message object: + ```yaml + message_id: "{message_id}" + type: "{type}" + from: "{from_agent}" + to: "{to_agent}" or "{to_agents}" + priority: "{priority}" + created: "{timestamp}" + status: "pending" + payload: {payload} + ``` + + + + + Check if {queue_dir} exists + Create directory {queue_dir} + + + + Load existing queue from {queue_file} (or create empty if not exists) + Append new message to messages array + Sort messages by priority (critical first) + Save updated queue to {queue_file} + + + + Return message_id and status + + Message sent successfully. + ID: {message_id} + Type: {type} + From: {from_agent} + To: {to_agent} + Priority: {priority} + + + + + + + + +