BMAD-METHOD/src/modules/bmb/docs/workflows/architecture.md

Standalone Workflow Builder Architecture

This document describes the architecture of the standalone workflow builder system - a pure markdown approach to creating structured workflows.

Core Architecture Principles

1. Micro-File Design

Each workflow consists of multiple focused, self-contained files:

workflow-folder/
├── workflow.md              # Main workflow configuration
├── steps/                   # Step instruction files (focused, self-contained)
│   ├── step-01-init.md
│   ├── step-02-profile.md
│   └── step-N-[name].md
├── templates/               # Content templates
│   ├── profile-section.md
│   └── [other-sections].md
└── data/                    # Optional data files
    └── [data-files].csv/.json

2. Just-In-Time (JIT) Loading

• Single File in Memory: Only the current step file is loaded
• No Future Peeking: Step files must not reference future steps
• Sequential Processing: Steps execute in strict order
• On-Demand Loading: Templates load only when needed

3. State Management

• Frontmatter Tracking: Workflow state stored in output document frontmatter
• Progress Array: stepsCompleted tracks completed steps
• Last Step Marker: lastStep indicates where to resume
• Append-Only Building: Documents grow by appending content

4. Execution Model

1. Load workflow.md → Read configuration
2. Execute step-01-init.md → Initialize or detect continuation
3. For each step:
   a. Load step file completely
   b. Execute instructions sequentially
   c. Wait for user input at menu points
   d. Only proceed with 'C' (Continue)
   e. Update document/frontmatter
   f. Load next step

Key Components

Workflow File (workflow.md)

• Purpose: Entry point and configuration
• Content: Role definition, goal, architecture rules
• Action: Points to step-01-init.md

Step Files (step-NN-[name].md)

• Size: Focused and concise (typically 5-10KB)
• Structure: Frontmatter + sequential instructions
• Features: Self-contained rules, menu handling, state updates

Frontmatter Variables

Standard variables in step files:

workflow_path: '{project-root}/{*bmad_folder*}/bmb/reference/workflows/[workflow-name]'
thisStepFile: '{workflow_path}/steps/step-[N]-[name].md'
nextStepFile: '{workflow_path}/steps/step-[N+1]-[name].md'
workflowFile: '{workflow_path}/workflow.md'
outputFile: '{output_folder}/[output-name]-{project_name}.md'

Execution Flow

Fresh Workflow

workflow.md
    ↓
step-01-init.md (creates document)
    ↓
step-02-[name].md
    ↓
step-03-[name].md
    ↓
...
    ↓
step-N-[final].md (completes workflow)

Continuation Workflow

workflow.md
    ↓
step-01-init.md (detects existing document)
    ↓
step-01b-continue.md (analyzes state)
    ↓
step-[appropriate-next].md

Menu System

Standard Menu Pattern

Display: **Select an Option:** [A] [Action] [P] Party Mode [C] Continue

#### Menu Handling Logic:
- IF A: Execute {advancedElicitationTask}
- IF P: Execute {partyModeWorkflow}
- IF C: Save content, update frontmatter, load next step

Menu Rules

• Halt Required: Always wait for user input
• Continue Only: Only proceed with 'C' selection
• State Persistence: Save before loading next step
• Loop Back: Return to menu after other actions

Collaborative Dialogue Model

Not Command-Response

• Facilitator Role: AI guides, user decides
• Equal Partnership: Both parties contribute
• No Assumptions: Don't assume user wants next step
• Explicit Consent: Always ask for input

Example Pattern

AI: "Tell me about your dietary preferences."
User: [provides information]
AI: "Thank you. Now let's discuss your cooking habits."
[Continue conversation]
AI: **Menu Options**

CSV Intelligence (Optional)

Data-Driven Behavior

• Configuration in CSV files
• Dynamic menu options
• Variable substitution
• Conditional logic

Example Structure

variable,type,value,description
cooking_frequency,choice,"daily|weekly|occasionally","How often user cooks"
meal_type,multi,"breakfast|lunch|dinner|snacks","Types of meals to plan"

Best Practices

File Size Limits

• Step Files: Keep focused and reasonably sized (5-10KB typical)
• Templates: Keep focused and reusable
• Workflow File: Keep lean, no implementation details

Sequential Enforcement

• Numbered Steps: Use sequential numbering (1, 2, 3...)
• No Skipping: Each step must complete
• State Updates: Mark completion in frontmatter

Error Prevention

• Path Variables: Use frontmatter variables, never hardcode
• Complete Loading: Always read entire file before execution
• Menu Halts: Never proceed without 'C' selection

Migration from XML

Advantages

• No Dependencies: Pure markdown, no XML parsing
• Human Readable: Files are self-documenting
• Git Friendly: Clean diffs and merges
• Flexible: Easier to modify and extend

Key Differences

XML Workflows	Standalone Workflows
Single large file	Multiple micro-files
Complex structure	Simple sequential steps
Parser required	Any markdown viewer
Rigid format	Flexible organization

Implementation Notes

Critical Rules

• NEVER load multiple step files
• ALWAYS read complete step file first
• NEVER skip steps or optimize
• ALWAYS update frontmatter of the output file when a step is complete
• NEVER proceed without user consent

Success Metrics

• Documents created correctly
• All steps completed sequentially
• User satisfied with collaborative process
• Clean, maintainable file structure

This architecture ensures disciplined, predictable workflow execution while maintaining flexibility for different use cases.