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

package/src/modules/bmb/workflows/agent/steps-v/v-02d-validate-structure.md

@@ -4,44 +4,98 @@ description: 'Validate YAML structure and append to report'
 
 nextStepFile: './v-02e-validate-sidecar.md'
 validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
+simpleValidation: ../data/simple-agent-validation.md
+expertValidation: ../data/expert-agent-validation.md
 agentCompilation: ../data/agent-compilation.md
+agentFile: '{agent-file-path}'
 ---
 
 # Validate Step 2d: Validate Structure
 
-## STEP GOAL:
+## STEP GOAL
 
-Validate the agent's YAML structure and completeness. Append findings to validation report and auto-advance.
+Validate the agent's YAML structure and completeness against BMAD standards as defined in agentCompilation.md. Append findings to validation report and auto-advance.
 
-## MANDATORY EXECUTION RULES:
+## MANDATORY EXECUTION RULES
 
 - 📖 CRITICAL: Read the complete step file before taking any action
 - 🔄 CRITICAL: Read validationReport and agentCompilation first
+- 🔄 CRITICAL: Load the actual agent file to validate structure
 - 🚫 NO MENU - append findings and auto-advance
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 
 ### Step-Specific Rules:
 
-- 🎯 Validate YAML structure and required fields
+- 🎯 Validate structure against agentCompilation.md rules
 - 📊 Append findings to validation report
 - 🚫 FORBIDDEN to present menu
 
-## EXECUTION PROTOCOLS:
+## EXECUTION PROTOCOLS
 
 - 🎯 Load agentCompilation.md reference
+- 🎯 Load the actual agent file for validation
 - 📊 Validate YAML structure
 - 💾 Append findings to validation report
 - ➡️ Auto-advance to next validation step
 
-## Sequence of Instructions:
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
 ### 1. Load References
 
-Read `{agentCompilation}` and `{validationReport}`.
+Read `{agentCompilation}`, `{simpleValidation}`, `{expertValidation}`, `{validationReport}`, and `{agentFile}`.
 
 ### 2. Validate Structure
 
-Perform checks on: YAML syntax, required fields, field types, indentation.
+Perform these checks systematically - validate EVERY rule specified in agentCompilation.md:
+
+#### A. YAML Syntax Validation
+- [ ] Parse YAML without errors
+- [ ] Check indentation consistency (2-space standard)
+- [ ] Validate proper escaping of special characters
+- [ ] Verify no duplicate keys in any section
+
+#### B. Frontmatter Validation
+- [ ] All required fields present (name, description, version, etc.)
+- [ ] Field values are correct type (string, boolean, array)
+- [ ] No empty required fields
+- [ ] Proper array formatting with dashes
+- [ ] Boolean fields are actual booleans (not strings)
+
+#### C. Section Completeness
+- [ ] All required sections present based on agent type
+- [ ] Sections not empty unless explicitly optional
+- [ ] Proper markdown heading hierarchy (##, ###)
+- [ ] No orphaned content without section headers
+
+#### D. Field-Level Validation
+- [ ] Path references exist and are valid
+- [ ] Array fields properly formatted
+- [ ] No malformed YAML structures
+- [ ] File references use correct path format
+
+#### E. Agent Type Specific Checks
+
+**For Simple Agents (hasSidecar is false/absent, module is 'stand-alone'):**
+- [ ] No sidecar requirements
+- [ ] No sidecar-folder path in metadata
+- [ ] Basic fields complete
+- [ ] No expert-only configuration present
+- [ ] Menu handlers use only internal references (#) or inline prompts
+
+**For Expert Agents (hasSidecar is true):**
+- [ ] Sidecar flag set correctly in metadata
+- [ ] Sidecar folder path specified in metadata
+- [ ] All expert fields present
+- [ ] Advanced features properly configured
+- [ ] Menu handlers reference sidecar files or have inline prompts
+
+**For Module Agents (module is a module code like 'bmm', 'bmb', etc.):**
+- [ ] Module property is valid module code
+- [ ] Exec paths for menu handlers start with `{project-root}/_bmad/{module}/...`
+- [ ] Referenced files exist under the module directory
+- [ ] If also hasSidecar: true, sidecar configuration is valid
 
 ### 3. Append Findings to Report
 
@@ -52,14 +106,25 @@ Append to `{validationReport}`:
 
 **Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
 
+**Agent Type:** {simple|expert|module}
+
 **Checks:**
 - [ ] Valid YAML syntax
 - [ ] Required fields present (name, description, type, persona)
 - [ ] Field types correct (arrays, strings)
 - [ ] Consistent 2-space indentation
+- [ ] Agent type appropriate structure
+
+**Detailed Findings:**
+
+*PASSING:*
+{List of passing checks}
+
+*WARNINGS:*
+{List of non-blocking issues}
 
-**Findings:**
-{Detailed findings}
+*FAILURES:*
+{List of blocking issues that must be fixed}
 ```
 
 ### 4. Auto-Advance

package/src/modules/bmb/workflows/agent/steps-v/v-02e-validate-sidecar.md

@@ -5,49 +5,94 @@ description: 'Validate sidecar structure and append to report'
 nextStepFile: './v-03-summary.md'
 validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
 expertValidation: ../data/expert-agent-validation.md
+criticalActions: ../data/critical-actions.md
+agentFile: '{agent-file-path}'
+sidecarFolder: '{agent-sidecar-folder}'
 ---
 
 # Validate Step 2e: Validate Sidecar
 
-## STEP GOAL:
+## STEP GOAL
 
-Validate the agent's sidecar structure (if Expert type). Append findings to validation report and auto-advance.
+Validate the agent's sidecar structure (if Expert type) against BMAD standards as defined in expertValidation.md. Append findings to validation report and auto-advance.
 
-## MANDATORY EXECUTION RULES:
+## MANDATORY EXECUTION RULES
 
 - 📖 CRITICAL: Read the complete step file before taking any action
 - 🔄 CRITICAL: Read validationReport and expertValidation first
+- 🔄 CRITICAL: Load the actual agent file to check for sidecar
 - 🚫 NO MENU - append findings and auto-advance
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 
 ### Step-Specific Rules:
 
-- 🎯 Validate sidecar structure for Expert agents
+- 🎯 Validate sidecar against expertValidation.md rules (for Expert agents)
 - 📊 Append findings to validation report
 - 🚫 FORBIDDEN to present menu
 
-## EXECUTION PROTOCOLS:
+## EXECUTION PROTOCOLS
 
 - 🎯 Load expertValidation.md reference
+- 🎯 Load the actual agent file for validation
 - 📊 Validate sidecar if Expert type, skip for Simple/Module
 - 💾 Append findings to validation report
 - ➡️ Auto-advance to summary step
 
-## Sequence of Instructions:
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
 ### 1. Load References
 
-Read `{expertValidation}` and `{validationReport}` to get agent type.
+Read `{expertValidation}`, `{criticalActions}`, `{validationReport}`, and `{agentFile}`.
 
 ### 2. Conditional Validation
 
-**IF agentType == expert:**
-- Check metadata.sidecar-folder present
-- Check sidecar-path correct format
-- Verify sidecar files exist
-
-**IF agentType != expert:**
-- Mark as N/A
+**IF (module = "stand-alone" AND hasSidecar = true) OR (module ≠ "stand-alone" AND hasSidecar = true):**
+Perform these checks systematically - validate EVERY rule specified in expertValidation.md:
+
+#### A. Sidecar Folder Validation
+- [ ] Sidecar folder exists at specified path
+- [ ] Sidecar folder is accessible and readable
+- [ ] Sidecar folder path in metadata matches actual location
+- [ ] Folder naming follows convention: `{agent-name}-sidecar`
+
+#### B. Sidecar File Inventory
+- [ ] List all files in sidecar folder
+- [ ] Verify expected files are present
+- [ ] Check for unexpected files
+- [ ] Validate file names follow conventions
+
+#### C. Path Reference Validation
+For each sidecar path reference in agent YAML:
+- [ ] Extract path from YAML reference
+- [ ] Verify file exists at referenced path
+- [ ] Check path format is correct (relative/absolute as expected)
+- [ ] Validate no broken path references
+
+#### D. Critical Actions File Validation (if present)
+- [ ] critical-actions.md file exists
+- [ ] File has proper frontmatter
+- [ ] Actions section is present and not empty
+- [ ] No critical sections missing
+- [ ] File content is complete (not just placeholder)
+
+#### E. Module Files Validation (if present)
+- [ ] Module files exist at referenced paths
+- [ ] Each module file has proper frontmatter
+- [ ] Module file content is complete
+- [ ] No empty or placeholder module files
+
+#### F. Sidecar Structure Completeness
+- [ ] All referenced sidecar files present
+- [ ] No orphaned references (files referenced but not present)
+- [ ] No unreferenced files (files present but not referenced)
+- [ ] File structure matches expert agent requirements
+
+**IF (module = "stand-alone" AND hasSidecar = false):**
+- [ ] Mark sidecar validation as N/A
+- [ ] Confirm no sidecar-folder path in metadata
+- [ ] Confirm no sidecar references in menu handlers
 
 ### 3. Append Findings to Report
 
@@ -58,13 +103,28 @@ Append to `{validationReport}`:
 
 **Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL / N/A}
 
+**Agent Type:** {simple|expert|module with sidecar}
+
 **Checks:**
 - [ ] metadata.sidecar-folder present (Expert only)
 - [ ] sidecar-path format correct
 - [ ] Sidecar files exist at specified path
+- [ ] All referenced files present
+- [ ] No broken path references
+
+**Detailed Findings:**
+
+*PASSING (for Expert agents):*
+{List of passing checks}
+
+*WARNINGS:*
+{List of non-blocking issues}
+
+*FAILURES:*
+{List of blocking issues that must be fixed}
 
-**Findings:**
-{Detailed findings or "N/A - Not an Expert agent"}
+*N/A (for Simple agents):*
+N/A - Agent is Simple type (module = "stand-alone" + hasSidecar: false, no sidecar required)
 ```
 
 ### 4. Auto-Advance

package/src/modules/bmb/workflows/agent/steps-v/v-03-summary.md

@@ -32,7 +32,9 @@ Display the complete validation report to the user and offer options for fixing
 - 📊 Display organized summary
 - 💾 Allow user to decide next steps
 
-## Sequence of Instructions:
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
 ### 1. Load Validation Report
 
@@ -57,6 +59,7 @@ Read `{validationReport}` to collect all validation findings.
 "What would you like to do?
 
 **[E]dit Agent** - Launch edit workflow to fix issues or make improvements
+**[F]ix in Place** - Confirm which fixes you would like right now and we can fix without loading the full agent edit workflow
 **[S]ave Report** - Save this validation report and exit
 **[R]etry** - Run validation again (if you've made external changes)"
 
@@ -69,6 +72,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [E] Edit
 - IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
 - IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
 - IF E: Inform user they can launch edit workflow with the same agent file, then redisplay menu
+- IF F; Attempt to make users desired fixes without loading the full edit workflow
 - IF S: Save final report to {validationReport} and end workflow
 - IF R: Restart validation from step v-01
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options)

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

@@ -12,6 +12,7 @@ agent:
     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: |

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

@@ -12,6 +12,7 @@ agent:
     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: |

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_