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

package/src/modules/bmb/workflows/agent/steps-e/e-08b-edit-expert.md

@@ -2,7 +2,7 @@
 name: 'e-08b-edit-expert'
 description: 'Apply edits to Expert agent'
 
-nextStepFile: './e-09a-validate-metadata.md'
+nextStepFile: './e-09-celebrate.md'
 editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
 agentFile: '{original-agent-path}'
 agentBackup: '{original-agent-path}.backup'
@@ -48,7 +48,9 @@ Apply all planned edits to the Expert agent YAML file and manage sidecar structu
 - ✅ Validate YAML and sidecar paths
 - ➡️ 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 Reference Documents
 
@@ -70,10 +72,10 @@ ALWAYS backup before editing:
 
 ### 4. Apply Edits in Sequence
 
-**Type Conversion to Expert:**
-- Update `type: expert`
+**Type Conversion TO Expert:**
+- Set `module: stand-alone` and `hasSidecar: true`
 - Add `metadata.sidecar-folder` if not present
-- Create sidecar directory: `mkdir -p {project-root}/_bmad/_memory/{sidecar-folder}/`
+- Create sidecar directory next to agent.yaml: `{agent-folder}/{agent-name}-sidecar/`
 
 **Sidecar Management:**
 - If changing sidecar-folder: update all critical_actions references

package/src/modules/bmb/workflows/agent/steps-e/e-08c-edit-module.md

@@ -2,7 +2,7 @@
 name: 'e-08c-edit-module'
 description: 'Apply edits to Module agent'
 
-nextStepFile: './e-09a-validate-metadata.md'
+nextStepFile: './e-09-celebrate.md'
 editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
 agentFile: '{original-agent-path}'
 agentBackup: '{original-agent-path}.backup'
@@ -48,11 +48,13 @@ Apply all planned edits to the Module agent YAML file and manage workflow integr
 - ✅ Validate YAML and workflow paths
 - ➡️ 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 Reference Documents
 
-Read all files before editing:
+Read all files before editing - these are RULES that must be followed when editing agents:
 - `{expertTemplate}` - Module uses expert as baseline
 - `{expertArch}`, `{moduleArch}` - Architecture references
 - `{agentCompilation}`, `{agentMetadata}`, `{personaProperties}`, `{principlesCrafting}`
@@ -70,9 +72,10 @@ ALWAYS backup before editing:
 
 ### 4. Apply Edits in Sequence
 
-**Type Conversion to Module:**
-- Update `type: module`
+**Type Conversion TO Module:**
+- Set `module` to module code (e.g., `bmm`, `cis`, `bmgd`, or custom)
 - Add workflow integration paths
+- Optionally set `hasSidecar: true` if complex multi-workflow module
 
 **Workflow Path Management:**
 - Add: `skills: - workflow: {path}`

package/src/modules/bmb/workflows/agent/steps-e/{e-10-celebrate.md → e-09-celebrate.md}

@@ -1,14 +1,15 @@
 ---
-name: 'e-10-celebrate'
+name: 'e-09-celebrate'
 description: 'Celebrate successful agent edit completion'
 
 editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
 
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+validationWorkflow: '{project-root}/src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md'
 ---
 
-# Edit Step 10: Celebration
+# Edit Step 9: Celebration
 
 ## STEP GOAL:
 
@@ -48,7 +49,9 @@ Celebrate the successful agent edit, provide summary of changes, and mark edit w
 - Limits: No more edits, only acknowledgment
 - Dependencies: All edits successfully applied
 
-## Sequence of Instructions:
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.:
 
 ### 1. Read Edit Plan
 
@@ -110,24 +113,26 @@ Append to editPlan:
 
 ### 6. Present MENU OPTIONS
 
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [X] Exit Workflow"
+Display: "**✅ Agent Edit Complete! Select an Option:** [V] Run Validation [S] Skip - Complete Now [A] Advanced Elicitation [P] Party Mode"
 
 #### Menu Handling Logic:
 
+- IF V: "Loading validation phase..." → Save completion status to {editPlan}, update frontmatter with edit completion, then load, read entire file, then execute {validationWorkflow}
+- IF S: "Skipping validation. Completing workflow..." → Save completion status to {editPlan} and end workflow gracefully
 - IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
 - IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF X: Save completion status to {editPlan} and end workflow gracefully
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- ONLY complete workflow when user selects 'X'
-- After other menu items execution, return to this menu
+- User can choose validation (V), skip to complete (S), or use advanced elicitation (A) or party mode (P)
+- After other menu items execution (A/P), return to this menu
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN [X exit option] is selected and [completion documented], will the workflow end gracefully with agent edit complete.
+ONLY WHEN [S skip option] is selected and [completion documented], will the workflow end gracefully with agent edit complete.
+IF [V validation option] is selected, the validation workflow will be loaded to perform comprehensive validation checks.
 
 ---
 

package/src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md

@@ -34,11 +34,19 @@ Load the existing agent file and initialize a validation report to track all fin
 - 💾 Create validation report document
 - 🚫 FORBIDDEN to proceed without user confirmation
 
-## Sequence of Instructions:
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
 ### 1. Load Agent File
 
 Read the complete YAML from the agent file path provided by the user.
+If the module property of the agent metadata is stand-alone, it is not a module agent.
+If the module property of the agent is a module code (like bmm, bmb, etc...) it is a module agent.
+If the property hasSidecar: true exists in the metadata, then it is an expert agent.
+Else it is a simple agent.
+
+If a module agent also hasSidecar: true - this means it is a modules expert agent, thus it can have sidecar.
 
 ### 2. Display Agent Summary
 
@@ -46,7 +54,6 @@ Read the complete YAML from the agent file path provided by the user.
 ## Agent to Validate: {agent-name}
 
 **Type:** {simple|expert|module}
-**Version:** {version}
 **File:** {agent-file-path}
 
 ### Current Structure:
@@ -63,7 +70,7 @@ Initialize the validation report:
 ```markdown
 ---
 agentName: '{agent-name}'
-agentType: '{simple|expert|module}'
+agentType: '{simple|expert|module}'  # Derived from module + hasSidecar
 agentFile: '{agent-file-path}'
 validationDate: '{YYYY-MM-DD}'
 stepsCompleted:
@@ -75,8 +82,9 @@ stepsCompleted:
 ## Agent Overview
 
 **Name:** {agent-name}
-**Type:** {simple|expert|module}
-**Version:** {version}
+**Type:** {simple|expert|module}  # Derived from: module + hasSidecar
+**module:** {module-value}
+**hasSidecar:** {true|false}
 **File:** {agent-file-path}
 
 ---
@@ -90,7 +98,7 @@ Write to `{validationReport}`.
 
 ### 4. Present MENU OPTIONS
 
-Display: "**Is this the correct agent to validate?** [A] Advanced Elicitation [P] Party Mode [C] Yes, Begin Validation"
+Display: "**Is this the correct agent to validate and is it identified as the proper type?** [A] Advanced Elicitation [P] Party Mode [C] Yes, Begin Validation"
 
 #### Menu Handling Logic:
 

package/src/modules/bmb/workflows/agent/steps-v/v-02a-validate-metadata.md

@@ -5,18 +5,20 @@ description: 'Validate metadata and append to report'
 nextStepFile: './v-02b-validate-persona.md'
 validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
 agentMetadata: ../data/agent-metadata.md
+agentFile: '{agent-file-path}'
 ---
 
 # Validate Step 2a: Validate Metadata
 
-## STEP GOAL:
+## STEP GOAL
 
-Validate the agent's metadata properties against BMAD standards. Append findings to validation report and auto-advance.
+Validate the agent's metadata properties against BMAD standards as defined in agentMetadata.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 agentMetadata first
+- 🔄 CRITICAL: Load the actual agent file to validate metadata
 - 🚫 NO MENU - append findings and auto-advance
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 
@@ -26,22 +28,55 @@ Validate the agent's metadata properties against BMAD standards. Append findings
 - 📊 Append findings to validation report
 - 🚫 FORBIDDEN to present menu
 
-## EXECUTION PROTOCOLS:
+## EXECUTION PROTOCOLS
 
 - 🎯 Load agentMetadata.md reference
+- 🎯 Load the actual agent file for validation
 - 📊 Validate all metadata fields
 - 💾 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 `{agentMetadata}` and `{validationReport}`.
+Read `{agentMetadata}`, `{validationReport}`, and `{agentFile}`.
 
 ### 2. Validate Metadata
 
-Perform checks on: id, name, title, icon, module, hasSidecar.
+Perform these checks systematically - validate EVERY rule specified in agentMetadata.md:
+
+1. **Required Fields Existence**
+   - [ ] id: Present and non-empty
+   - [ ] name: Present and non-empty (display name)
+   - [ ] title: Present and non-empty
+   - [ ] icon: Present (emoji or symbol)
+   - [ ] module: Present and valid format
+   - [ ] hasSidecar: Present (boolean, if applicable)
+
+2. **Format Validation**
+   - [ ] id: Uses kebab-case, no spaces, unique identifier
+   - [ ] name: Clear display name for UI
+   - [ ] title: Concise functional description
+   - [ ] icon: Appropriate emoji or unicode symbol
+   - [ ] module: Either a 3-4 letter module code OR 'stand-alone'
+   - [ ] hasSidecar: Boolean value, matches actual agent structure
+
+3. **Content Quality**
+   - [ ] id: Unique and descriptive
+   - [ ] name: Clear and user-friendly
+   - [ ] title: Accurately describes agent's function
+   - [ ] icon: Visually representative of agent's purpose
+   - [ ] module: Correctly identifies module membership
+   - [ ] hasSidecar: Correctly indicates if agent uses sidecar files
+
+4. **Agent Type Consistency**
+   - [ ] If hasSidecar: true, sidecar folder path must be specified
+   - [ ] If module is a module code, agent is a module agent
+   - [ ] If module is 'stand-alone', agent is not part of a module
+   - [ ] No conflicting type indicators
 
 ### 3. Append Findings to Report
 
@@ -53,15 +88,23 @@ Append to `{validationReport}`:
 **Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
 
 **Checks:**
-- [ ] id: kebab-case, no spaces
+- [ ] id: kebab-case, no spaces, unique
 - [ ] name: clear display name
 - [ ] title: concise function description
 - [ ] icon: appropriate emoji/symbol
-- [ ] module: correct format `{project}:{type}:{name}`
+- [ ] module: correct format (code or stand-alone)
 - [ ] hasSidecar: matches actual usage
 
-**Findings:**
-{Detailed findings}
+**Detailed Findings:**
+
+*PASSING:*
+{List of passing checks}
+
+*WARNINGS:*
+{List of non-blocking issues}
+
+*FAILURES:*
+{List of blocking issues that must be fixed}
 ```
 
 ### 4. Auto-Advance

package/src/modules/bmb/workflows/agent/steps-v/v-02b-validate-persona.md

@@ -6,43 +6,87 @@ nextStepFile: './v-02c-validate-menu.md'
 validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
 personaProperties: ../data/persona-properties.md
 principlesCrafting: ../data/principles-crafting.md
+agentFile: '{agent-file-path}'
 ---
 
 # Validate Step 2b: Validate Persona
 
-## STEP GOAL:
+## STEP GOAL
 
-Validate the agent's persona against BMAD standards. Append findings to validation report and auto-advance.
+Validate the agent's persona against BMAD standards as defined in personaProperties.md and principlesCrafting.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 persona references first
+- 🔄 CRITICAL: Load the actual agent file to validate persona
 - 🚫 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 persona four-field system
+- 🎯 Validate persona against personaProperties.md rules
 - 📊 Append findings to validation report
 - 🚫 FORBIDDEN to present menu
 
-## EXECUTION PROTOCOLS:
+## EXECUTION PROTOCOLS
 
 - 🎯 Load personaProperties.md and principlesCrafting.md
+- 🎯 Load the actual agent file for validation
 - 📊 Validate persona fields
 - 💾 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 `{personaProperties}`, `{principlesCrafting}`, and `{validationReport}`.
+Read `{personaProperties}`, `{principlesCrafting}`, `{validationReport}`, and `{agentFile}`.
 
 ### 2. Validate Persona
 
-Perform checks on: role, identity, communication_style, principles.
+Perform these checks systematically - validate EVERY rule specified in personaProperties.md:
+
+1. **Required Fields Existence**
+   - [ ] role: Present, clear, and specific
+   - [ ] identity: Present and defines who the agent is
+   - [ ] communication_style: Present and appropriate to role
+   - [ ] principles: Present as array, not empty (if applicable)
+
+2. **Content Quality - Role**
+   - [ ] Role is specific (not generic like "assistant")
+   - [ ] Role aligns with agent's purpose and menu items
+   - [ ] Role is achievable within LLM capabilities
+   - [ ] Role scope is appropriate (not too broad/narrow)
+
+3. **Content Quality - Identity**
+   - [ ] Identity clearly defines the agent's character
+   - [ ] Identity is consistent with the role
+   - [ ] Identity provides context for behavior
+   - [ ] Identity is not generic or cliché
+
+4. **Content Quality - Communication Style**
+   - [ ] Communication style is clearly defined
+   - [ ] Style matches the role and target users
+   - [ ] Style is consistent throughout the definition
+   - [ ] Style examples or guidance provided if nuanced
+   - [ ] Style focuses on speech patterns only (not behavior)
+
+5. **Content Quality - Principles**
+   - [ ] Principles are actionable (not vague platitudes)
+   - [ ] Principles guide behavior and decisions
+   - [ ] Principles are consistent with role
+   - [ ] 3-7 principles recommended (not overwhelming)
+   - [ ] Each principle is clear and specific
+   - [ ] First principle activates expert knowledge domain
+
+6. **Consistency Checks**
+   - [ ] Role, identity, communication_style, principles all align
+   - [ ] No contradictions between principles
+   - [ ] Persona supports the menu items defined
+   - [ ] Language and terminology consistent
 
 ### 3. Append Findings to Report
 
@@ -59,8 +103,16 @@ Append to `{validationReport}`:
 - [ ] communication_style: speech patterns only
 - [ ] principles: first principle activates expert knowledge
 
-**Findings:**
-{Detailed findings}
+**Detailed Findings:**
+
+*PASSING:*
+{List of passing checks}
+
+*WARNINGS:*
+{List of non-blocking issues}
+
+*FAILURES:*
+{List of blocking issues that must be fixed}
 ```
 
 ### 4. Auto-Advance

package/src/modules/bmb/workflows/agent/steps-v/v-02c-validate-menu.md

@@ -5,43 +5,108 @@ description: 'Validate menu structure and append to report'
 nextStepFile: './v-02d-validate-structure.md'
 validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
 agentMenuPatterns: ../data/agent-menu-patterns.md
+agentFile: '{agent-file-path}'
 ---
 
 # Validate Step 2c: Validate Menu
 
-## STEP GOAL:
+## STEP GOAL
 
-Validate the agent's command menu structure against BMAD standards. Append findings to validation report and auto-advance.
+Validate the agent's command menu structure against BMAD standards as defined in agentMenuPatterns.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 agentMenuPatterns first
+- 🔄 CRITICAL: Load the actual agent file to validate menu
 - 🚫 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 command/menu structure
+- 🎯 Validate menu against agentMenuPatterns.md rules
 - 📊 Append findings to validation report
 - 🚫 FORBIDDEN to present menu
 
-## EXECUTION PROTOCOLS:
+## EXECUTION PROTOCOLS
 
 - 🎯 Load agentMenuPatterns.md reference
+- 🎯 Load the actual agent file for validation
 - 📊 Validate commands and menu
 - 💾 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 `{agentMenuPatterns}` and `{validationReport}`.
+Read `{agentMenuPatterns}`, `{validationReport}`, and `{agentFile}`.
 
 ### 2. Validate Menu
 
-Perform checks on: A/P/C convention, command names, descriptions.
+Perform these checks systematically - validate EVERY rule specified in agentMenuPatterns.md:
+
+1. **Menu Structure**
+   - [ ] Menu section exists and is properly formatted
+   - [ ] At least one menu item defined (unless intentionally tool-less)
+   - [ ] Menu items follow proper YAML structure
+   - [ ] Each item has required fields (name, description, pattern)
+
+2. **Menu Item Requirements**
+   For each menu item:
+   - [ ] name: Present, unique, uses kebab-case
+   - [ ] description: Clear and concise
+   - [ ] pattern: Valid regex pattern or tool reference
+   - [ ] scope: Appropriate scope defined (if applicable)
+
+3. **Pattern Quality**
+   - [ ] Patterns are valid and testable
+   - [ ] Patterns are specific enough to match intended inputs
+   - [ ] Patterns are not overly restrictive
+   - [ ] Patterns use appropriate regex syntax
+
+4. **Description Quality**
+   - [ ] Each item has clear description
+   - [ ] Descriptions explain what the item does
+   - [ ] Descriptions are consistent in style
+   - [ ] Descriptions help users understand when to use
+
+5. **Alignment Checks**
+   - [ ] Menu items align with agent's role/purpose
+   - [ ] Menu items are supported by agent's expertise
+   - [ ] Menu items fit within agent's constraints
+   - [ ] Menu items are appropriate for target users
+
+6. **Completeness**
+   - [ ] Core capabilities for this role are covered
+   - [ ] No obvious missing functionality
+   - [ ] Menu scope is appropriate (not too sparse/overloaded)
+   - [ ] Related functionality is grouped logically
+
+7. **Standards Compliance**
+   - [ ] No prohibited patterns or commands
+   - [ ] No security vulnerabilities in patterns
+   - [ ] No ambiguous or conflicting items
+   - [ ] Consistent naming conventions
+
+8. **Menu Link Validation (Agent Type Specific)**
+   - [ ] Determine agent type from metadata:
+     - Simple: module property is 'stand-alone' AND hasSidecar is false/absent
+     - Expert: hasSidecar is true
+     - Module: module property is a module code (e.g., 'bmm', 'bmb', 'bmgd', 'bmad')
+   - [ ] For Expert agents (hasSidecar: true):
+     - Menu handlers SHOULD reference external sidecar files (e.g., `./{agent-name}-sidecar/...`)
+     - OR have inline prompts defined directly in the handler
+   - [ ] For Module agents (module property is a module code):
+     - Menu handlers SHOULD reference external module files under the module path
+     - Exec paths must start with `{project-root}/_bmad/{module}/...`
+     - Verify referenced files exist under the module directory
+   - [ ] For Simple agents (stand-alone, no sidecar):
+     - Menu handlers MUST NOT have external file links
+     - Menu handlers SHOULD only use relative links within the same file (e.g., `#section-name`)
+     - OR have inline prompts defined directly in the handler
 
 ### 3. Append Findings to Report
 
@@ -57,9 +122,18 @@ Append to `{validationReport}`:
 - [ ] Command names clear and descriptive
 - [ ] Command descriptions specific and actionable
 - [ ] Menu handling logic properly specified
+- [ ] Agent type appropriate menu links verified
+
+**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