bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

package/src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent.template.md

@@ -0,0 +1,77 @@
+{{#if comment}}
+------------------------------------------------------------------------------
+Expert Agent Handlebars Template
+Used by: step-06-build.md to generate final agent YAML
+Documentation: ../../data/expert-agent-architecture.md
+------------------------------------------------------------------------------
+{{/if}}
+agent:
+  metadata:
+    id: {{agent_id}}
+    name: {{agent_name}}
+    title: {{agent_title}}
+    icon: {{agent_icon}}
+    module: {{agent_module}}{{#if agent_module_comment}}  {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
+    hasSidecar: {{has_sidecar}}{{#if has_sidecar_comment}}  {{!-- true if agent has a sidecar folder, false otherwise --}}{{/if}}
+
+  persona:
+    role: |
+      {{persona_role}}{{#if persona_role_note}}
+      {{!-- 1-2 sentences, first person --}}{{/if}}
+
+    identity: |
+      {{persona_identity}}{{#if persona_identity_note}}
+      {{!-- 2-5 sentences, first person, background/specializations --}}{{/if}}
+
+    communication_style: |
+      {{communication_style}}{{#if communication_style_note}}
+      {{!-- How the agent speaks, include memory reference patterns --}}{{/if}}
+
+    principles:
+      {{#each principles}}
+      - {{this}}
+      {{/each}}
+
+  critical_actions:
+    {{#each critical_actions}}
+    - '{{{this}}}'
+    {{/each}}
+
+  {{#if has_prompts}}
+  prompts:
+    {{#each prompts}}
+    - id: {{id}}
+      content: |
+        {{{content}}}
+    {{/each}}
+  {{/if}}
+
+  menu:
+    {{#each menu_items}}
+    - trigger: {{trigger_code}} or fuzzy match on {{trigger_command}}
+      {{#if action_is_prompt}}
+      action: '#{{action_id}}'
+      {{else}}
+      action: {{{action_inline}}}
+      {{/if}}
+      description: '[{{trigger_code}}] {{{description}}}'
+    {{/each}}
+
+  {{#if has_install_config}}
+  install_config:
+    compile_time_only: true
+    description: '{{install_description}}'
+    questions:
+      {{#each install_questions}}
+      - var: {{var_name}}
+        prompt: '{{prompt}}'
+        type: {{question_type}}{{#if question_options}}
+        options:
+          {{#each question_options}}
+          - label: '{{label}}'
+            value: '{{value}}'
+          {{/each}}
+        {{/if}}
+        default: {{{default_value}}}
+      {{/each}}
+  {{/if}}

package/src/modules/bmb/workflows/agent/templates/simple-agent.template.md

@@ -0,0 +1,72 @@
+{{#if comment}}
+------------------------------------------------------------------------------
+Simple Agent Handlebars Template
+Used by: step-06-build.md to generate final agent YAML
+Documentation: ../data/simple-agent-architecture.md
+------------------------------------------------------------------------------
+{{/if}}
+agent:
+  metadata:
+    id: {{agent_id}}
+    name: {{agent_name}}
+    title: {{agent_title}}
+    icon: {{agent_icon}}
+    module: {{agent_module}}{{#if agent_module_comment}}  {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
+    hasSidecar: {{has_sidecar}}{{#if has_sidecar_comment}}  {{!-- true if agent has a sidecar folder, false otherwise --}}{{/if}}
+
+  persona:
+    role: |
+      {{persona_role}}{{#if persona_role_note}}
+      {{!-- 1-2 sentences, first person --}}{{/if}}
+
+    identity: |
+      {{persona_identity}}{{#if persona_identity_note}}
+      {{!-- 2-5 sentences, first person, background/specializations --}}{{/if}}
+
+    communication_style: |
+      {{communication_style}}{{#if communication_style_note}}
+      {{!-- How the agent speaks: tone, voice, mannerisms --}}{{/if}}
+
+    principles:
+      {{#each principles}}
+      - {{this}}
+      {{/each}}
+
+  {{#if has_prompts}}
+  prompts:
+    {{#each prompts}}
+    - id: {{id}}
+      content: |
+        {{{content}}}
+    {{/each}}
+  {{/if}}
+
+  menu:
+    {{#each menu_items}}
+    - trigger: {{trigger_code}} or fuzzy match on {{trigger_command}}
+      {{#if action_is_prompt}}
+      action: '#{{action_id}}'
+      {{else}}
+      action: {{{action_inline}}}
+      {{/if}}
+      description: '[{{trigger_code}}] {{{description}}}'
+    {{/each}}
+
+  {{#if has_install_config}}
+  install_config:
+    compile_time_only: true
+    description: '{{install_description}}'
+    questions:
+      {{#each install_questions}}
+      - var: {{var_name}}
+        prompt: '{{prompt}}'
+        type: {{question_type}}{{#if question_options}}
+        options:
+          {{#each question_options}}
+          - label: '{{label}}'
+            value: '{{value}}'
+          {{/each}}
+        {{/if}}
+        default: {{{default_value}}}
+      {{/each}}
+  {{/if}}

package/src/modules/bmb/workflows/agent/workflow.md

@@ -0,0 +1,123 @@
+---
+name: agent
+description: Tri-modal workflow for creating, editing, and validating BMAD Core compliant agents
+web_bundle: true
+---
+
+# Agent Workflow
+
+**Goal:** Collaboratively create, edit, or validate BMAD Core compliant agents through guided discovery and systematic execution.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an expert agent architect specializing in BMAD Core agent lifecycle management. You guide users through creating new agents, editing existing ones, or validating agent configurations.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file
+- **Just-In-Time Loading**: Only the current step file is in memory
+- **Sequential Enforcement**: Steps completed in order, conditional based on mode
+- **State Tracking**: Document progress in tracking files (agentPlan, editPlan, validationReport)
+- **Mode-Aware Routing**: Separate step flows for Create/Edit/Validate
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute numbered sections in order
+3. **WAIT FOR INPUT**: Halt at menus and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed when user selects appropriate option
+5. **SAVE STATE**: Update progress before loading next step
+6. **LOAD NEXT**: When directed, load and execute the next step file
+
+### Critical Rules
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps unless explicitly optional
+- 💾 **ALWAYS** save progress and outputs
+- 🎯 **ALWAYS** follow exact instructions in step files
+- ⏸️ **ALWAYS** halt at menus and wait for input
+- 📋 **NEVER** pre-load future steps
+
+---
+
+## MODE OVERVIEW
+
+This workflow supports three modes:
+
+| Mode | Purpose | Entry Point | Output |
+|------|---------|-------------|--------|
+| **Create** | Build new agent from scratch | `steps-c/step-01-brainstorm.md` | New `.agent.yaml` file |
+| **Edit** | Modify existing agent | `steps-e/e-01-load-existing.md` | Updated `.agent.yaml` file |
+| **Validate** | Review existing agent | `steps-v/v-01-load-review.md` | Validation report |
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. Mode Determination
+
+**Check if mode was specified in the command invocation:**
+
+- If user invoked with "create agent" or "new agent" → Set mode to **create**
+- If user invoked with "edit agent" or "modify agent" → Set mode to **edit**
+- If user invoked with "validate agent" or "review agent" → Set mode to **validate**
+
+**If mode is unclear from command, ask user:**
+
+"Welcome to the BMAD Agent Workflow! What would you like to do?
+
+**[C]reate** - Build a new agent from scratch
+**[E]dit** - Modify an existing agent
+**[V]alidate** - Review an existing agent and generate report
+
+Please select: [C]reate / [E]dit / [V]alidate"
+
+### 3. Route to First Step
+
+**IF mode == create:**
+Load, read completely, then execute `steps-c/step-01-brainstorm.md`
+
+**IF mode == edit:**
+Prompt for agent file path: "Which agent would you like to edit? Please provide the path to the `.agent.yaml` file."
+Then load, read completely, and execute `steps-e/e-01-load-existing.md`
+
+**IF mode == validate:**
+Prompt for agent file path: "Which agent would you like to validate? Please provide the path to the `.agent.yaml` file."
+Then load, read completely, and execute `steps-v/v-01-load-review.md`
+
+---
+
+## MODE-SPECIFIC NOTES
+
+### Create Mode
+- Starts with optional brainstorming
+- Progresses through discovery, metadata, persona, commands, activation
+- Builds agent based on type (Simple/Expert/Module)
+- Validates built agent
+- Celebrates completion with installation guidance
+
+### Edit Mode
+- Loads existing agent first
+- Discovers what user wants to change
+- Validates current agent before editing
+- Creates structured edit plan
+- Applies changes with validation
+- Celebrates successful edit
+
+### Validate Mode
+- Loads existing agent
+- Runs systematic validation (metadata, persona, menu, structure, sidecar)
+- Generates comprehensive validation report
+- Offers option to apply fixes if user desires

package/src/modules/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/modules/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_