Entropyk/_bmad/bmb/workflows/workflow/data/frontmatter-standards.md

Frontmatter Standards

Purpose: Variables, paths, and frontmatter rules for workflow steps.

---

Golden Rules

1. Only variables USED in the step may be in frontmatter
2. All file references MUST use {variable} format - no hardcoded paths
3. Paths within workflow folder MUST be relative - NO workflow_path variable allowed

---

Standard Variables

Variable	Example
{project-root}	/Users/user/dev/BMAD-METHOD
{project_name}	my-project
{output_folder}	/Users/user/dev/BMAD-METHOD/output
{user_name}	Brian
{communication_language}	english
{document_output_language}	english

---

Module-Specific Variables

Workflows in a MODULE can access additional variables from its module.yaml.

Example:

bmb_creations_output_folder: '{project-root}/_bmad/bmb-creations'

Standalone workflows: Only have access to standard variables.

---

Frontmatter Structure

Required Fields

---
name: 'step-[N]-[name]'
description: '[what this step does]'
---

File References - ONLY variables used in this step

---
# Step to step (SAME folder) - use ./filename.md
nextStepFile: './step-02-vision.md'

# Step to template (PARENT folder) - use ../filename.md
productBriefTemplate: '../product-brief.template.md'

# Step to data (SUBFOLDER) - use ./data/filename.md
someData: './data/config.csv'

# Output files - use variable
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'

# External references - use {project-root}
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
---

---

Critical Rule: Unused Variables Forbidden

Detection Rule: For EVERY variable in frontmatter, search the step body for {variableName}. If not found, it's a violation.

❌ VIOLATION

---
outputFile: '{output_folder}/output.md'
thisStepFile: './step-01-init.md'      # ❌ NEVER USED
workflowFile: './workflow.md'           # ❌ NEVER USED
---

✅ CORRECT

---
outputFile: '{output_folder}/output.md'
nextStepFile: './step-02-foo.md'
---

---

Path Rules

Type	Format	Example
Step to Step (same folder)	./filename.md	./step-02-vision.md
Step to Template (parent)	../filename.md	../template.md
Step to Subfolder	./subfolder/file.md	./data/config.csv
External References	{project-root}/...	{project-root}/_bmad/core/workflows/...
Output Files	{folder_variable}/...	{planning_artifacts}/output.md

---

❌ FORBIDDEN Patterns

Pattern	Why
workflow_path: '{project-root}/...'	Use relative paths
thisStepFile: './step-XX.md'	Remove unless referenced
workflowFile: './workflow.md'	Remove unless referenced
{workflow_path}/templates/...	Use ../template.md
{workflow_path}/data/...	Use ./data/file.md

---

Variable Naming

Use snake_case with descriptive prefixes:

Suffix	Usage	Example
*_File	File references	outputFile, nextStepFile
*_Task	Task references	advancedElicitationTask
*_Workflow	Workflow references	partyModeWorkflow
*_Template	Templates	productBriefTemplate
*_Data	Data files	dietaryData

---

Defining New Variables

Steps can define NEW variables for future steps.

Step 01 defines:

---
targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
---

Step 02 uses:

---
targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
workflowPlanFile: '{targetWorkflowPath}/plan.md'
---

---

Continuable Workflow Frontmatter

---
stepsCompleted: ['step-01-init', 'step-02-gather', 'step-03-design']
lastStep: 'step-03-design'
lastContinued: '2025-01-02'
date: '2025-01-01'
---

Step tracking: Each step appends its NAME to stepsCompleted.

---

Validation Checklist

For EVERY step frontmatter, verify:

• name present, kebab-case format
• description present
• Extract ALL variable names from frontmatter
• For EACH variable, search body: is {variableName} present?
• If variable NOT in body → ❌ VIOLATION, remove from frontmatter
• All step-to-step paths use ./filename.md format
• All parent-folder paths use ../filename.md format
• All subfolder paths use ./subfolder/filename.md format
• NO {workflow_path} variable exists
• External paths use {project-root} variable
• Module variables only used if workflow belongs to that module