brachnha-insight/_bmad/bmb/workflows/module/data/agent-architecture.md

Agent Architecture for Modules

Purpose: High-level guidance for planning agents in your module — not implementation details (that's what the agent-builder workflow is for).

---

Single Agent vs. Multi-Agent Module

Single Agent Module

Use when: One persona can handle the module's purpose.

Characteristics:

• Simpler, focused
• Clear single point of contact
• Good for narrow domains

Question: Could one expert agent with a sidecar handle this entire module?

---

Multi-Agent Module

Use when: Different expertise areas justify specialized personas.

Characteristics:

• Each agent has a distinct role and expertise
• Agents form a cohesive team around the module's theme
• Menus coordinate to guide users to the right agent

Why multi-agent?

• Different workflows need different expert perspectives
• Users expect to talk to "the right expert" for each task
• The module covers a domain too broad for one persona

---

Flagship Example: BMM Agent Team

BMM demonstrates a multi-agent module with 9 specialized agents forming a complete software development team.

The BMM Theme

"Agile software delivery, AI-driven"

Every agent serves this theme — they're a complete team working together.

BMM Agent Overview

Agent	Name	Role	Responsible For
PM	John	Product Manager	PRDs, requirements, user stories
Architect	Winston	System Architect	Technical design, architecture
UX		UX Designer	User research, UX design
Dev		Developer	Implementation, coding
TEA		Test Engineer Architect	Test architecture, QA
SM		Scrum Master	Sprint planning, workflow status
Tech Writer		Technical Writer	Documentation
Analyst		Business Analyst	Analysis, metrics
Quick Flow		Solo Developer	Quick standalone work

Key Patterns

1. Shared commands — All agents have [WS] Workflow Status
2. Specialty commands — Each agent has unique commands (PM→PRD, Architect→Architecture)
3. No overlap — Each command has one clear owner
4. Collaboration — Agents reference each other's work (PRD → Architecture → Implementation)

---

Planning Your Agents

For Each Agent, Document:

1. Role — What is this agent responsible for?
2. Workflows — Which workflows will this agent trigger/own?
3. Human Name — What's their persona name? (e.g., "John", "Winston")
4. Communication Style — How do they talk? (e.g., "Direct and data-sharp", "Calm and pragmatic")
5. Skills/Expertise — What knowledge does this agent bring?
6. Memory/Learning — Does this agent need to remember things over time? (hasSidecar)

That's it! The agent-builder workflow will handle the detailed implementation.

---

Agent Memory & Learning

Sidecar Agents (hasSidecar: true)

Use when: The agent needs to remember context across sessions.

Characteristics:

• Has a sidecar file that persists between conversations
• Learns from user interactions
• Remembers project details, preferences, past work

Examples:

• An agent that tracks project decisions over time
• An agent that learns user preferences
• An agent that maintains ongoing project context

Stateless Agents (hasSidecar: false)

Use when: The agent doesn't need persistent memory.

Characteristics:

• Each conversation starts fresh
• Relies on shared context files (like project-context.md)
• Simpler, more predictable

Most module agents are stateless — they reference shared project context rather than maintaining their own memory.

---

Agent-Workflow Coordination

Menu Triggers

Each agent has menu items that trigger workflows:

Trigger Type	Pattern	Example
Shared	Same across all agents	[WS] Workflow Status
Specialty	Unique to this agent	[PR] Create PRD (PM only)
Cross-reference	Points to another agent's workflow	"See architecture"

Simple Planning Format

For each agent, just document:

Agent: PM (John)
Role: Product Manager, requirements, PRDs
Triggers:
  - WS → Workflow Status (shared)
  - PR → Create PRD (specialty)
  - ES → Epics and Stories (specialty)
Memory: No (uses shared project-context)

The agent-builder workflow will convert this into the proper format.

---

When to Use Multiple Agents

Consider multiple agents when:

• Different workflows require different expertise
• The domain has clear specialization areas
• Users would expect to talk to different "experts"
• The module covers a broad process (like software development)

Use a single agent when:

• The domain is focused and narrow
• One expertise area covers all workflows
• Simplicity is preferred
• The agent could reasonably handle everything with a sidecar

---

Quick Agent Planning Checklist

For each agent in your module:

• Role defined (what they're responsible for)
• Workflows assigned (which workflows they trigger)
• Human name chosen (persona)
• Communication style described
• Skills/expertise identified
• Memory decision (hasSidecar: true/false)

---

Notes

• Don't worry about the exact YAML format — agent-builder handles that
• Focus on the planning — who does what, how they work together
• Keep it high-level — this is about the module's agent architecture, not implementation details
• BMM is the reference — look at how their agents form a cohesive team