4.3 KiB
BMad Module Workflows
Advanced patterns for BMad module workflows — long-running, multi-stage processes with progressive disclosure, config integration, and compaction survival.
Workflow Persona
BMad workflows treat the human operator as the expert. The agent facilitates — asks clarifying questions, presents options with trade-offs, validates before irreversible actions. The operator knows their domain; the workflow knows the process.
Config Reading and Integration
Workflows read config from {project-root}/_bmad/config.yaml and config.user.yaml.
Config Loading Pattern
Module-based skills — load with fallback and setup skill awareness:
Load config from {project-root}/_bmad/config.yaml ({module-code} section) and config.user.yaml.
If missing: inform user that {module-setup-skill} is available, continue with sensible defaults.
Standalone skills — load best-effort:
Load config from {project-root}/_bmad/config.yaml and config.user.yaml if available.
If missing: continue with defaults — no mention of setup skill.
Required Core Variables
Load core config (user preferences, language, output locations) with sensible defaults. If the workflow creates documents, include document output language.
Example config line for a document-producing workflow:
vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,bmad_builder_output_folder:{project-root}/bmad-builder-creations/
Config variables used directly in prompts — they already contain {project-root} in resolved values.
Long-Running Workflows: Compaction Survival
Workflows that run long may trigger context compaction. Critical state MUST survive in output files.
The Document-Itself Pattern
The output document is the cache. Write directly to the file you're creating, updating progressively. The document stores both content and context:
- YAML front matter — paths to input files, current status
- Draft sections — progressive content as it's built
- Status marker — which stage is complete
Each stage after the first reads the output document to recover context. If compacted, re-read input files listed in the YAML front matter.
---
title: 'Analysis: Research Topic'
status: 'analysis'
inputs:
- '{project_root}/docs/brief.md'
created: '2025-03-02T10:00:00Z'
updated: '2025-03-02T11:30:00Z'
---
When to use: Guided flows with long documents, yolo flows with multiple turns. Single-pass yolo can wait to write final output.
When NOT to use: Short single-turn outputs, purely conversational workflows, multiple independent artifacts (each gets its own file).
Sequential Progressive Disclosure
Use numbered prompt files at the skill root when:
- Multi-phase workflow with ordered stages
- Input of one phase affects the next
- Workflow is long-running and stages shouldn't be visible upfront
Structure
my-workflow/
├── SKILL.md # Routing + entry logic (minimal)
├── references/
│ ├── 01-discovery.md # Stage 1
│ ├── 02-planning.md # Stage 2
│ ├── 03-execution.md # Stage 3
│ └── templates.md # Supporting reference
└── scripts/
└── validator.sh
Each stage prompt specifies prerequisites, progression conditions, and next destination. SKILL.md is minimal routing logic.
Keep inline in SKILL.md when: Simple skill, well-known domain, single-purpose utility, all stages independent.
Module Metadata Reference
BMad module workflows require extended frontmatter metadata. See ./metadata-reference.md for the metadata template and field explanations.
Workflow Architecture Checklist
Before finalizing a BMad module workflow, verify:
- Facilitator persona — treats operator as expert?
- Config integration — language, output locations read and used?
- Portable paths — artifacts use
{project_root}? - Compaction survival — each stage writes to output document?
- Document-as-cache — YAML front matter with status and inputs?
- Progressive disclosure — stages in
references/with progression conditions? - Final polish — subagent polish step at the end?
- Recovery — can resume by reading output doc front matter?