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:**
```markdown
## 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:**
```markdown
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:**
```markdown
"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

```markdown
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

```markdown
---
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**
```markdown
## 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
```

```markdown
## 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:

```markdown
## 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:

```markdown
## 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:

```markdown
# 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:

```markdown
## 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):
```yaml
---
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**:
```markdown
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**:
```markdown
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
```