BMAD-METHOD/core/messenger/messenger.md

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:

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:

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:

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:

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:

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:

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

<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

<exec task="receive-message">
  <param name="agent">architect</param>
  <param name="type_filter">handoff</param>
</exec>

Queue File Structure

# _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