Entropyk/_bmad/bmb/workflows/workflow/data/architecture.md

Workflow Architecture

Purpose: Core structural patterns for BMAD workflows.

---

Structure

workflow-folder/
├── workflow.md              # Entry point, configuration
├── steps-c/                 # Create flow steps
│   ├── step-01-init.md
│   ├── step-02-[name].md
│   └── step-N-[name].md
├── steps-e/                 # Edit flow (if needed)
├── steps-v/                 # Validate flow (if needed)
├── data/                    # Shared reference files
└── templates/               # Output templates (if needed)

---

workflow.md Standards

CRITICAL: workflow.md MUST be lean — entry point only.

❌ PROHIBITED:

• Listing all steps (defeats progressive disclosure)
• Detailed step descriptions (steps are self-documenting)
• Validation checklists (belong in steps-v/)
• Implementation details (belong in step files)

✅ REQUIRED:

• Frontmatter: name, description, web_bundle
• Goal: What the workflow accomplishes
• Role: Who the AI embodies
• Meta-context: Architecture background (if pattern demo)
• Core principles (step-file design, JIT loading, etc.)
• Initialization/routing: How to start, which step first

Progressive Disclosure: Users ONLY know about current step. workflow.md routes to first step, each step routes to next. No step lists in workflow.md!

---

Core Principles

1. Micro-File Design

• Each step: ~80-200 lines, focused
• One concept per step
• Self-contained instructions

2. Just-In-Time Loading

• Only current step in memory
• Never load future steps until 'C' selected
• Progressive disclosure = LLM focus

3. Sequential Enforcement

• Steps execute in order
• No skipping, no optimization
• Each step completes before next loads

4. State Tracking

For continuable workflows:

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

Each step appends its name to stepsCompleted before loading next.

---

Execution Flow

Fresh Start:

workflow.md → step-01-init.md → step-02-[name].md → ... → step-N-final.md

Continuation:

workflow.md → step-01-init.md (detects existing) → step-01b-continue.md → [next step]

---

Frontmatter Variables

Standard

workflow_path: '{project-root}/_bmad/[module]/workflows/[name]'
thisStepFile: './step-[N]-[name].md'
nextStepFile: './step-[N+1]-[name].md'
outputFile: '{output_folder}/[output].md'

Module-Specific

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

Rules

• ONLY variables used in step body go in frontmatter
• All file references use {variable} format
• Paths within workflow folder are relative

---

Menu Pattern

### N. Present MENU OPTIONS

Display: "**Select:** [A] [action] [P] [action] [C] Continue"

#### Menu Handling Logic:
- IF A: Execute {task}, then redisplay menu
- IF P: Execute {task}, then redisplay menu
- IF C: Save to {outputFile}, update frontmatter, then load {nextStepFile}
- IF Any other: help user, then redisplay menu

#### EXECUTION RULES:
- ALWAYS halt and wait for user input
- ONLY proceed to next step when user selects 'C'

A/P not needed in: Step 1 (init), validation sequences, simple data gathering

---

Output Pattern

Every step writes BEFORE loading next:

1. Plan-then-build: Steps append to plan.md → build step consumes plan
2. Direct-to-final: Steps append directly to final document

See: output-format-standards.md

---

Critical Rules

• 🛑 NEVER load multiple step files simultaneously
• 📖 ALWAYS read entire step file before execution
• 🚫 NEVER skip steps or optimize the sequence
• 💾 ALWAYS update frontmatter when step completes
• ⏸️ ALWAYS halt at menus and wait for input
• 📋 NEVER create mental todos from future steps