Skip to content

Commit 4731aff

Browse files
Brian MadisonBrian Madison
Brian Madison
authored and
Brian Madison
committed
docs: comprehensive workflow documentation overhaul
- Compress all 15 workflow data files for optimal token usage (18-40% reduction) - Rewrite workflow documentation with accurate technical details from source - Add workflow patterns explanation (structure, intent, session types) - Add workflow variables reference (complete frontmatter guide) - Add skills standard reference with BMad-specific best practices - Add guide for adding workflows to existing modules (epic-level looping) - Run editorial reviews on all 39 docs and apply improvements - Fix all style guide violations (relative paths, admonitions, etc.) - Add real-world examples outside engineering throughout New files: - docs/explanation/workflow-patterns.md - docs/reference/workflow-variables.md - docs/reference/skills-standard.md - docs/how-to/add-workflows-to-modules.md
1 parent 4fd4eb2 commit 4731aff

46 files changed

Lines changed: 2655 additions & 1581 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/explanation/bond-wendy-morgan.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -163,12 +163,16 @@ Their communication styles are optimized for their domain:
163163

164164
Start with the builder that matches your goal:
165165

166-
- **[Create a Custom Agent](docs/tutorials/create-custom-agent.md)** — Work with Bond
167-
- **[Create Your First Workflow](docs/tutorials/create-your-first-workflow.md)** — Work with Wendy
168-
- **[Create Your First Module](docs/tutorials/create-your-first-module.md)** — Work with Morgan
169-
170-
## See Also
171-
172-
- **[Builder Commands Reference](docs/reference/builder-commands.md)** — All builder commands
173-
- **[What Are Agents](docs/explanation/what-are-bmad-agents.md)** — Understanding agents
174-
- **[What Are Workflows](docs/explanation/what-are-workflows.md)** — Understanding workflows
166+
| Builder | Tutorial |
167+
|---------|----------|
168+
| **Bond** | [Create a Custom Agent](/docs/tutorials/create-custom-agent.md) |
169+
| **Wendy** | [Create Your First Workflow](/docs/tutorials/create-your-first-workflow.md) |
170+
| **Morgan** | [Create Your First Module](/docs/tutorials/create-your-first-module.md) |
171+
172+
## Resources
173+
174+
| Resource | Description |
175+
|----------|-------------|
176+
| [Builder Commands](/docs/reference/builder-commands.md) | All builder commands |
177+
| [What Are Agents](/docs/explanation/what-are-bmad-agents.md) | Understanding agents |
178+
| [What Are Workflows](/docs/explanation/what-are-workflows.md) | Understanding workflows |

‎docs/explanation/crafting-agent-principles.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -188,8 +188,10 @@ persona:
188188
- Reflection transforms experience into wisdom
189189
```
190190

191-
## See Also
191+
## Resources
192192

193-
- **[Develop Agent Persona](docs/how-to/develop-agent-persona.md)** - Full four-field persona system
194-
- **[Agent Schema Reference](docs/reference/agent-schema.md)** - Complete field reference
195-
- **[Brainstorming Agent Context](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/brainstorm-context.md)** - Framework for creating memorable agents
193+
| Resource | Description |
194+
|----------|-------------|
195+
| [Develop Agent Persona](/docs/how-to/develop-agent-persona.md) | Full four-field persona system |
196+
| [Agent Schema](/docs/reference/agent-schema.md) | Complete field reference |
197+
| [Brainstorming Agent Context](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/brainstorm-context.md) | Framework for creating memorable agents |

‎docs/explanation/customize-workflows.md‎

Lines changed: 198 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,207 @@
11
---
2-
title: "Workflow Customization Guide"
2+
title: "Workflow Customization"
33
---
44

5-
Customize and optimize workflows with step replacement and hooks.
5+
Workflows support powerful customization patterns through tri-modal architecture, step replacement, and cross-mode integration. This enables workflows to adapt to your specific project needs while maintaining best practices.
66

7-
## Status
7+
## Tri-Modal Workflow Structure
88

9-
:::note[Coming Soon]
10-
Workflow customization is an upcoming capability. This guide will be updated when the feature is available.
9+
Complex workflows use **tri-modal architecture** — separate flows for create, edit, and validate operations:
10+
11+
````
12+
workflow-name/
13+
├── workflow.md # Entry point with mode routing
14+
├── data/ # SHARED standards and reference
15+
├── steps-c/ # Create (self-contained)
16+
│ ├── step-01-init.md
17+
│ └── step-N-complete.md
18+
├── steps-e/ # Edit (self-contained)
19+
│ ├── step-01-assess.md
20+
│ └── step-N-complete.md
21+
└── steps-v/ # Validate (self-contained)
22+
└── step-01-validate.md
23+
````
24+
25+
### Mode Responsibilities
26+
27+
| Mode | Purpose | Key Patterns |
28+
|------|---------|--------------|
29+
| **Create** | Build new entities from scratch | Step-00-conversion for non-compliant input |
30+
| **Edit** | Modify existing compliant entities | Assess compliance first, route to conversion if needed |
31+
| **Validate** | Standalone validation against standards | Auto-proceeds through checks, generates report |
32+
33+
**Key principle:** Each mode is self-contained with no shared step files. The `data/` folder is shared to prevent drift.
34+
35+
:::note[When to Use Tri-Modal]
36+
Use tri-modal for complex workflows requiring quality assurance, long-term maintenance, or non-compliant input handling. Use create-only for simple experimental workflows.
1137
:::
1238

13-
## What to Expect
39+
## Cross-Mode Integration
40+
41+
Workflows support seamless integration between modes:
42+
43+
### Edit to Create (Non-Compliant Detection)
44+
45+
When editing detects a non-compliant workflow:
46+
47+
```yaml
48+
Check workflow compliance:
49+
- Compliant → Continue to edit steps
50+
- Non-compliant → Offer conversion
51+
- IF user accepts: Load steps-c/step-00-conversion.md
52+
```
53+
54+
### Create/Edit to Validation
55+
56+
After creation or editing, workflows can automatically invoke validation:
57+
58+
```yaml
59+
Offer: "Run validation?"
60+
- IF yes: Load ../steps-v/step-01-validate.md
61+
- Validation runs standalone, returns report
62+
- Resume with validation results
63+
```
64+
65+
### Validation to Edit
66+
67+
Validation reports can be consumed by edit mode for fixes:
68+
69+
```yaml
70+
"Fix issues found?"
71+
- IF yes: Load steps-e/step-01-assess.md with validationReport path
72+
```
73+
74+
## Workflow Conversion
75+
76+
Workflows can convert non-compliant input to BMad-compliant format through `step-00-conversion`:
77+
78+
**Conversion process:**
79+
1. Load non-compliant workflow
80+
2. Extract essence and structure
81+
3. Create plan with `conversionFrom` metadata
82+
4. Build compliant workflow
83+
5. Verify coverage of original functionality
84+
85+
**Coverage tracking:**
86+
87+
```yaml
88+
# In create step-10-confirmation
89+
Check workflowPlan metadata:
90+
- IF conversionFrom exists:
91+
- Load original workflow
92+
- Compare each step/instruction
93+
- Report coverage percentage
94+
- ELSE (new workflow):
95+
- Validate all plan requirements implemented
96+
```
97+
98+
## Step Replacement and Extension
99+
100+
### Adding Steps
101+
102+
To add a step to an existing workflow:
103+
104+
1. Create new step file: `step-XX-new-step.md`
105+
2. Update previous step's `nextStepFile` to load the new step
106+
3. Set the new step's `nextStepFile` to continue the sequence
107+
4. Validate with `[VW]` or `validate-workflow`
108+
109+
### Replacing Steps
110+
111+
To replace a step entirely:
112+
113+
1. Create replacement step file with same or new name
114+
2. Update previous step's `nextStepFile` to load replacement
115+
3. Remove or archive old step file
116+
4. Validate the workflow
117+
118+
### Extracting to Data Files
119+
120+
When a step exceeds 200-250 lines, extract content to `/data/` files:
121+
122+
**Good candidates for extraction:**
123+
- Domain-specific reference materials
124+
- Reusable patterns or examples
125+
- Configuration data
126+
- Large lookup tables
127+
128+
## Menu Customization
129+
130+
### Menu Patterns
131+
132+
| Pattern | Use Case | Options |
133+
|---------|----------|---------|
134+
| **Standard A/P/C** | Collaborative content generation | Advanced, Party, Continue |
135+
| **C Only** | Data gathering, simple progression | Continue only |
136+
| **Branching** | User choice determines path | Custom letters (L/R/F) |
137+
| **Auto-proceed** | Init steps, validation sequences | No menu |
138+
139+
### Custom Menu Options
140+
141+
Workflows can define custom menu letters:
142+
143+
```markdown
144+
Display: "**Select:** [L] Load Existing [N] Create New [C] Continue"
145+
146+
#### Menu Handling Logic:
147+
- IF L: Load existing document, then execute {stepForExisting}
148+
- IF N: Create new document, then execute {stepForNew}
149+
- IF C: Save content, check condition, load appropriate step
150+
```
151+
152+
## Template Customization
153+
154+
### Template Types
155+
156+
| Type | Description | Use Case |
157+
|------|-------------|----------|
158+
| **Free-form** | Minimal template, progressive append | Most workflows |
159+
| **Structured** | Single template with placeholders | Consistent formatting needed |
160+
| **Semi-structured** | Core sections + optional additions | Flexible but organized |
161+
| **Strict** | Multiple templates, exact definitions | Compliance, regulated industries |
162+
163+
### Template Syntax
164+
165+
```markdown
166+
{{variable}} # Handlebars style (preferred)
167+
[variable] # Bracket style (also supported)
168+
```
169+
170+
## Output Customization
171+
172+
### Output Patterns
173+
174+
**Plan-then-Build:**
175+
176+
```
177+
Step 1 → Creates plan.md
178+
Step 2 → Appends requirements
179+
Step 3 → Appends design
180+
Step 4 → Build step consumes plan
181+
```
182+
183+
**Direct-to-Final:**
184+
185+
```
186+
Step 1 → Creates final-doc.md
187+
Step 2 → Appends Section 1
188+
Step 3 → Appends Section 2
189+
Step 4 → Polish step optimizes entire document
190+
```
191+
192+
### Final Polish Step
193+
194+
For free-form workflows, include a polish step that:
195+
1. Loads entire document
196+
2. Reviews for flow and coherence
197+
3. Reduces duplication
198+
4. Ensures proper headers
199+
5. Improves transitions
14200
15-
Workflow customization will allow you to:
201+
## Pattern Resources
16202
17-
- **Replace Steps** - Swap out specific workflow steps with custom implementations
18-
- **Add Hooks** - Inject custom behavior before/after workflow steps
19-
- **Extend Workflows** - Create new workflows based on existing ones
20-
- **Override Behavior** - Customize workflow logic for your project's needs
203+
| Resource | Description |
204+
|----------|-------------|
205+
| [Workflow Patterns](/docs/explanation/workflow-patterns.md) | Step types and structure patterns |
206+
| [Workflow Schema](/docs/reference/workflow-schema.md) | Technical reference |
207+
| [Edit Agents and Workflows](/docs/how-to/edit-agents-and-workflows.md) | Step-by-step editing guide |

‎docs/explanation/facilitation-over-generation.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -239,18 +239,18 @@ But the **core creative and analytical work** happens through facilitated discov
239239

240240
### For Individuals
241241
- **Deeper insights** than pure generation. Ideas connect to your actual knowledge.
242-
- **Full ownership** of creative outputs and decisions
243-
- **Skill development** in structured thinking and problem-solving
242+
- **Full ownership** of creative outputs and decisions.
243+
- **Skill development** in structured thinking and problem-solving.
244244
- **More memorable and actionable** results. You understand the "why".
245245

246246
### For Teams
247-
- **Shared creative experience** that builds alignment and trust
248-
- **Aligned understanding** through documented exploration
249-
- **Documented rationale** for future reference and onboarding
250-
- **Stronger buy-in** to outcomes because everyone participated in discovery
247+
- **Shared creative experience** that builds alignment and trust.
248+
- **Aligned understanding** through documented exploration.
249+
- **Documented rationale** for future reference and onboarding.
250+
- **Stronger buy-in** to outcomes because everyone participated in discovery.
251251

252252
### For Implementation
253-
- **Outputs match reality** because they came from your actual constraints
254-
- **Easier iteration** because you understand the reasoning behind choices
255-
- **Confident implementation** because you can defend every decision
256-
- **Reduced rework** because facilitation catches issues early
253+
- **Outputs match reality** because they came from your actual constraints.
254+
- **Easier iteration** because you understand the reasoning behind choices.
255+
- **Confident implementation** because you can defend every decision.
256+
- **Reduced rework** because facilitation catches issues early.

‎docs/explanation/index.md‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,48 +9,54 @@ Create custom agents, workflows, and modules for BMad. This ranges from simple p
99

1010
| Resource | Description |
1111
|----------|-------------|
12-
| **[Create a Custom Agent](docs/tutorials/create-custom-agent.md)** | Build your first AI agent |
13-
| **[Create Your First Workflow](docs/tutorials/create-your-first-workflow.md)** | Design structured workflows |
14-
| **[Create Your First Module](docs/tutorials/create-your-first-module.md)** | Package and publish modules |
12+
| **[Create a Custom Agent](/docs/tutorials/create-custom-agent.md)** | Build your first AI agent |
13+
| **[Create Your First Workflow](/docs/tutorials/create-your-first-workflow.md)** | Design structured workflows |
14+
| **[Create Your First Module](/docs/tutorials/create-your-first-module.md)** | Package and publish modules |
1515

1616
## The Three Builders
1717

1818
| Builder | Creates | Description |
1919
|---------|---------|-------------|
20-
| **[Bond](docs/explanation/bond-wendy-morgan.md)** | Agents | Agent architecture and persona development |
21-
| **[Wendy](docs/explanation/bond-wendy-morgan.md)** | Workflows | Process design and step architecture |
22-
| **[Morgan](docs/explanation/bond-wendy-morgan.md)** | Modules | Full-stack systems design |
20+
| **[Bond](/docs/explanation/bond-wendy-morgan.md)** | Agents | Agent architecture and persona development |
21+
| **[Wendy](/docs/explanation/bond-wendy-morgan.md)** | Workflows | Process design and step architecture |
22+
| **[Morgan](/docs/explanation/bond-wendy-morgan.md)** | Modules | Full-stack systems design |
2323

2424
## Core Concepts
2525

2626
| Topic | Description |
2727
|-------|-------------|
28-
| **[What Are Agents](docs/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities |
29-
| **[What Are Workflows](docs/explanation/what-are-workflows.md)** | Structured step-by-step processes |
30-
| **[What Are Modules](docs/explanation/what-are-modules.md)** | Bundles of agents and workflows |
31-
| **[Custom Content Types](docs/explanation/custom-content-types.md)** | Content categories in BMad |
28+
| **[What Are Agents](/docs/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities |
29+
| **[What Are Workflows](/docs/explanation/what-are-workflows.md)** | Structured step-by-step processes |
30+
| **[What Are Modules](/docs/explanation/what-are-modules.md)** | Bundles of agents and workflows |
31+
| **[Custom Content Types](/docs/explanation/custom-content-types.md)** | Content categories in BMad |
32+
33+
## Workflow Design
34+
35+
| Topic | Description |
36+
|-------|-------------|
37+
| **[Workflow Patterns](/docs/explanation/workflow-patterns.md)** | Structure types, intent spectrum, and execution patterns |
38+
| **[Workflow Customization](/docs/explanation/customize-workflows.md)** | Tri-modal structure, cross-mode integration, and modification |
3239

3340
## Agent Deep Dives
3441

3542
| Topic | Description |
3643
|-------|-------------|
37-
| **[Crafting Agent Principles](docs/explanation/crafting-agent-principles.md)** | Write effective principles that activate expert knowledge |
44+
| **[Crafting Agent Principles](/docs/explanation/crafting-agent-principles.md)** | Write effective principles that activate expert knowledge |
3845

3946
## Architecture & Process
4047

4148
| Topic | Description |
4249
|-------|-------------|
43-
| **[Understanding Module Building](docs/explanation/module-building-architecture.md)** | How module creation works from planning to scaffolding to implementation |
50+
| **[Understanding Module Building](/docs/explanation/module-building-architecture.md)** | How module creation works from planning to scaffolding to implementation |
4451

4552
## Ecosystem Vision
4653

4754
| Topic | Description |
4855
|-------|-------------|
49-
| **[The Module Ecosystem Vision](docs/explanation/module-ecosystem-vision.md)** | How BMad modules create a shared ecosystem of capabilities across every domain |
56+
| **[The Module Ecosystem Vision](/docs/explanation/module-ecosystem-vision.md)** | How BMad modules create a shared ecosystem of capabilities across every domain |
5057

5158
## Advanced Topics
5259

5360
| Topic | Description |
5461
|-------|-------------|
55-
| **[Facilitation vs Generation](docs/explanation/facilitation-over-generation.md)** | Workflow design philosophy |
56-
| **[Customize Workflows](docs/explanation/customize-workflows.md)** | Adapting workflows to your needs |
62+
| **[Facilitation vs Generation](/docs/explanation/facilitation-over-generation.md)** | Workflow design philosophy | |

‎docs/explanation/module-building-architecture.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -292,9 +292,11 @@ wedding-planner/
292292
- [ ] Test each component independently
293293
- [ ] Run `[VM]` to validate complete module
294294

295-
## See Also
296-
297-
- **[Create Your First Module](docs/tutorials/create-your-first-module.md)** — Hands-on tutorial
298-
- **[Discover Your Module Idea](docs/how-to/discover-your-module-idea.md)** — Finding the right idea
299-
- **[What Are Modules](docs/explanation/what-are-modules.md)** — Module concepts
300-
- **[Agent or Module Decision Guide](docs/how-to/agent-or-module-decision.md)** — What to build
295+
## Resources
296+
297+
| Resource | Description |
298+
|----------|-------------|
299+
| [Create Your First Module](/docs/tutorials/create-your-first-module.md) | Hands-on tutorial |
300+
| [Discover Your Module Idea](/docs/how-to/discover-your-module-idea.md) | Finding the right idea |
301+
| [What Are Modules](/docs/explanation/what-are-modules.md) | Module concepts |
302+
| [Agent or Module Decision Guide](/docs/how-to/agent-or-module-decision.md) | What to build |

‎docs/explanation/what-are-bmad-agents.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,4 +153,4 @@ Then use the **Module Builder** instead of a single agent.
153153
154154
## Creating Custom Agents
155155
156-
See the [Agent Creation Tutorial](docs/tutorials/create-custom-agent.md) for step-by-step instructions.
156+
See the [Create a Custom Agent](/docs/tutorials/create-custom-agent.md) tutorial for step-by-step instructions.

‎docs/explanation/what-are-modules.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,4 @@ You can create your own modules for your domain. This includes team-specific wor
3535

3636
## Installing Modules
3737

38-
Choose which modules to install during setup, or add/remove modules later by re-running the installer. See [Installation Guide](docs/how-to/install-custom-modules.md) for details.
38+
Choose which modules to install during setup, or add/remove modules later by re-running the installer. See [Install Custom Modules](docs/how-to/install-custom-modules.md) for details.

0 commit comments

Comments
 (0)