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
This commit is contained in:
Ibrahim Elsahafy
parent
28b4e7a8ee
commit
5601e6de12
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
<exec task="send-message">
|
||||||
|
<param name="type">handoff</param>
|
||||||
|
<param name="from_agent">pm</param>
|
||||||
|
<param name="to_agent">architect</param>
|
||||||
|
<param name="payload">
|
||||||
|
artifact_path: "_bmad-output/planning-artifacts/prd.md"
|
||||||
|
context_summary: "PRD complete, ready for architecture"
|
||||||
|
next_actions:
|
||||||
|
- Review technical requirements
|
||||||
|
- Design system architecture
|
||||||
|
</param>
|
||||||
|
</exec>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Receiving Messages
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<exec task="receive-message">
|
||||||
|
<param name="agent">architect</param>
|
||||||
|
<param name="type_filter">handoff</param>
|
||||||
|
</exec>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
@ -0,0 +1,68 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<task id="receive-message" name="Receive Inter-Agent Message" standalone="false">
|
||||||
|
<description>Receive and process messages from the messenger queue</description>
|
||||||
|
|
||||||
|
<config>
|
||||||
|
<source>{project-root}/_bmad/core/messenger/messenger-config.yaml</source>
|
||||||
|
<queue_file>{project-root}/_bmad-output/messenger/message-queue.yaml</queue_file>
|
||||||
|
<archive_dir>{project-root}/_bmad-output/messenger/archive</archive_dir>
|
||||||
|
</config>
|
||||||
|
|
||||||
|
<parameters>
|
||||||
|
<param name="agent" required="true" description="Agent checking for messages"/>
|
||||||
|
<param name="type_filter" required="false" description="Filter by message type"/>
|
||||||
|
<param name="mark_read" required="false" default="true" description="Mark messages as read"/>
|
||||||
|
</parameters>
|
||||||
|
|
||||||
|
<execution>
|
||||||
|
<step n="1" goal="Load message queue">
|
||||||
|
<action>Load queue from {queue_file}</action>
|
||||||
|
<action if="queue not exists or empty">Return: "No messages in queue"</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2" goal="Filter messages for agent">
|
||||||
|
<action>Filter messages where:
|
||||||
|
- to == {agent} OR
|
||||||
|
- to_agents contains {agent} OR
|
||||||
|
- to_agents == "all"
|
||||||
|
</action>
|
||||||
|
<action>Filter by status == "pending"</action>
|
||||||
|
<action if="type_filter specified">Filter by type == {type_filter}</action>
|
||||||
|
<action>Sort by priority (critical first), then by created (oldest first)</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="3" goal="Process messages">
|
||||||
|
<action if="no matching messages">Return: "No pending messages for {agent}"</action>
|
||||||
|
<action>For each message:
|
||||||
|
- Display message summary
|
||||||
|
- If mark_read == true, update status to "read"
|
||||||
|
</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="4" goal="Update queue">
|
||||||
|
<action if="mark_read == true">Save updated queue to {queue_file}</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="5" goal="Return messages">
|
||||||
|
<action>Return list of messages with full payloads</action>
|
||||||
|
<output>
|
||||||
|
Messages for {agent}: {count}
|
||||||
|
|
||||||
|
{for each message}
|
||||||
|
---
|
||||||
|
[{priority}] {type} from {from_agent}
|
||||||
|
ID: {message_id}
|
||||||
|
Received: {created}
|
||||||
|
|
||||||
|
{payload_summary}
|
||||||
|
---
|
||||||
|
{end for}
|
||||||
|
</output>
|
||||||
|
</step>
|
||||||
|
</execution>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
<field name="messages" description="Array of message objects"/>
|
||||||
|
<field name="count" description="Number of messages"/>
|
||||||
|
</output>
|
||||||
|
</task>
|
||||||
|
|
@ -0,0 +1,72 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<task id="send-message" name="Send Inter-Agent Message" standalone="false">
|
||||||
|
<description>Send a message between BMAD agents using the messenger system</description>
|
||||||
|
|
||||||
|
<config>
|
||||||
|
<source>{project-root}/_bmad/core/messenger/messenger-config.yaml</source>
|
||||||
|
<queue_file>{project-root}/_bmad-output/messenger/message-queue.yaml</queue_file>
|
||||||
|
</config>
|
||||||
|
|
||||||
|
<parameters>
|
||||||
|
<param name="type" required="true" description="Message type: handoff, review, clarify, escalate, notify, collaborate"/>
|
||||||
|
<param name="from_agent" required="true" description="Sending agent identifier"/>
|
||||||
|
<param name="to_agent" required="false" description="Receiving agent (not needed for escalate)"/>
|
||||||
|
<param name="to_agents" required="false" description="List of receiving agents (for notify/collaborate)"/>
|
||||||
|
<param name="payload" required="true" description="Message payload object"/>
|
||||||
|
<param name="priority" required="false" default="medium" description="Message priority"/>
|
||||||
|
</parameters>
|
||||||
|
|
||||||
|
<execution>
|
||||||
|
<step n="1" goal="Validate message type and required fields">
|
||||||
|
<action>Load messenger config from {config_source}</action>
|
||||||
|
<action>Validate type is one of: handoff, review, clarify, escalate, notify, collaborate</action>
|
||||||
|
<action>Check required_fields for message type are present in payload</action>
|
||||||
|
<action if="validation fails">HALT with validation error message</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2" goal="Create message object">
|
||||||
|
<action>Generate unique message_id: "MSG-{timestamp}-{random4}"</action>
|
||||||
|
<action>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}
|
||||||
|
```
|
||||||
|
</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="3" goal="Ensure queue directory exists">
|
||||||
|
<action>Check if {queue_dir} exists</action>
|
||||||
|
<action if="not exists">Create directory {queue_dir}</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="4" goal="Add message to queue">
|
||||||
|
<action>Load existing queue from {queue_file} (or create empty if not exists)</action>
|
||||||
|
<action>Append new message to messages array</action>
|
||||||
|
<action>Sort messages by priority (critical first)</action>
|
||||||
|
<action>Save updated queue to {queue_file}</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="5" goal="Return confirmation">
|
||||||
|
<action>Return message_id and status</action>
|
||||||
|
<output>
|
||||||
|
Message sent successfully.
|
||||||
|
ID: {message_id}
|
||||||
|
Type: {type}
|
||||||
|
From: {from_agent}
|
||||||
|
To: {to_agent}
|
||||||
|
Priority: {priority}
|
||||||
|
</output>
|
||||||
|
</step>
|
||||||
|
</execution>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
<field name="message_id" description="Unique message identifier"/>
|
||||||
|
<field name="status" description="sent | failed"/>
|
||||||
|
</output>
|
||||||
|
</task>
|
||||||
Loading…
Reference in New Issue