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