brachnha-insight/_bmad/bmb/workflows/workflow/steps-v/step-02-frontmatter-validation.md

name, description, nextStepFile, targetWorkflowPath, validationReportFile, frontmatterStandards

name	description	nextStepFile	targetWorkflowPath	validationReportFile	frontmatterStandards
step-02-frontmatter-validation	Validate frontmatter compliance across all step files	./step-02b-path-violations.md	{workflow_folder_path}	{workflow_folder_path}/validation-report-{datetime}.md	../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

# 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:

---
# 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

# 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:

# 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.