BMAD-METHOD/src/modules/bmb/docs/workflows/step-template.md

BMAD Workflow Step Template

This template provides the standard structure for all BMAD workflow step files. Copy and modify this template for each new step you create.

---

---
name: 'step-[N]-[short-name]'
description: '[Brief description of what this step accomplishes]'

# Path Definitions
workflow_path: '{project-root}/{bmad_folder}/bmb/reference/workflows/[workflow-name]'

# File References (all use {variable} format in file)
thisStepFile: '{workflow_path}/steps/step-[N]-[short-name].md'
nextStepFile: '{workflow_path}/steps/step-[N+1]-[next-short-name].md' # Remove for final step
workflowFile: '{workflow_path}/workflow.md'
outputFile: '{output_folder}/[output-file-name]-{project_name}.md'

# Task References
advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md'

# Template References (if this step uses templates)
profileTemplate: '{workflow_path}/templates/profile-section.md'
assessmentTemplate: '{workflow_path}/templates/assessment-section.md'
strategyTemplate: '{workflow_path}/templates/strategy-section.md'
# Add more as needed
---

Step [N]: [Step Name]

STEP GOAL:

[State the goal in context of the overall workflow goal. Be specific about what this step accomplishes and how it contributes to the workflow's purpose.]

Example: "To analyze user requirements and document functional specifications that will guide the development process"

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator

Role Reinforcement:

• ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
• ✅ 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], and together we produce something better than the sum of our own parts
• ✅ Maintain collaborative [adjective] tone throughout

Step-Specific Rules:

• 🎯 Focus only on [specific task for this step]
• 🚫 FORBIDDEN to [what not to do in this step]
• 💬 Approach: [how to handle this specific task]
• 📋 Additional rule relevant to this step

EXECUTION PROTOCOLS:

• 🎯 [Step-specific protocol 1]
• 💾 [Step-specific protocol 2 - e.g., document updates]
• 📖 [Step-specific protocol 3 - e.g., tracking requirements]
• 🚫 [Step-specific restriction]

CONTEXT BOUNDARIES:

• Available context: [what context is available from previous steps]
• Focus: [what this step should concentrate on]
• Limits: [what not to assume or do]
• Dependencies: [what this step depends on]

Sequence of Instructions (Do not deviate, skip, or optimize)

[Detailed instructions for the step's work]

1. Title

[Specific instructions for first part of the work]

2. Title

[Specific instructions for second part of the work]

Content to Append (if applicable):

## [Section Title]

[Content template or instructions for what to append]

N. (Continue as needed)

N. Present MENU OPTIONS

Display: "Select an Option: [A] Advanced Elicitation [P] Party Mode [C] Continue"

Menu Handling Logic:

• IF A: Execute {advancedElicitationTask} # Or custom action
• IF P: Execute {partyModeWorkflow}
• IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then Redisplay 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

[Specific conditions for completing this step and transitioning to the next, such as output to file being created with this tasks updates]

ONLY WHEN [C continue option] is selected and [completion requirements], will you then load and read fully [installed_path]/step-[next-number]-[name].md to execute and begin [next step description].

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• [Step-specific success criteria 1]
• [Step-specific success criteria 2]
• Content properly saved/document updated
• Menu presented and user input handled correctly
• [General success criteria]

❌ SYSTEM FAILURE:

• [Step-specific failure mode 1]
• [Step-specific failure mode 2]
• Proceeding without user input/selection
• Not updating required documents/frontmatter
• [General failure modes]

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

---

Common Menu Patterns

Standard Menu (A/P/C)

### N. Present MENU OPTIONS

Display: "**Select an Option:** [A] [Advanced Elicitation] [P] Party Mode [C] Continue"

#### Menu Handling Logic:

- IF A: Execute {advancedElicitationTask}
- IF P: Execute {partyModeWorkflow}
- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-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

Auto-Proceed Menu (No User Choice)

### N. Present MENU OPTIONS

Display: "**Proceeding to [next action]...**"

#### Menu Handling Logic:

- After [completion condition], immediately load, read entire file, then execute {nextStepFile}

#### EXECUTION RULES:

- This is an [auto-proceed reason] step with no user choices
- Proceed directly to next step after setup

Custom Menu Options

### N. Present MENU OPTIONS

Display: "**Select an Option:** [A] [Custom Action 1] [B] [Custom Action 2] [C] Continue"

#### Menu Handling Logic:

- IF A: [Custom handler for option A]
- IF B: [Custom handler for option B]
- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-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

Conditional Menu (Based on Workflow State)

### N. Present MENU OPTIONS

Display: "**Select an Option:** [A] [Custom Label] [C] Continue"

#### Menu Handling Logic:

- IF A: Execute {customAction}
- IF C: Save content to {outputFile}, update frontmatter, check [condition]:
  - IF [condition true]: load, read entire file, then execute {pathA}
  - IF [condition false]: load, read entire file, then execute {pathB}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-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

Example Step Implementations

Initialization Step Example

See step-01-init.md for an example of:

• Detecting existing workflow state and short circuit to 1b
• Creating output documents from templates
• Auto-proceeding to the next step (this is not the normal behavior of most steps)
• Handling continuation scenarios

Continuation Step Example

See step-01b-continue.md for an example of:

• Handling already-in-progress workflows
• Detecting completion status
• Presenting update vs new plan options
• Seamless workflow resumption

Standard Step with Menu Example

See step-02-profile.md for an example of:

• Presenting a menu with A/P/C options
• Forcing halt until user selects 'C' (Continue)
• Writing all collected content to output file only when 'C' is selected
• Updating frontmatter with step completion before proceeding
• Using frontmatter variables for file references

Final Step Example

See step-06-prep-schedule.md for an example of:

• Completing workflow deliverables
• Marking workflow as complete in frontmatter
• Providing final success messages
• Ending the workflow session gracefully

Best Practices

1. Keep step files focused - Each step should do one thing well
2. Be explicit in instructions - No ambiguity about what to do
3. Include all critical rules - Don't assume anything from other steps
4. Use clear, concise language - Avoid jargon unless necessary
5. Ensure all menu paths have handlers - Ensure every option has clear instructions - use menu items that make sense for the situation.
6. Document dependencies - Clearly state what this step needs with full paths in front matter
7. Define success and failure clearly - Both for the step and the workflow
8. Mark completion clearly - Ensure final steps update frontmatter to indicate workflow completion