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

package/src/modules/bmb/workflows/workflow/steps-v/step-01-validate.md

@@ -0,0 +1,221 @@
+---
+name: 'step-01-validate'
+description: 'Initialize validation: create report and check file structure & size'
+
+nextStepFile: './step-02-frontmatter-validation.md'
+targetWorkflowPath: '{workflow_folder_path}'
+workflowPlanFile: '{workflow_folder_path}/workflow-plan.md'
+validationReportFile: '{workflow_folder_path}/validation-report-{datetime}.md'
+stepFileRules: '../data/step-file-rules.md'
+---
+
+# Validation Step 1: File Structure & Size
+
+## STEP GOAL:
+
+To create the validation report and check that the workflow has correct file structure and all step files are within size limits.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 DO NOT BE LAZY - LOAD AND REVIEW EVERY FILE
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- ✅ Validation does NOT stop for user input - auto-proceed through all validation steps
+- ⚙️ If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context
+
+### Step-Specific Rules:
+
+- 🎯 Create validation report with header structure using subprocess optimization when available
+- 🚫 DO NOT skip checking any file - DO NOT BE LAZY
+- 💬 Subprocess must either update validation report directly OR return structured findings to parent for aggregation
+- 🚪 This is validation - systematic and thorough
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and check EVERY file in the workflow using subprocess optimization when available - single subprocess for bash/grep operations, separate subprocess per file for size analysis
+- 💾 Subprocesses must either update validation report OR return findings for parent aggregation
+- 📖 Save report before loading next validation step
+- 🚫 DO NOT halt for user input - validation runs to completion
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip or shortcut.
+
+### 1. Create Validation Report
+
+Create {validationReportFile} with header structure:
+
+```markdown
+---
+validationDate: [current date]
+workflowName: {new_workflow_name}
+workflowPath: {workflow_folder_path}
+validationStatus: IN_PROGRESS
+---
+
+# Validation Report: {new_workflow_name}
+
+**Validation Started:** [current date]
+**Validator:** BMAD Workflow Validation System
+**Standards Version:** BMAD Workflow Standards
+
+---
+
+## File Structure & Size
+
+*Validation in progress...*
+
+## Frontmatter Validation
+*Pending...*
+
+## Critical Path Violations
+*Pending...*
+
+## Menu Handling Validation
+*Pending...*
+
+## Step Type Validation
+*Pending...*
+
+## Output Format Validation
+*Pending...*
+
+## Validation Design Check
+*Pending...*
+
+## Instruction Style Check
+*Pending...*
+
+## Collaborative Experience Check
+*Pending...*
+
+## Subprocess Optimization Opportunities
+*Pending...*
+
+## Cohesive Review
+*Pending...*
+
+## Plan Quality Validation
+*Pending...*
+
+## Summary
+*Pending...*
+```
+
+### 2. Load File Structure Standards
+
+Load {stepFileRules} to understand:
+- File size limits (<200 recommended, 250 max)
+- Required folder structure
+- Required files
+
+### 3. Check Folder Structure
+
+**Launch a single subprocess that:**
+
+1. Lists the entire folder structure using bash commands
+2. Verifies all required folders and files exist
+3. Returns structured findings to parent for aggregation
+
+```bash
+# List folder structure
+find {targetWorkflowPath} -type f -name "*.md" | sort
+```
+
+**Expected structure:**
+```
+{targetWorkflowPath}/
+├── workflow.md
+├── steps*/ potentially more than one folder like this (such as steps-v, steps-c - the folder name is not critical but should make sense)
+│   ├── step-01-init.md
+│   ├── step-01b-continue.md (if continuable)
+│   ├── step-02-*.md
+│   └── ...
+├── */ # any other random files - critical will be later ensure its all used - aside from potential documentation for user later.
+├── data/
+│   └── [as needed]
+└── templates/
+    └── [as needed]
+```
+
+**Check:**
+- ✅ workflow.md exists
+- ✅ step files are in a well organized folder
+- ✅ non step reference files are organized in other folders such as data, templates, or others that make sense for the workflow
+- ✅ Folder names make sense
+
+### 4. Check File Sizes
+
+**DO NOT BE LAZY - For EACH step file in steps-c/, launch a subprocess that:**
+
+1. Loads that step file
+2. Counts lines and checks against size limits
+3. Returns structured findings to parent for aggregation
+
+**Limits:**
+- < 200 lines: ✅ Good
+- 200-250 lines: ⚠️ Approaching limit
+- > 250 lines: ❌ Exceeds limit
+
+**Subprocess returns:** File name, line count, status (Good/Approaching limit/Exceeds limit), and any issues found.
+
+**Subprocess must either:**
+- Update validation report directly with findings, OR
+- Return structured findings to parent for aggregation into report
+
+**Document findings in validation report:**
+- List all step files checked with their line counts
+- Note any files approaching or exceeding size limits (<200 recommended, 250 max)
+- Check data and reference files for size issues (large files should be sharded or indexed)
+- Identify specific size violations and recommendations
+
+### 5. Verify File Presence
+
+From the design in {workflowPlanFile}, verify:
+- Every step from design has a corresponding file
+- Step files are numbered sequentially
+- No gaps in numbering
+- Final step exists
+
+### 6. Append Findings to Report
+
+Replace the "## File Structure & Size" section in {validationReportFile} with actual findings:
+
+**Document the following:**
+- Folder structure assessment
+- Required files presence check
+- File size analysis results
+- List of any issues found (missing files, extra files, size violations, naming issues)
+- Overall validation status (PASS/FAIL/WARNINGS)
+
+### 7. Save Report and Auto-Proceed
+
+**CRITICAL:** Save the validation report BEFORE loading next step.
+
+Then immediately load, read entire file, then execute {nextStepFile}.
+
+**Display:**
+"**File Structure & Size validation complete.** Proceeding to Frontmatter Validation..."
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Validation report created with header structure
+- EVERY file checked for structure and size
+- Findings appended to report
+- Report saved before proceeding
+- Next validation step loaded
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking every file
+- Skipping size checks
+- Not saving report before proceeding
+- Halting for user input
+
+**Master Rule:** Validation is systematic and thorough. DO NOT BE LAZY. Check EVERY file. Auto-proceed through all validation steps.

package/src/modules/bmb/workflows/workflow/steps-v/step-01b-structure.md

@@ -0,0 +1,152 @@
+---
+name: 'step-01-validate'
+description: 'Initialize validation: create report and check file structure & size'
+
+nextStepFile: './step-02-frontmatter-validation.md'
+targetWorkflowPath: '{workflow_folder_path}'
+workflowPlanFile: '{workflow_folder_path}/workflow-plan.md'
+validationReportFile: '{workflow_folder_path}/validation-report-{datetime}.md'
+stepFileRules: '../data/step-file-rules.md'
+---
+
+# Validation Step 1: File Structure & Size
+
+## STEP GOAL:
+
+To create the validation report and check that the workflow has correct file structure and all step files are within size limits.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 DO NOT BE LAZY - LOAD AND REVIEW EVERY FILE
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- ✅ Validation does NOT stop for user input - auto-proceed through all validation steps
+- ⚙️ If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context
+
+### Step-Specific Rules:
+
+- 🎯 Create validation report with header structure using subprocess optimization when available
+- 🚫 DO NOT skip checking any file - DO NOT BE LAZY
+- 💬 Subprocess must either update validation report directly OR return structured findings to parent for aggregation
+- 🚪 This is validation - systematic and thorough
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and check EVERY file in the workflow using subprocess optimization when available - single subprocess for bash/grep operations, separate subprocess per file for size analysis
+- 💾 Subprocesses must either update validation report OR return findings for parent aggregation
+- 📖 Save report before loading next validation step
+- 🚫 DO NOT halt for user input - validation runs to completion
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip or shortcut.
+
+### 1. Check Folder Structure
+
+**Launch a single subprocess that will do all of the following for items:**
+
+1.  Load {stepFileRules} to understand:
+- File size limits (<200 recommended, 250 max)
+- Required folder structure
+- Required files
+2. Lists the entire folder structure using bash commands
+3. Verifies all required folders and files exist
+4. Returns structured findings to parent for aggregation
+
+```bash
+# List folder structure
+find {targetWorkflowPath} -type f -name "*.md" | sort
+```
+
+**Expected structure:**
+```
+{targetWorkflowPath}/
+├── workflow.md
+├── steps*/ potentially more than one folder like this (such as steps-v, steps-c - the folder name is not critical but should make sense)
+│   ├── step-01-init.md
+│   ├── step-01b-continue.md (if continuable)
+│   ├── step-02-*.md
+│   └── ...
+├── */ # any other random files - critical will be later ensure its all used - aside from potential documentation for user later.
+├── data/
+│   └── [as needed]
+└── templates/
+    └── [as needed]
+```
+
+**Check:**
+- ✅ workflow.md exists
+- ✅ step files are in a well organized folder
+- ✅ non step reference files are organized in other folders such as data, templates, or others that make sense for the workflow
+- ✅ Folder names make sense
+
+### 4. Check File Sizes
+
+**DO NOT BE LAZY - For EACH step file in steps-c/, launch a subprocess that:**
+
+1. Loads that step file
+2. Counts lines and checks against size limits
+3. Returns structured findings to parent for aggregation
+
+**Limits:**
+- < 200 lines: ✅ Good
+- 200-300 lines: ⚠️ Approaching limit
+- > 300 lines: ❌ Exceeds limit
+
+**Subprocess returns:** File name, line count, status (Good/Approaching limit/Exceeds limit), and any issues found.
+
+**Subprocess must either:**
+- Update validation report directly with findings, OR
+- Return structured findings to parent for aggregation into report
+
+**Document findings in validation report:**
+- List all step files checked with their line counts
+- Note any files approaching or exceeding size limits (<200 recommended, 250 max)
+- Check data and reference files for size issues (large files should be sharded or indexed)
+- Identify specific size violations and recommendations
+
+### 5. Verify File Presence
+
+From the design in {workflowPlanFile}, verify:
+- Every step from design has a corresponding file
+- Step files are numbered sequentially
+- No gaps in numbering
+- Final step exists
+
+### 6. Document all findings in a report
+
+**Document the following:**
+- Folder structure assessment
+- Required files presence check
+- File size analysis results
+- List of any issues found (missing files, extra files, size violations, naming issues)
+- Overall validation status (PASS/FAIL/WARNINGS)
+
+### 7. Save Report
+
+**CRITICAL:** Save the validation report BEFORE COMPLETING THIS STEP
+
+**Display:** "**File Structure & Size validation complete.**"
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Validation report created with header structure
+- EVERY file checked for structure and size
+- Findings appended to report
+- Report saved before proceeding
+- Next validation step loaded
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking every file
+- Skipping size checks
+- Not saving report before proceeding
+- Halting for user input
+
+**Master Rule:** Validation is systematic and thorough. DO NOT BE LAZY. Check EVERY file. Auto-proceed through all validation steps.

package/src/modules/bmb/workflows/workflow/steps-v/step-02-frontmatter-validation.md

@@ -0,0 +1,199 @@
+---
+name: 'step-02-frontmatter-validation'
+description: 'Validate frontmatter compliance across all step files'
+
+nextStepFile: './step-02b-path-violations.md'
+targetWorkflowPath: '{workflow_folder_path}'
+validationReportFile: '{workflow_folder_path}/validation-report-{datetime}.md'
+frontmatterStandards: '../data/frontmatter-standards.md'
+---
+
+# Validation Step 2: Frontmatter Validation
+
+## STEP GOAL:
+
+To validate that EVERY step file's frontmatter follows the frontmatter standards - correct variables, proper relative paths, NO unused variables.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 DO NOT BE LAZY - VALIDATE EVERY FILE'S FRONTMATTER
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- ✅ Validation does NOT stop for user input - auto-proceed through all validation steps
+- ⚙️ If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+
+### Step-Specific Rules:
+
+- 🎯 Validate EVERY step file's frontmatter using subprocess optimization - each file in its own subprocess
+- 🚫 DO NOT skip any files or checks - DO NOT BE LAZY
+- 💬 Subprocess must either update validation report directly OR return structured findings to parent for aggregation
+- 🚪 This is validation - systematic and thorough using per-file deep analysis (Pattern 2)
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load frontmatter standards first, then validate each file in its own subprocess for deep analysis
+- 💾 Subprocesses must either update validation report OR return findings for parent aggregation
+- 📖 Aggregate all findings into validation report before loading next step
+- 🚫 DO NOT halt for user input - validation runs to completion
+
+## CONTEXT BOUNDARIES:
+
+- All step files in the workflow must be validated
+- Load {frontmatterStandards} for validation criteria
+- Check for: unused variables, non-relative paths, missing required fields, forbidden patterns
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip or shortcut.
+
+### 1. Load Frontmatter Standards
+
+Load {frontmatterStandards} to understand validation criteria.
+
+**Key Rules:**
+1. Only variables USED in the step may be in frontmatter
+2. All file references MUST use `{variable}` format
+3. Paths within workflow folder MUST be relative - NO `workflow_path` allowed
+
+**Forbidden Patterns:**
+- `workflow_path: '...'` - use relative paths instead
+- `thisStepFile: '...'` - remove unless actually referenced in body
+- `workflowFile: '...'` - remove unless actually referenced in body
+- `./...` - use `./step-XX.md`
+- `{workflow_path}/templates/...` - use `../template.md`
+
+### 2. Validate EVERY Step File - Systematic Algorithm with Subprocess Optimization
+
+**DO NOT BE LAZY - For EACH step file, launch a subprocess that:**
+
+1. Loads that file
+2. Loads {frontmatterStandards} to understand validation criteria
+3. Performs all frontmatter validation checks on that file (extract variables, check usage, validate paths)
+4. **EITHER** updates the validation report directly with its findings
+5. **OR** returns structured findings to parent for aggregation
+
+**SUBPROCESS ANALYSIS PATTERN:**
+
+For each file, the subprocess performs the following deep analysis:
+
+#### Step 2.1: Extract Frontmatter Variables
+
+```python
+# Algorithm to extract variables from frontmatter:
+1. Find content between first `---` and second `---`
+2. For each line, extract key before `:`
+3. Skip `name`, `description`, and comment lines starting with `#`
+4. Collect all variable names
+```
+
+Example frontmatter:
+```yaml
+---
+# File References
+nextStepFile: './step-02-vision.md'
+outputFile: '{planning_artifacts}/product-brief-{{project_name}}.md'
+workflow_path: '{project-root}/...'  # ❌ FORBIDDEN
+thisStepFile: './step-01-init.md'     # ❌ Likely unused
+---
+```
+
+Variables extracted: `nextStepFile`, `outputFile`, `workflow_path`, `thisStepFile`
+
+#### Step 2.2: Check Each Variable Is Used
+
+```python
+# Algorithm to check variable usage:
+for each variable in extracted_variables:
+    search_body = "{variableName}"  # with curly braces
+    if search_body NOT found in step body (after frontmatter):
+        MARK_AS_UNUSED(variable)
+```
+
+**Example:**
+- Variable `nextStepFile`: Search body for `{nextStepFile}` → Found in line 166 ✅
+- Variable `thisStepFile`: Search body for `{thisStepFile}` → Not found ❌ VIOLATION
+
+#### Step 2.3: Check Path Formats
+
+For each variable containing a file path:
+
+```python
+# Algorithm to validate paths:
+if path contains "{workflow_path}":
+    MARK_AS_VIOLATION("workflow_path is forbidden - use relative paths")
+
+if path is to another step file:
+    if not path.startswith("./step-"):
+        MARK_AS_VIOLATION("Step-to-step paths must be ./filename.md")
+
+if path is to parent folder template:
+    if not path.startswith("../"):
+        MARK_AS_VIOLATION("Parent folder paths must be ../filename.md")
+
+if path contains "{project-root}" and is internal workflow reference:
+    MARK_AS_VIOLATION("Internal paths must be relative, not project-root")
+```
+
+**RETURN FORMAT:**
+
+Subprocess returns file name, frontmatter compliance status, unused variables found, path violations, and overall status (PASS/FAIL). Include specific variable names and violation details for documentation.
+
+Check ALL files systematically. Return findings for compilation and appendage to validation report.
+
+### 3. Aggregate Findings and Document Results
+
+Document frontmatter validation results in the validation report showing:
+- Which files were checked
+- Frontmatter compliance status for each file
+- Unused variables found in each file
+- Path violations detected
+- Overall pass/fail status for each file
+
+### 4. List All Violations
+
+Document all violations found in the validation report, including:
+- Specific files with violations
+- Unused variable names and why they're unused
+- Forbidden patterns detected with explanation
+- Path format violations with details
+- Files that passed all checks
+
+### 5. Append to Report
+
+Update {validationReportFile} - replace "## Frontmatter Validation *Pending...*" with actual findings.
+
+### 6. Save Report and Auto-Proceed
+
+**CRITICAL:** Save the validation report BEFORE loading next step.
+
+Then immediately load, read entire file, then execute {nextStepFile}.
+
+**Display:**
+"**Frontmatter validation complete.** Proceeding to Menu Handling Validation..."
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- EVERY step file validated using subprocess optimization (Pattern 2: per-file deep analysis)
+- Each subprocess validates frontmatter, checks variable usage, validates paths
+- Structured findings returned to parent OR report updated directly by subprocesses
+- All violations documented with specific variable names
+- Findings aggregated into validation report
+- Report saved before proceeding
+- Next validation step loaded
+
+### ❌ SYSTEM FAILURE:
+
+- Not validating every file using subprocess optimization
+- Not systematically checking each variable for usage in subprocess
+- Missing forbidden pattern detection
+- Not documenting violations with specific details
+- Not returning structured findings OR updating report from subprocess
+- Not saving report before proceeding
+
+**Master Rule:** Validation is systematic and thorough using subprocess optimization. DO NOT BE LAZY. For EACH file, launch a subprocess that validates frontmatter, checks variable usage, validates paths, and returns findings. Auto-proceed through all validation steps.