BMAD-METHOD/src/modules/bmb/workflows/create-workflow/instructions.md

Build Workflow - Workflow Builder Instructions

The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/create-workflow/workflow.yaml You MUST fully understand the workflow creation guide at: {workflow_creation_guide} Study the guide thoroughly to follow ALL conventions for optimal human-AI collaboration

Do you want to brainstorm workflow ideas first? [y/n] Invoke brainstorming workflow to explore ideas and design concepts: - Workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml - Context data: {installed_path}/brainstorm-context.md - Purpose: Generate creative workflow ideas, explore different approaches, and clarify requirements

The brainstorming output will inform:

• Workflow purpose and goals
• Workflow type selection
• Step design and structure
• User experience considerations
• Technical requirements

Skip brainstorming and proceed directly to workflow building process. Load the complete workflow creation guide from: {workflow_creation_guide} Study all sections thoroughly including: - Core concepts (tasks vs workflows, workflow types) - Workflow structure (required/optional files, patterns) - Writing instructions (step attributes, XML tags, flow control) - Templates and variables (syntax, naming, sources) - Validation best practices - Common pitfalls to avoid Load template files from: {workflow_template_path}/ You must follow ALL conventions from the guide to ensure optimal human-AI collaboration Ask the user: - What is the workflow name? (kebab-case, e.g., "product-brief") - What module will it belong to? (e.g., "bmm", "bmb", "cis") - Store as {{target_module}} for output path determination - What is the workflow's main purpose? - What type of workflow is this? - Document workflow (generates documents like PRDs, specs) - Action workflow (performs actions like refactoring) - Interactive workflow (guided sessions) - Autonomous workflow (runs without user input) - Meta-workflow (coordinates other workflows)

Based on type, determine which files are needed:

• Document: workflow.yaml + template.md + instructions.md + checklist.md
• Action: workflow.yaml + instructions.md
• Others: Varies based on requirements

Determine output location based on module assignment:

• If workflow belongs to module: Save to {module_output_folder}
• If standalone workflow: Save to {standalone_output_folder}

Store decisions for later use.

Collect essential configuration details: - Description (clear purpose statement) - Author name (default to user_name or "BMad") - Output file naming pattern - Any required input documents - Any required tools or dependencies

Create the workflow name in kebab-case and verify it doesn't conflict with existing workflows.

Work with user to outline the workflow steps: - How many major steps? (Recommend 5-10 max) - What is the goal of each step? - Which steps are optional? - Which steps need user input? - Which steps should repeat? - What variables/outputs does each step produce?

Create a step outline with clear goals and outputs.

Load and use the template at: {template_workflow_yaml}

Replace all placeholders following the workflow creation guide conventions:

• {TITLE} → Proper case workflow name
• {WORKFLOW_CODE} → kebab-case name
• {WORKFLOW_DESCRIPTION} → Clear description
• {module-code} → Target module
• {file.md} → Output filename pattern

Include:

• All metadata from steps 1-2
• Proper paths for installed_path using variable substitution
• Template/instructions/validation paths based on workflow type:
  • Document workflow: all files (template, instructions, validation)
  • Action workflow: instructions only (template: false)
  • Autonomous: set autonomous: true flag
• Required tools if any
• Recommended inputs if any

Follow path conventions from guide:

• Use {project-root} for absolute paths
• Use {installed_path} for workflow components
• Use {config_source} for config references

Determine save location:

• Use the output folder determined in Step 1 (module or standalone)
• Write to {{output_folder}}/workflow.yaml

Load and use the template at: {template_instructions}

Generate the instructions.md file following the workflow creation guide:

1. ALWAYS include critical headers:

   • Workflow engine reference: {project_root}/bmad/core/tasks/workflow.xml
   • workflow.yaml reference: must be loaded and processed

2. Structure with tags containing all steps

3. For each step from design phase, follow guide conventions:

   • Step attributes: n="X" goal="clear goal statement"
   • Optional steps: optional="true"
   • Repeating: repeat="3" or repeat="for-each-X" or repeat="until-approved"
   • Conditional: if="condition"
   • Sub-steps: Use 3a, 3b notation

4. Use proper XML tags from guide:

   • Execution: , , , ,
   • Output: , , ,
   • Flow: , ,

5. Best practices from guide:

   • Keep steps focused (single goal)
   • Be specific ("Write 1-2 paragraphs" not "Write about")
   • Provide examples where helpful
   • Set limits ("3-5 items maximum")
   • Save checkpoints with

Save location:

• Write to {{output_folder}}/instructions.md

Load and use the template at: {template_template}

Generate the template.md file following guide conventions:

1. Document structure with clear sections
2. Variable syntax: {{variable_name}} using snake_case
3. Variable names MUST match tags exactly from instructions
4. Include standard metadata:
   • Date: {{date}}
   • Author: {{user_name}} (if applicable)
5. Follow naming conventions from guide:
   • Use descriptive names: {{primary_user_journey}} not {{puj}}
   • Snake_case for all variables
   • Match instruction outputs precisely

Variable sources as per guide:

• workflow.yaml config values
• User input runtime values
• Step outputs via
• System variables (date, paths)

Save location:

• Write to {{output_folder}}/template.md

Ask if user wants a validation checklist. If yes:

Load and use the template at: {template_checklist}

Create checklist.md following guide best practices:

1. Make criteria MEASURABLE and SPECIFIC ❌ "- [ ] Good documentation" ✅ "- [ ] Each function has JSDoc comments with parameters and return types"

2. Group checks logically:

   • Structure: All sections present, no placeholders, proper formatting
   • Content Quality: Clear and specific, technically accurate, consistent terminology
   • Completeness: Ready for next phase, dependencies documented, action items defined

3. Include workflow-specific validations based on type:

   • Document workflows: Template variables mapped, sections complete
   • Action workflows: Actions clearly defined, error handling specified
   • Interactive: User prompts clear, decision points documented

4. Add final validation section with issue lists

Save location:

• Write to {{output_folder}}/checklist.md

Ask if any supporting data files are needed: - CSV files with data - Example documents - Reference materials

If yes, create placeholder files or copy from templates.

Review the created workflow: 1. Verify all file paths are correct 2. Check variable names match between files 3. Ensure step numbering is sequential 4. Validate YAML syntax 5. Confirm all placeholders are replaced

Show user a summary of created files and their locations. Ask if they want to:

• Test run the workflow
• Make any adjustments
• Add additional steps or features

Will this workflow need to be deployable as a web bundle? [yes/no]

If yes: Explain web bundle requirements:

• Web bundles are self-contained and cannot use config_source variables
• All files must be explicitly listed in web_bundle_files
• File paths use bmad/ root (not {project-root})

Configure web_bundle section in workflow.yaml:

1. Copy core workflow metadata (name, description, author)

2. Convert all file paths to bmad/-relative paths:

   • Remove {project-root}/ prefix
   • Remove {config_source} references (use hardcoded values)
   • Example: "{project-root}/bmad/bmm/workflows/x" → "bmad/bmm/workflows/x"

3. List ALL referenced files:

   • Scan instructions.md for any file paths
   • Scan template.md for any includes or references
   • Include all data files (CSV, JSON, etc.)
   • Include any sub-workflow YAML files
   • Include any shared templates

4. Create web_bundle_files array with complete list

Example:

web_bundle:
  name: '{workflow_name}'
  description: '{workflow_description}'
  author: '{author}'
  instructions: 'bmad/{module}/workflows/{workflow}/instructions.md'
  validation: 'bmad/{module}/workflows/{workflow}/checklist.md'
  template: 'bmad/{module}/workflows/{workflow}/template.md'

  # Any data files (no config_source)
  data_file: 'bmad/{module}/workflows/{workflow}/data.csv'

  web_bundle_files:
    - 'bmad/{module}/workflows/{workflow}/instructions.md'
    - 'bmad/{module}/workflows/{workflow}/checklist.md'
    - 'bmad/{module}/workflows/{workflow}/template.md'
    - 'bmad/{module}/workflows/{workflow}/data.csv'
    # Add every single file referenced anywhere

Validate web bundle completeness:

• Ensure no {config_source} variables remain
• Verify all file paths are listed
• Check that paths are bmad/-relative

web_bundle_config

Create a brief README for the workflow folder explaining: - Purpose and use case - How to invoke: `workflow {workflow_name}` - Expected inputs - Generated outputs - Any special requirements

Provide user with:

• Location of created workflow: {{output_folder}}
• Command to run it
• Next steps:
  • "Run the BMAD Method installer to this project location"
  • "Select the option 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder"
  • "This will compile your new workflow and make it available for use"