mirror of
https://github.com/R0m1k3/xtremflow.git
synced 2026-10-12 09:46:21 +02:00
470 lines
12 KiB
Markdown
470 lines
12 KiB
Markdown
# BMAD Step File Guidelines
|
|
|
|
**Version:** 1.0
|
|
**Module:** bmb (BMAD Builder)
|
|
**Purpose:** Definitive guide for creating BMAD workflow step files
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines.
|
|
|
|
---
|
|
|
|
## File Size Optimization
|
|
|
|
**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum).
|
|
|
|
If a step exceeds this limit:
|
|
- Consider splitting into multiple steps
|
|
- Extract content to `/data/` reference files
|
|
- Optimize verbose explanations
|
|
|
|
---
|
|
|
|
## Required Frontmatter Structure
|
|
|
|
CRITICAL: Frontmatter should only have items that are used in the step file!
|
|
|
|
```yaml
|
|
---
|
|
name: 'step-2-foo.md'
|
|
description: 'Brief description of what this step accomplishes'
|
|
|
|
# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file!
|
|
outputFile: {bmb_creations_output_folder}/output-file-name.md
|
|
nextStepFile: './step-3-bar.md'
|
|
|
|
# Task References (as needed)
|
|
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
|
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
|
# ... other task-specific references
|
|
---
|
|
```
|
|
|
|
### Frontmatter Field Descriptions
|
|
|
|
| Field | Required | Description |
|
|
| --------------- | --------- | --------------------------------- |
|
|
| `name` | Yes | Step identifier (kebab-case) |
|
|
| `description` | Yes | One-line summary of step purpose |
|
|
| `outputFile` | Yes | Where results are documented |
|
|
| Task references | As needed | Paths to external workflows/tasks |
|
|
|
|
---
|
|
|
|
## Document Structure
|
|
|
|
### 1. Title
|
|
|
|
```markdown
|
|
# Step X: [Step Name]
|
|
```
|
|
|
|
### 2. STEP GOAL
|
|
|
|
```markdown
|
|
## STEP GOAL:
|
|
|
|
[Single sentence stating what this step accomplishes]
|
|
```
|
|
|
|
### 3. Role Reinforcement
|
|
|
|
```markdown
|
|
### Role Reinforcement:
|
|
|
|
- ✅ You are a [specific role] who [does what]
|
|
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
|
|
- ✅ We engage in collaborative dialogue, not command-response
|
|
- ✅ You bring [your expertise], user brings [their expertise], together we [achieve goal]
|
|
- ✅ Maintain [tone/approach] throughout
|
|
```
|
|
|
|
### 4. Language Preference
|
|
|
|
```markdown
|
|
### Language Preference:
|
|
The user has chosen to communicate in the **{language}** language.
|
|
You MUST respond in **{language}** throughout this step.
|
|
```
|
|
|
|
**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it.
|
|
|
|
### 5. Step-Specific Rules
|
|
|
|
```markdown
|
|
### Step-Specific Rules:
|
|
|
|
- 🎯 Focus only on [specific scope]
|
|
- 🚫 FORBIDDEN to [prohibited action]
|
|
- 💬 Approach: [how to engage]
|
|
- 📋 Ensure [specific outcome]
|
|
```
|
|
|
|
### 6. EXECUTION PROTOCOLS
|
|
|
|
```markdown
|
|
## EXECUTION PROTOCOLS:
|
|
|
|
- [What to do - use verbs]
|
|
- [Another action]
|
|
- 🚫 FORBIDDEN to [prohibited action]
|
|
```
|
|
|
|
### 7. CONTEXT BOUNDARIES
|
|
|
|
```markdown
|
|
## CONTEXT BOUNDARIES:
|
|
|
|
- Available context: [what's available]
|
|
- Focus: [what to focus on]
|
|
- Limits: [boundaries]
|
|
- Dependencies: [what this step depends on]
|
|
```
|
|
|
|
### 8. Sequence of Instructions
|
|
|
|
```markdown
|
|
## Sequence of Instructions:
|
|
|
|
### 1. [First Action]
|
|
|
|
**[Action Description]**
|
|
|
|
### 2. [Second Action]
|
|
|
|
...
|
|
```
|
|
|
|
### 9. MENU OPTIONS
|
|
|
|
```markdown
|
|
### X. Present MENU OPTIONS
|
|
|
|
Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]"
|
|
|
|
#### Menu Handling Logic:
|
|
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
|
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
|
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
|
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
|
|
|
|
#### EXECUTION RULES:
|
|
- ALWAYS halt and wait for user input after presenting menu
|
|
- ONLY proceed to next step when user selects 'C'
|
|
- After other menu items execution, return to this menu
|
|
- User can chat or ask questions - always respond and then end with display again of the menu options
|
|
|
|
## CRITICAL STEP COMPLETION NOTE
|
|
ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`...
|
|
```
|
|
|
|
### 10. SYSTEM SUCCESS/FAILURE METRICS
|
|
|
|
```markdown
|
|
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
|
|
|
### ✅ SUCCESS:
|
|
- [Success criterion 1]
|
|
- [Success criterion 2]
|
|
- ...
|
|
|
|
### ❌ SYSTEM FAILURE:
|
|
- [Failure criterion 1]
|
|
- [Failure criterion 2]
|
|
- ...
|
|
|
|
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
|
```
|
|
|
|
---
|
|
|
|
## A/P/C Menu Convention
|
|
|
|
BMAD workflows use a fixed menu structure:
|
|
|
|
| Option | Meaning | Behavior |
|
|
| ------ | -------------------- | ---------------------------------------------------- |
|
|
| **A** | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu |
|
|
| **P** | Party Mode | Execute partyModeWorkflow, then redisplay menu |
|
|
| **C** | Continue/Accept | Save output, update frontmatter, load nextStepFile |
|
|
| Other | Custom | Defined per step (e.g., F = Fix, X = Exit) |
|
|
|
|
**Rules:**
|
|
- A and P MUST always be present
|
|
- C MUST be present except in final step (use X or similar for exit)
|
|
- After A/P → redisplay menu
|
|
- After C → proceed to next step
|
|
- Custom letters can be used for step-specific options
|
|
|
|
---
|
|
|
|
## Progressive Disclosure
|
|
|
|
**Core Principle:** Each step only knows about its immediate next step.
|
|
|
|
### Implementation
|
|
|
|
1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C]
|
|
|
|
2. **Mode-aware routing** (for shared steps):
|
|
```markdown
|
|
## MODE-AWARE ROUTING:
|
|
### If entered from CREATE mode:
|
|
Load ./s-next-step.md
|
|
|
|
### If entered from EDIT mode:
|
|
Load ./e-next-step.md
|
|
|
|
### If entered from VALIDATE mode:
|
|
Load ./v-next-step.md
|
|
```
|
|
|
|
3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing
|
|
|
|
---
|
|
|
|
## Mode-Aware Routing (Shared Steps)
|
|
|
|
Shared steps (`s-*.md`) must route based on the mode stored in the tracking file.
|
|
|
|
### Tracking File Frontmatter
|
|
|
|
```yaml
|
|
---
|
|
mode: create # or edit | validate
|
|
stepsCompleted:
|
|
- c-01-brainstorm.md
|
|
- s-01-discovery.md
|
|
# ... other tracking fields
|
|
---
|
|
```
|
|
|
|
### Routing Implementation
|
|
|
|
```markdown
|
|
## COMPLETION ROUTING:
|
|
|
|
1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted
|
|
2. Save content to {trackingFile}
|
|
3. Read {trackingFile}.mode
|
|
4. Route based on mode:
|
|
|
|
### IF mode == create:
|
|
Load ./s-next-create-step.md
|
|
|
|
### IF mode == edit:
|
|
Load ./e-next-edit-step.md
|
|
|
|
### IF mode == validate:
|
|
Load ./s-next-validate-step.md
|
|
```
|
|
|
|
---
|
|
|
|
## File Naming Conventions
|
|
|
|
### Tri-Modal Workflows
|
|
|
|
| Prefix | Meaning | Example |
|
|
| ------ | ------------------ | ---------------------- |
|
|
| `c-` | Create-specific | `c-01-brainstorm.md` |
|
|
| `e-` | Edit-specific | `e-01-load-analyze.md` |
|
|
| `v-` | Validate-specific | `v-01-load-review.md` |
|
|
| `s-` | Shared by 2+ modes | `s-05-activation.md` |
|
|
|
|
### Numbering
|
|
|
|
- Within each prefix type, number sequentially
|
|
- Restart numbering for each prefix type (c-01, e-01, v-01, s-01)
|
|
- Use letters for sub-steps (s-06a, s-06b, s-06c)
|
|
|
|
---
|
|
|
|
## Language Preference Enforcement
|
|
|
|
**CRITICAL:** Every step MUST respect the user's chosen language.
|
|
|
|
### Implementation
|
|
|
|
```markdown
|
|
### Language Preference:
|
|
The user has chosen to communicate in the **{language}** language.
|
|
You MUST respond in **{language}** throughout this step.
|
|
```
|
|
|
|
### Reading Language Preference
|
|
|
|
From tracking file frontmatter:
|
|
```yaml
|
|
---
|
|
userPreferences:
|
|
language: spanish # or any language
|
|
---
|
|
```
|
|
|
|
### Rules
|
|
|
|
- **MUST** read language preference from tracking file at step start
|
|
- **MUST** respond in user's chosen language for ALL content
|
|
- **MUST** include menu options in user's chosen language
|
|
- **EXCEPTION:** Technical terms, file names, and code remain in English
|
|
|
|
---
|
|
|
|
## Data File References
|
|
|
|
When step content becomes too large (>200 lines), extract to `/data/` files:
|
|
|
|
### When to Extract
|
|
|
|
- Step file exceeds 200 lines
|
|
- Content is reference material (rules, examples, patterns)
|
|
- Content is reused across multiple steps
|
|
|
|
### How to Reference
|
|
|
|
```markdown
|
|
## Reference Material:
|
|
|
|
Load and reference: `../data/{data-file-name}.md`
|
|
|
|
Key points from that file:
|
|
- [Point 1]
|
|
- [Point 2]
|
|
```
|
|
|
|
### Data File Best Practices
|
|
|
|
- Keep data files focused on single topic
|
|
- Use clear, descriptive names
|
|
- Include examples and non-examples
|
|
- Optimize for LLM usage (concise, structured)
|
|
|
|
---
|
|
|
|
## Common Pitfalls to Avoid
|
|
|
|
### ❌ DON'T:
|
|
|
|
- Pre-load future steps (violates progressive disclosure)
|
|
- Exceed 250 lines without splitting
|
|
- Forget to update `stepsCompleted` array
|
|
- Ignore user's language preference
|
|
- Skip mode checking in shared steps
|
|
- Use vague menu option letters (stick to A/P/C plus 1-2 custom)
|
|
|
|
### ✅ DO:
|
|
|
|
- Keep files under 200 lines
|
|
- Read tracking file first thing
|
|
- Route based on `mode` field
|
|
- Include A/P in every menu
|
|
- Use descriptive step names
|
|
- Extract complex content to data files
|
|
|
|
---
|
|
|
|
## Template: New Step File
|
|
|
|
```markdown
|
|
---
|
|
name: 'step-name'
|
|
description: 'What this step does'
|
|
|
|
# File References
|
|
thisStepFile: ./step-name.md
|
|
workflowFile: ../workflow.md
|
|
outputFile: {bmb_creations_output_folder}/output.md
|
|
|
|
# Task References
|
|
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
|
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
|
---
|
|
|
|
# Step X: [Step Name]
|
|
|
|
## STEP GOAL:
|
|
|
|
[Single sentence goal]
|
|
|
|
### Role Reinforcement:
|
|
|
|
- ✅ You are a [role] who [does what]
|
|
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
|
|
- ✅ We engage in collaborative dialogue, not command-response
|
|
- ✅ You bring [expertise], user brings [expertise], together we [achieve]
|
|
- ✅ Maintain [tone] throughout
|
|
|
|
### Language Preference:
|
|
The user has chosen to communicate in the **{language}** language.
|
|
You MUST respond in **{language}** throughout this step.
|
|
|
|
### Step-Specific Rules:
|
|
|
|
- 🎯 Focus only on [scope]
|
|
- 🚫 FORBIDDEN to [prohibited action]
|
|
- 💬 Approach: [how to engage]
|
|
- 📋 Ensure [outcome]
|
|
|
|
## EXECUTION PROTOCOLS:
|
|
|
|
- [Action 1]
|
|
- [Action 2]
|
|
- 🚫 FORBIDDEN to [prohibited action]
|
|
|
|
## CONTEXT BOUNDARIES:
|
|
|
|
- Available context: [what's available]
|
|
- Focus: [what to focus on]
|
|
- Limits: [boundaries]
|
|
- Dependencies: [what depends on what]
|
|
|
|
## Sequence of Instructions:
|
|
|
|
### 1. [First Action]
|
|
|
|
**Description of first action**
|
|
|
|
### 2. [Second Action]
|
|
|
|
**Description of second action**
|
|
|
|
...
|
|
|
|
### X. Present MENU OPTIONS
|
|
|
|
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
|
|
|
|
#### Menu Handling Logic:
|
|
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
|
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
|
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
|
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
|
|
|
|
#### EXECUTION RULES:
|
|
- ALWAYS halt and wait for user input after presenting menu
|
|
- ONLY proceed to next step when user selects 'C'
|
|
- After other menu items execution, return to this menu
|
|
- User can chat or ask questions - always respond and then end with display again of the menu options
|
|
|
|
## CRITICAL STEP COMPLETION NOTE
|
|
ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`...
|
|
|
|
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
|
|
|
### ✅ SUCCESS:
|
|
- [Success criteria]
|
|
|
|
### ❌ SYSTEM FAILURE:
|
|
- [Failure criteria]
|
|
|
|
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
|
```
|
|
|
|
---
|
|
|
|
**End of Guidelines**
|