@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/module/data/agent-architecture.md

@@ -0,0 +1,179 @@
+# 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

package/src/bmb/workflows/module/data/agent-spec-template.md

@@ -0,0 +1,79 @@
+# Agent Specification: {agent_name}
+
+**Module:** {module_code}
+**Status:** Placeholder — To be created via create-agent workflow
+**Created:** {date}
+
+---
+
+## Agent Metadata
+
+```yaml
+agent:
+  metadata:
+    id: "_bmad/{module_code}/agents/{agent_file_name}.md"
+    name: {agent_human_name}
+    title: {agent_title}
+    icon: {agent_icon}
+    module: {module_code}
+    hasSidecar: false
+```
+
+---
+
+## Agent Persona
+
+### Role
+
+{agent_role}
+
+### Identity
+
+{agent_identity}
+
+### Communication Style
+
+{agent_communication_style}
+
+### Principles
+
+{agent_principles}
+
+---
+
+## Agent Menu
+
+### Planned Commands
+
+| Trigger | Command | Description | Workflow |
+|---------|---------|-------------|----------|
+{agent_menu_table}
+
+---
+
+## Agent Integration
+
+### Shared Context
+
+- References: `{shared_context_files}`
+- Collaboration with: {collaborating_agents}
+
+### Workflow References
+
+{workflow_references}
+
+---
+
+## Implementation Notes
+
+**Use the create-agent workflow to build this agent.**
+
+Inputs needed:
+- Agent name and human name
+- Role and expertise area
+- Communication style preferences
+- Menu commands and workflow mappings
+
+---
+
+_Spec created on {date} via BMAD Module workflow_

package/src/bmb/workflows/module/data/module-standards.md

@@ -0,0 +1,263 @@
+# Module Standards
+
+**Purpose:** Defines what a BMAD module is, its structure, and the three types of modules.
+
+---
+
+## What is a BMAD Module?
+
+A **BMAD module** is a self-contained package of functionality that extends the BMAD framework. Modules provide:
+- **Agents** — AI personas with specialized expertise and menu-driven commands
+- **Workflows** — Structured processes for accomplishing complex tasks
+- **Configuration** — module.yaml for user customization
+
+---
+
+## Module Types
+
+### 1. Standalone Module
+
+A new, independent module focused on a specific domain.
+
+**Characteristics:**
+- Own module code (e.g., `healthcare-ai`, `legal-assist`)
+- Independent of other modules
+- Can be installed alongside any other modules
+- Has its own agents, workflows, configuration
+
+**Location:** `src/modules/{module-code}/`
+
+**Example:** CIS (Creative Innovation Suite) — a standalone module for innovation workflows
+
+---
+
+### 2. Extension Module
+
+Extends an existing BMAD module with additional functionality.
+
+**Characteristics:**
+- Builds upon an existing module's agents and workflows
+- May add new agents or workflows that complement the base module
+- Shares configuration context with the extended module
+- Typically installed alongside the module it extends
+
+**Location:** `src/modules/{base-module}/extensions/{extension-code}/`
+
+**Example:** An extension to BMM that adds specialized security review workflows
+
+---
+
+### Extension Module: Override & Merge Pattern
+
+When an extension module is installed, its files merge with the base module following these rules:
+
+#### Code Matching
+
+The extension's `module.yaml` `code:` field matches the base module's code:
+
+```yaml
+# Base module: src/modules/bmm/module.yaml
+code: bmm
+
+# Extension: src/modules/bmm/extensions/security/module.yaml
+code: bmm  # SAME CODE — extends BMM
+```
+
+The **folder name** is unique (e.g., `bmm-security`) but the `code:` matches the base module.
+
+#### File Merge Rules
+
+| File Type | Same Name | Different Name |
+|-----------|-----------|----------------|
+| Agent file | **OVERRIDE** — replaces the base agent | **ADD** — new agent added |
+| Workflow folder | **OVERRIDE** — replaces the base workflow | **ADD** — new workflow added |
+| Other files | **OVERRIDE** — replaces base file | **ADD** — new file added |
+
+#### Examples
+
+**Override scenario:**
+```
+Base module (BMM):
+├── agents/
+│   └── pm.agent.yaml          # Original PM agent
+
+Extension (bmm-security):
+├── agents/
+│   └── pm.agent.yaml          # Security-focused PM — REPLACES original
+
+Result after installation:
+├── agents/
+│   └── pm.agent.yaml          # Now the security version
+```
+
+**Add scenario:**
+```
+Base module (BMM):
+├── agents/
+│   ├── pm.agent.yaml
+│   └── architect.agent.yaml
+
+Extension (bmm-security):
+├── agents/
+│   └── security-auditor.agent.yaml  # NEW agent
+
+Result after installation:
+├── agents/
+│   ├── pm.agent.yaml
+│   ├── architect.agent.yaml
+│   └── security-auditor.agent.yaml  # ADDED
+```
+
+**Mixed scenario:**
+```
+Extension contains both overrides and new files — applies rules per file
+```
+
+---
+
+### 3. Global Module
+
+Affects the entire BMAD framework and all modules.
+
+**Characteristics:**
+- Core functionality that impacts all modules
+- Often provides foundational services or utilities
+- Installed at the framework level
+- Use sparingly — only for truly global concerns
+
+**Location:** `src/modules/{module-code}/` with `global: true` in module.yaml
+
+**Example:** A module that provides universal logging or telemetry across BMAD
+
+---
+
+## Required Module Structure
+
+```
+{module-code}/
+├── module.yaml                 # Module configuration (REQUIRED)
+├── README.md                   # Module documentation (REQUIRED)
+├── agents/                     # Agent definitions (if any)
+│   └── {agent-name}.agent.yaml
+├── workflows/                  # Workflow definitions (if any)
+│   └── {workflow-name}/
+│       └── workflow.md
+└── {other folders}             # Tasks, templates, data as needed
+```
+
+---
+
+## Required Files
+
+### module.yaml (REQUIRED)
+
+Every module MUST have a `module.yaml` file with at minimum:
+
+```yaml
+code: {module-code}
+name: "Module Display Name"
+header: "Brief module description"
+subheader: "Additional context"
+default_selected: false
+```
+
+See: `module-yaml-conventions.md` for full specification.
+
+---
+
+### README.md (REQUIRED)
+
+Every module MUST have a README.md with:
+- Module name and purpose
+- Installation instructions
+- Components section (agents, workflows)
+- Quick start guide
+- Module structure diagram
+- Configuration section
+- Usage examples
+- Author information
+
+---
+
+## Optional Components
+
+### Agents
+
+Agents are AI personas with:
+- Metadata (id, name, title, icon, module)
+- Persona (role, identity, communication_style, principles)
+- Menu (trigger → workflow/exec mappings)
+
+See: `agent-architecture.md` for design guidance.
+
+---
+
+### Workflows
+
+Workflows are structured processes with:
+- workflow.md (entry point)
+- steps/ folder with step files
+- data/ folder with shared reference
+- templates/ folder if needed
+
+---
+
+---
+
+## Module Type Decision Tree
+
+```
+START: Creating a module
+│
+├─ Is this a brand new independent domain?
+│  └─ YES → Standalone Module
+│
+├─ Does this extend an existing module?
+│  └─ YES → Extension Module
+│
+└─ Does this affect all modules globally?
+   └─ YES → Global Module (use sparingly)
+```
+
+---
+
+## Naming Conventions
+
+### Module Code
+
+- **kebab-case** (e.g., `bmm`, `cis`, `bmgd`, `healthcare-ai`)
+- Short, memorable, descriptive
+- 2-20 characters
+- Lowercase letters, numbers, hyphens only
+
+### Agent Files
+
+- Format: `{role-name}.agent.yaml`
+- Example: `pm.agent.yaml`, `architect.agent.yaml`
+
+### Workflow Folders
+
+- Format: `{workflow-name}/`
+- Example: `prd/`, `create-architecture/`
+
+---
+
+## Module Dependencies
+
+Modules can depend on:
+- **Core BMAD** — Always available
+- **Other modules** — Specify in module.yaml as `dependencies:`
+- **External tools** — Document in README
+
+---
+
+## Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| What's a module? | Self-contained package of agents, workflows, config |
+| What are the types? | Standalone, Extension, Global |
+| What's required? | module.yaml, README.md |
+| Where do modules live? | `src/modules/{code}/` |
+| How do agents work? | Menu triggers → workflow/exec |
+| How does installation work? | module.yaml prompts |