bi-agents/.claude/skills/bmad-workflow-builder/references/complex-workflow-patterns.md

BMad Module Workflows

Advanced patterns for BMad module workflows — long-running, multi-stage processes with progressive disclosure, config integration, and compaction survival.

---

Workflow Persona: Facilitator Model

BMad workflows treat the human operator as the expert. The agent's role is facilitator, not replacement.

Principles:

• Ask clarifying questions when requirements are ambiguous
• Present options with trade-offs, don't assume preferences
• Validate decisions before executing irreversible actions
• The operator knows their domain; the workflow knows the process

Example voice:

## Discovery
I found 3 API endpoints that could handle this. Which approach fits your use case?

**Option A**: POST /bulk-import — Faster, but no validation until complete
**Option B**: POST /validate + POST /import — Slower, but catches errors early
**Option C**: Streaming import — Best of both, requires backend support

Which would you prefer?

---

Config Reading and Integration

Workflows MUST read config values using the bmad-init skill.

Config Loading Pattern

Invoke the skill with parameters:

Use bmad-init skill:
- module: {bmad-module-code}
- vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,{output-location-variable}:{default-output-path}

The skill returns JSON with config values. Store in memory as {var_name} for use in prompts.

Required Core Variables

Every module workflow MUST load these core variables:

• user_name:BMad
• communication_language:English
• output_folder:{project-root}/_bmad-output

Conditionally include:

• document_output_language:English — ONLY if workflow creates documents (check capability output-location field)
• Output location variable from capability output-location — ONLY if specified in metadata

Example for BMB workflow (creates documents, has output var):

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/

Example for analysis workflow (no documents, has output var):

vars: user_name:BMad,communication_language:English,output_folder:{project-root}/_bmad-output,analysis_output_folder:{project-root}/_bmad-output/analysis/

Example for processing workflow (no documents, no output var):

vars: user_name:BMad,communication_language:English,output_folder:{project-root}/_bmad-output

Using Config Values in Prompts

Every prompt file MUST start with:

Language: {communication_language}
Output Language: {document_output_language}  ← ONLY if workflow creates documents
Output Location: {output-variable}           ← ONLY if capability output-location is defined

Use throughout prompts:

"Creating documentation in {document_output_language}..."  ← ONLY if creates documents
"Writing output to {bmad_builder_output_folder}/report.md" ← ONLY if has output var
"Connecting to API at {my_module_api_url}..."

---

{project_root} Pattern for Portable Paths

Artifacts MUST use {project_root} for paths so the skill works regardless of install location (user directory or project).

Path Pattern

{project_root}/docs/foo.md         → Correct (portable)
./docs/foo.md                      → Wrong (breaks if skill in user dir)
~/my-project/docs/foo.md           → Wrong (not portable)
/bizarre/absolute/path/foo.md      → Wrong (not portable)

Writing Artifacts

1. Create the artifact at {project_root}/docs/architecture.md
2. Update {project_root}/CHANGELOG.md with entry
3. Copy template to {project_root}/.bmad-cache/template.md

{project_root} Resolution

{project_root} is automatically resolved to the directory where the workflow was launched. This ensures:

• Skills work whether installed globally or per-project
• Multiple projects can use the same skill without conflict
• Artifact paths are always relative to the active project

---

Long-Running Workflows: Compaction Survival

Workflows that run long (many steps, large context) may trigger context compaction. Critical state MUST be preserved in output files.

The Document-Itself Pattern

The output document is the cache. Write directly to the file you're creating, updating it progressively as the workflow advances.

The document stores both content and context:

• YAML front matter — paths to input files used (for recovery after compaction)
• Draft sections — progressive content as it's built
• Status marker — which stage is complete (for resumption)

This avoids:

• File collisions when working on multiple PRDs/research projects simultaneously
• Extra _bmad-cache folder overhead
• State synchronization complexity

Draft Document Structure

---
title: "Analysis: Research Topic"
status: "analysis"  # discovery | planning | analysis | synthesis | polish
inputs:
  - "{project_root}/docs/brief.md"
  - "{project_root}/data/sources.json"
created: "2025-03-02T10:00:00Z"
updated: "2025-03-02T11:30:00Z"
---

# Analysis: Research Topic

## Discovery
[content from stage 1...]

## Analysis
[content from stage 2...]

---

*Last updated: Stage 2 complete*

Input Tracking Pattern

Stage 1: Initialize document with inputs

## Stage 1: Discovery
1. Gather sources and identify input files
2. Create output document with YAML front matter:
```yaml
---
title: "{document_title}"
status: "discovery"
inputs:
  - "{relative_path_to_input_1}"
  - "{relative_path_to_input_2}"
created: "{timestamp}"
updated: "{timestamp}"
---

3. Write discovery content to document
4. Present summary to user

**Stage 2+: Reload context if compacted**
```markdown
## Stage Start: Analysis
1. Read {output_doc_path}
2. Parse YAML front matter for `inputs` list
3. Re-read each input file to restore context
4. Verify status indicates previous stage complete
5. Proceed with analysis, updating document in place

## Stage 1: Research
1. Gather sources
2. **Write findings to {project_root}/docs/research-topic.md**
3. Present summary to user

## Stage 2: Analysis
1. **Read {project_root}/docs/research-topic.md** (survives compaction)
2. Analyze patterns
3. **Append/insert analysis into the same file**

## Stage 3: Synthesis
1. Read the growing document
2. Synthesize into final structure
3. **Update the same file in place**

## Stage 4: Final Polish
1. Spawn a subagent to polish the completed document:
   - Cohesion check
   - Redundancy removal
   - Contradiction detection and fixes
   - Add TOC if long document
2. Write final version to {project_root}/docs/research-topic.md

When to Use This Pattern

Guided flows with long documents: Always write updates to the document itself at each stage.

Yolo flows with multiple turns: If the workflow takes multiple conversational turns, write to the output file progressively.

Single-pass yolo: Can wait to write final output if the entire response fits in one turn.

Progressive Document Structure

Each stage appends to or restructures the document:

## Initial Stage
# Document Title

## Section 1: Initial Research
[content...]

---

## Second Stage (reads file, appends)
# Document Title

## Section 1: Initial Research
[existing content...]

## Section 2: Analysis
[new content...]

---

## Third Stage (reads file, restructures)
# Document Title

## Executive Summary
[ synthesized from sections ]

## Background
[ section 1 content ]

## Analysis
[ section 2 content ]

Final Polish Subagent

At workflow completion, spawn a subagent for final quality pass:

## Final Polish

Launch a general-purpose agent with:

Task: Polish {output_file_path}

Actions:

1. Check cohesion - do sections flow logically?
2. Find and remove redundancy
3. Detect contradictions and fix them
4. If document is >5 sections, add a TOC at the top
5. Ensure consistent formatting and tone

Write the polished version back to the same file.

### Compaction Recovery Pattern

If context is compacted mid-workflow:
```markdown
## Recovery Check
1. Read {output_doc_path}
2. Parse YAML front matter:
   - Check `status` for current stage
   - Read `inputs` list to restore context
3. Re-read all input files from `inputs`
4. Resume from next stage based on status

When NOT to Use This Pattern

• Short, single-turn outputs: Just write once at the end
• Purely conversational workflows: No persistent document needed
• Multiple independent artifacts: Each gets its own file; write each directly

---

Sequential Progressive Disclosure

Place numbered prompt files at the skill root when:

• Multi-phase workflow with ordered questions
• Input of one phase affects the next
• User requires specific sequence
• Workflow is long-running and stages shouldn't be visible upfront

Prompt File Structure

my-workflow/
├── SKILL.md
├── 01-discovery.md           # Stage 1: Gather requirements, start output doc
├── 02-planning.md            # Stage 2: Create plan (uses discovery output)
├── 03-execution.md           # Stage 3: Execute (uses plan, updates output)
├── 04-review.md              # Stage 4: Review and polish final output
└── references/
    └── stage-templates.md

Progression Conditions

Each prompt file specifies when to proceed:

# 02-planning.md

## Prerequisites
- Discovery complete (output doc exists and has discovery section)
- User approved scope (user confirmed: proceed)

## On Activation
1. Read the output doc to get discovery context
2. Generate plan based on discovered requirements
3. **Append/insert plan section into the output doc**
4. Present plan summary to user

## Progression Condition
Proceed to execution stage when user confirms: "Proceed with plan" OR user provides modifications

## On User Approval
Route to 03-execution.md

SKILL.md Routes to Prompt Files

Main SKILL.md is minimal — just routing logic:

## Workflow Entry

1. Load config from {project-root}/_bmad/bmb/config.yaml

2. Check if workflow in progress:
   - If output doc exists (user specifies path or we prompt):
     - Read doc to determine current stage
     - Resume from last completed section
   - Else: Start at 01-discovery.md

3. Route to appropriate prompt file based on stage

When NOT to Use Separate Prompt Files

Keep inline in SKILL.md when:

• Simple skill (session-long context fits)
• Well-known domain tool usage
• Single-purpose utility
• All stages are independent or can be visible upfront

---

Module Metadata Reference

BMad module workflows require extended frontmatter metadata. See references/metadata-reference.md for the metadata template, field explanations, and comparisons between standalone skills and module workflows.

---

Workflow Architecture Checklist

Before finalizing a BMad module workflow, verify:

• Facilitator persona: Does the workflow treat the operator as expert?
• Config integration: Are language, output locations, and module props read and used?
• Portable paths: All artifact paths use {project_root}?
• Continuous output: Does each stage write to the output document directly (survives compaction)?
• Document-as-cache: Output doc has YAML front matter with status and inputs for recovery?
• Input tracking: Does front matter list relative paths to all input files used?
• Final polish: Does workflow include a subagent polish step at the end?
• Progressive disclosure: Are stages in prompt files at root with clear progression conditions?
• Metadata complete: All bmad-* fields present and accurate?
• Recovery pattern: Can the workflow resume by reading the output doc front matter?

---

Example: Complete BMad Workflow Skeleton

my-module-workflow/
├── SKILL.md                              # Routing + entry logic
├── 01-discovery.md                       # Gather requirements
├── 02-planning.md                        # Create plan
├── 03-execution.md                       # Execute
├── 04-review.md                          # Review results
├── references/
│   └── templates.md                      # Stage templates
└── scripts/
    └── validator.sh                      # Output validation

SKILL.md (minimal routing):

---
name: bmad-mymodule-workflow
description: Complex multi-stage workflow for my module. Use when user requests to 'run my module workflow' or 'create analysis report'.
---

## Workflow Entry

1. Use bmad-init skill (module: mm) — loads user_name, communication_language, document_output_language, output_folder, my_output_folder

2. Ask user for output document path (or suggest {my_output_folder}/analysis-{timestamp}.md)

3. Check if doc exists:
   - If yes: read to determine current stage, resume
   - If no: start at 01-discovery.md

4. Route to appropriate prompt file based on stage

01-discovery.md:

Language: {communication_language}
Output Language: {document_output_language}
Output Location: {my_output_folder}

## Discovery

1. What are we building?
2. What are the constraints?
3. What input files should we reference?

**Create**: {output_doc_path} with:
```markdown
---
title: "Analysis: {topic}"
status: "discovery"
inputs:
  - "{relative_path_to_input_1}"
  - "{relative_path_to_input_2}"
created: "{timestamp}"
updated: "{timestamp}"
---

# Analysis: {topic}

## Discovery
[findings...]

---

*Status: Stage 1 complete*

Progression

When complete → 02-planning.md

**02-planning.md**:
```markdown
Language: {communication_language}
Output Language: {document_output_language}

## Planning Start

1. Read {output_doc_path}
2. Parse YAML front matter — reload all `inputs` to restore context
3. Verify status is "discovery"

## Planning
1. Generate plan based on discovery
2. Update {output_doc_path}:
   - Update status to "planning"
   - Append planning section

## Progression
When complete → 03-execution.md

04-review.md:

Language: {communication_language}
Output Language: {document_output_language}

## Final Polish

1. Read the complete output doc
2. Launch a general-purpose agent:

Task: Polish {output_doc_path}

Actions:

1. Check cohesion - do sections flow logically?
2. Find and remove redundancy
3. Detect contradictions and fix them
4. If document is >5 sections, add a TOC at the top
5. Ensure consistent formatting and tone
6. Update YAML status to "complete" and remove draft markers

Write the polished version back to the same file.

## Progression
When complete → present final result to user