External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

installer improvements

Browse Source
This commit is contained in:
Brian Madison
2025-10-28 12:47:45 -05:00
parent ed3603f7b2
commit ee58586f39
99 changed files with 8143 additions and 1286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

619
bmad/bmb/workflows/create-workflow/workflow-creation-guide.md
View File

@@ -29,6 +29,8 @@ installed_path: '{project-root}/bmad/module/workflows/my-workflow'
template: '{installed_path}/template.md'
instructions: '{installed_path}/instructions.md'
default_output_file: '{output_folder}/output.md'
standalone: true
```
```markdown
@@ -46,14 +48,14 @@ default_output_file: '{output_folder}/output.md'
<critical>You MUST have already loaded and processed: workflow.yaml</critical>
<workflow>
<step n="1" goal="Generate content">
Create the main content for this document.
<template-output>main_content</template-output>
</step>
<step n="1" goal="Generate content">
Create the main content for this document.
<template-output>main_content</template-output>
</step>
</workflow>
```
That's it! To execute, tell the BMAD agent: `workflow my-workflow`
That's it! To execute, tell the BMAD agent: `workflow path/to/my-workflow/`
## Core Concepts
@@ -62,7 +64,7 @@ That's it! To execute, tell the BMAD agent: `workflow my-workflow`
| Aspect | Task | Workflow |
| -------------- | ------------------ | ----------------------- |
| **Purpose** | Single operation | Multi-step process |
| **Format** | XML in `.md` file | Folder with YAML config |
| **Format** | XML | Folder with YAML config |
| **Location** | `/src/core/tasks/` | `/bmad/*/workflows/` |
| **User Input** | Minimal | Extensive |
| **Output** | Variable | Usually documents |
@@ -91,7 +93,7 @@ my-workflow/
├── template.md # Document structure
├── instructions.md # Step-by-step guide
├── checklist.md # Validation criteria
└── [data files] # Supporting resources
└── [data files] # Supporting resources, xml, md, csv or others
```
### workflow.yaml Configuration
@@ -111,11 +113,121 @@ validation: '{installed_path}/checklist.md' # optional
default_output_file: '{output_folder}/document.md'
# Advanced options
autonomous: true # Skip user checkpoints
recommended_inputs: # Expected input docs
- input_doc: 'path/to/doc.md'
# Invocation control
standalone: true # Can be invoked directly (default: true)
```
### Standalone Property: Invocation Control
**CRITICAL**: The `standalone` property controls whether a workflow, task, or tool can be invoked independently or must be called through an agent's menu.
#### For Workflows (workflow.yaml)
```yaml
standalone: true # Can invoke directly: /workflow-name or via IDE command
standalone: false # Must be called from an agent menu or another workflow
```
**When to use `standalone: true` (DEFAULT)**:
- ✅ User-facing workflows that should be directly accessible
- ✅ Workflows invoked via IDE commands or CLI
- ✅ Workflows that users will run independently
- ✅ Most document generation workflows (PRD, architecture, etc.)
- ✅ Action workflows users trigger directly (refactor, analyze, etc.)
- ✅ Entry-point workflows for a module
**When to use `standalone: false`**:
- ✅ Sub-workflows only called by other workflows (via `<invoke-workflow>`)
- ✅ Internal utility workflows not meant for direct user access
- ✅ Workflows that require specific context from parent workflow
- ✅ Helper workflows that don't make sense alone
**Examples**:
```yaml
# Standalone: User invokes directly
name: 'plan-project'
description: 'Create PRD/GDD for any project'
standalone: true # Users run this directly
---
# Non-standalone: Only called by parent workflow
name: 'validate-requirements'
description: 'Internal validation helper for PRD workflow'
standalone: false # Only invoked by plan-project workflow
```
#### For Tasks and Tools (XML files)
Tasks and tools in `src/core/tasks/` and `src/core/tools/` also support the standalone attribute:
```xml
<!-- Standalone task: Can be invoked directly -->
<task name="workflow" standalone="true">
<!-- Task definition -->
</task>
<!-- Non-standalone: Only called by workflows/agents -->
<tool name="internal-helper" standalone="false">
<!-- Tool definition -->
</tool>
```
**Task/Tool Standalone Guidelines**:
- `standalone="true"`: Core tasks like workflow.xml, create-doc.xml that users/agents invoke directly
- `standalone="false"`: Internal helpers, utilities only called by other tasks/workflows
#### Default Behavior
**If standalone property is omitted**:
- Workflows: Default to `standalone: true` (accessible directly)
- Tasks/Tools: Default to `standalone: true` (accessible directly)
**Best Practice**: Explicitly set standalone even if using default to make intent clear.
#### Invocation Patterns
**Standalone workflows can be invoked**:
1. Directly by users: `/workflow-name` or IDE command
2. From agent menus: `workflow: "{path}/workflow.yaml"`
3. From other workflows: `<invoke-workflow path="{path}/workflow.yaml">`
**Non-standalone workflows**:
1. ❌ Cannot be invoked directly by users
2. ❌ Cannot be called from IDE commands
3. ✅ Can be invoked by other workflows via `<invoke-workflow>`
4. ✅ Can be called from agent menu items
#### Module Design Implications
**Typical Module Pattern**:
```yaml
# Entry-point workflows: standalone: true
bmm/workflows/plan-project/workflow.yaml → standalone: true
bmm/workflows/architecture/workflow.yaml → standalone: true
# Helper workflows: standalone: false
bmm/workflows/internal/validate-epic/workflow.yaml → standalone: false
bmm/workflows/internal/format-story/workflow.yaml → standalone: false
```
**Benefits of this pattern**:
- Clear separation between user-facing and internal workflows
- Prevents users from accidentally invoking incomplete/internal workflows
- Cleaner IDE command palette (only shows standalone workflows)
- Better encapsulation and maintainability
### Common Patterns
**Full Document Workflow** (most common)
@@ -135,6 +247,395 @@ recommended_inputs: # Expected input docs
## Writing Instructions
### Instruction Styles: Intent-Based vs Prescriptive
**CRITICAL DESIGN DECISION**: Choose your instruction style early - it fundamentally shapes the user experience.
#### Default Recommendation: Intent-Based (Adaptive)
**Intent-based workflows give the AI goals and principles, letting it adapt the conversation naturally to the user's context.** This is the BMAD v6 default for most workflows.
#### The Two Approaches
##### 1. Intent-Based Instructions (RECOMMENDED)
**What it is**: Guide the AI with goals, principles, and context - let it determine the best way to interact with each user.
**Characteristics**:
- Uses `<action>` tags with guiding instructions
- Focuses on WHAT to accomplish and WHY it matters
- Lets AI adapt conversation to user needs
- More flexible and conversational
- Better for complex discovery and iterative refinement
**When to use**:
- Complex discovery processes (requirements gathering, architecture design)
- Creative brainstorming and ideation
- Iterative refinement workflows
- When user input quality matters more than consistency
- Workflows requiring adaptation to context
- Teaching/educational workflows
- When users have varying skill levels
**Example**:
```xml
<step n="2" goal="Understand user's target audience">
<action>Engage in collaborative discovery to understand their target users:
Ask open-ended questions to explore:
- Who will use this product?
- What problems do they face?
- What are their goals and motivations?
- How tech-savvy are they?
Listen for clues about:
- Demographics and characteristics
- Pain points and needs
- Current solutions they use
- Unmet needs or frustrations
Adapt your depth and terminology to the user's responses.
If they give brief answers, dig deeper with follow-ups.
If they're uncertain, help them think through it with examples.
</action>
<template-output>target_audience</template-output>
</step>
```
**Intent-based workflow adapts**:
- **Expert user** might get: "Tell me about your target users - demographics, pain points, and technical profile?"
- **Beginner user** might get: "Let's talk about who will use this. Imagine your ideal customer - what do they look like? What problem are they trying to solve?"
##### 2. Prescriptive Instructions (Use Selectively)
**What it is**: Provide exact wording for questions and specific options for answers.
**Characteristics**:
- Uses `<ask>` tags with exact question text
- Provides specific options or formats
- More controlled and predictable
- Ensures consistency across runs
- Better for simple data collection or compliance needs
**When to use**:
- Simple data collection (platform choice, format selection)
- Compliance verification and standards adherence
- Configuration with finite, well-defined options
- When consistency is critical across all executions
- Quick setup wizards
- Binary decisions (yes/no, enable/disable)
- When gathering specific required fields
**Example**:
```xml
<step n="3" goal="Select target platform">
<ask>What is your target platform?
1. Web (browser-based application)
2. Mobile (iOS/Android native apps)
3. Desktop (Windows/Mac/Linux applications)
4. CLI (command-line tool)
5. API (backend service)
Enter the number (1-5):</ask>
<action>Store the platform choice as {{target_platform}}</action>
<template-output>target_platform</template-output>
</step>
```
**Prescriptive workflow stays consistent** - every user gets the same 5 options in the same format.
#### Best Practice: Mix Both Styles
**Even predominantly intent-based workflows should use prescriptive moments** for simple choices. Even prescriptive workflows can have intent-based discovery.
**Example of effective mixing**:
```xml
<!-- Intent-based: Complex discovery -->
<step n="1" goal="Understand user vision">
<action>Explore the user's vision through open conversation:
Help them articulate:
- The core problem they're solving
- Their unique approach or innovation
- The experience they want to create
Adapt your questions based on their expertise and communication style.
If they're visionary, explore the "why". If they're technical, explore the "how".
</action>
<template-output>vision</template-output>
</step>
<!-- Prescriptive: Simple data -->
<step n="2" goal="Capture basic metadata">
<ask>What is your target platform? Choose one:
- Web
- Mobile
- Desktop
- CLI
- API</ask>
<action>Store as {{platform}}</action>
</step>
<!-- Intent-based: Deep exploration -->
<step n="3" goal="Design user experience">
<action>Facilitate collaborative UX design:
Guide them to explore:
- User journey and key flows
- Interaction patterns and affordances
- Visual/aesthetic direction
Use their platform choice from step 2 to inform relevant patterns.
For web: discuss responsive design. For mobile: touch interactions. Etc.
</action>
<template-output>ux_design</template-output>
</step>
```
#### Interactivity Levels
Beyond style (intent vs prescriptive), consider **how interactive** your workflow should be:
##### High Interactivity (Collaborative)
- Constant back-and-forth with user
- Multiple asks per step
- Iterative refinement and review
- User guides the direction
- **Best for**: Creative work, complex decisions, learning
**Example**:
```xml
<step n="4" goal="Design feature set" repeat="until-satisfied">
<action>Collaborate on feature definitions:
For each feature the user proposes:
- Help them articulate it clearly
- Explore edge cases together
- Consider implications and dependencies
- Refine the description iteratively
After each feature: "Want to refine this, add another, or move on?"
</action>
</step>
```
##### Medium Interactivity (Guided)
- Key decision points have interaction
- AI proposes, user confirms or refines
- Validation checkpoints
- **Best for**: Most document workflows, structured processes
**Example**:
```xml
<step n="5" goal="Generate architecture decisions">
<action>Based on the PRD, identify 10-15 key architectural decisions needed</action>
<action>For each decision, research options and present recommendation</action>
<ask>Approve this decision or propose alternative?</ask>
<action>Record decision and rationale</action>
</step>
```
##### Low Interactivity (Autonomous)
- Minimal user input required
- AI works independently with guidelines
- User reviews final output
- **Best for**: Automated generation, batch processing
**Example**:
```xml
<step n="6" goal="Generate user stories">
<action>For each epic in the PRD, generate 3-7 user stories following this pattern:
- As a [user type]
- I want to [action]
- So that [benefit]
Ensure stories are:
- Independently valuable
- Testable
- Sized appropriately (1-5 days of work)
</action>
<template-output>user_stories</template-output>
</step>
<step n="7" goal="Review generated stories">
<ask>Review the generated user stories. Want to refine any? (y/n)</ask>
<check if="yes">
<goto step="6">Regenerate with feedback</goto>
</check>
</step>
```
#### Decision Framework
**Choose Intent-Based when**:
- ✅ User knowledge/skill level varies
- ✅ Context matters (one-size-fits-all won't work)
- ✅ Discovery and exploration are important
- ✅ Quality of input matters more than consistency
- ✅ Teaching/education is part of the goal
- ✅ Iteration and refinement expected
**Choose Prescriptive when**:
- ✅ Options are finite and well-defined
- ✅ Consistency across users is critical
- ✅ Compliance or standards matter
- ✅ Simple data collection
- ✅ Users just need to make a choice and move on
- ✅ Speed matters more than depth
**Choose High Interactivity when**:
- ✅ User expertise is essential
- ✅ Creative collaboration needed
- ✅ Decisions have major implications
- ✅ Learning and understanding matter
- ✅ Iteration is expected
**Choose Low Interactivity when**:
- ✅ Process is well-defined and repeatable
- ✅ AI can work autonomously with clear guidelines
- ✅ User time is constrained
- ✅ Batch processing or automation desired
- ✅ Review-and-refine model works
#### Implementation Guidelines
**For Intent-Based Workflows**:
1. **Use `<action>` tags with guiding instructions**
```xml
<action>Facilitate discovery of {{topic}}:
Ask open-ended questions to explore:
- {{aspect_1}}
- {{aspect_2}}
Listen for clues about {{patterns_to_notice}}.
Adapt your approach based on their {{context_factor}}.
</action>
```
2. **Provide principles, not scripts**
```xml
<!-- ✅ Good: Principles -->
<action>Help user articulate their unique value proposition.
Focus on what makes them different, not just what they do.
If they struggle, offer examples from analogous domains.</action>
<!-- ❌ Avoid: Prescriptive script -->
<ask>What makes your product unique? Provide 2-3 bullet points.</ask>
```
3. **Guide with context and rationale**
```xml
<action>Now that we understand their {{context_from_previous}},
explore how {{current_topic}} connects to their vision.
This matters because {{reason_it_matters}}.
If they seem uncertain about {{potential_challenge}}, help them think through {{approach}}.
</action>
```
**For Prescriptive Workflows**:
1. **Use `<ask>` tags with specific questions**
```xml
<ask>Select your preferred database:
1. PostgreSQL
2. MySQL
3. MongoDB
4. SQLite
Enter number (1-4):</ask>
```
2. **Provide clear options and formats**
```xml
<ask>Enable user authentication? (yes/no)</ask>
<ask>Enter project name (lowercase, no spaces):</ask>
```
3. **Keep it crisp and clear**
```xml
<!-- ✅ Good: Clear and direct -->
<ask>Target platform? (web/mobile/desktop)</ask>
<!-- ❌ Avoid: Over-explaining -->
<ask>We need to know what platform you're building for. This will affect
the technology stack recommendations. Please choose: web, mobile, or desktop.</ask>
```
#### Mixing Styles Within a Workflow
**Pattern: Intent-based discovery → Prescriptive capture → Intent-based refinement**
```xml
<step n="1" goal="Explore user needs">
<!-- Intent-based discovery -->
<action>Engage in open conversation to understand user needs deeply...</action>
</step>
<step n="2" goal="Capture key metrics">
<!-- Prescriptive data collection -->
<ask>Expected daily active users? (number)</ask>
<ask>Data sensitivity level? (public/internal/sensitive/highly-sensitive)</ask>
</step>
<step n="3" goal="Design solution approach">
<!-- Intent-based design -->
<action>Collaborate on solution design, using the metrics from step 2 to inform scale and security decisions...</action>
</step>
```
**Pattern: Prescriptive setup → Intent-based execution**
```xml
<step n="1" goal="Quick setup">
<!-- Prescriptive configuration -->
<ask>Project type? (web-app/api/cli/library)</ask>
<ask>Language? (typescript/python/go/rust)</ask>
</step>
<step n="2" goal="Detailed design">
<!-- Intent-based design -->
<action>Now that we know it's a {{project_type}} in {{language}},
let's explore the architecture in detail.
Guide them through design decisions appropriate for a {{project_type}}...
</action>
</step>
```
### Basic Structure
```markdown
@@ -290,6 +791,43 @@ _Generated on {{date}}_
- **`<action if="">`** - Single conditional action (cleaner, more concise)
- **`<check if="">...</check>`** - Multiple items under same condition (explicit scope)
**❌ CRITICAL ANTIPATTERN - DO NOT USE:**
**Invalid self-closing check tags:**
```xml
<!-- ❌ WRONG - Invalid XML structure -->
<check>If condition met:</check>
<action>Do something</action>
<!-- ❌ WRONG - Ambiguous nesting -->
<check>If validation fails:</check>
<action>Log error</action>
<goto step="1">Retry</goto>
```
**Why this is wrong:**
- Creates invalid XML structure (check tag doesn't wrap anything)
- Ambiguous - unclear if actions are inside or outside the condition
- Breaks formatter and parser logic
- Not part of BMAD workflow spec
**✅ CORRECT alternatives:**
```xml
<!-- ✅ Single action - use inline if -->
<action if="condition met">Do something</action>
<!-- ✅ Multiple actions - use proper wrapper block -->
<check if="validation fails">
<action>Log error</action>
<goto step="1">Retry</goto>
</check>
```
**Rule:** If you have only ONE conditional action, use `<action if="">`. If you have MULTIPLE conditional actions, use `<check if="">...</check>` wrapper with a closing tag.
### Loops
```xml
@@ -358,21 +896,21 @@ _Generated on {{date}}_
```xml
<workflow>
<step n="1" goal="Gather context">
Load existing documents and understand project scope.
<template-output>context</template-output>
</step>
<step n="1" goal="Gather context">
Load existing documents and understand project scope.
<template-output>context</template-output>
</step>
<step n="2" goal="Define requirements">
Create functional and non-functional requirements.
<template-output>requirements</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="2" goal="Define requirements">
Create functional and non-functional requirements.
<template-output>requirements</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="3" goal="Validate">
Check requirements against goals.
<template-output>validated_requirements</template-output>
</step>
<step n="3" goal="Validate">
Check requirements against goals.
<template-output>validated_requirements</template-output>
</step>
</workflow>
```
@@ -404,20 +942,20 @@ Check requirements against goals.
```xml
<workflow name="greenfield-app">
<step n="1" goal="Discovery">
<invoke-workflow>product-brief</invoke-workflow>
<template-output>brief</template-output>
</step>
<step n="1" goal="Discovery">
<invoke-workflow>product-brief</invoke-workflow>
<template-output>brief</template-output>
</step>
<step n="2" goal="Requirements">
<invoke-workflow input="{{brief}}">prd</invoke-workflow>
<template-output>prd</template-output>
</step>
<step n="2" goal="Requirements">
<invoke-workflow input="{{brief}}">prd</invoke-workflow>
<template-output>prd</template-output>
</step>
<step n="3" goal="Architecture">
<invoke-workflow input="{{prd}}">architecture</invoke-workflow>
<template-output>architecture</template-output>
</step>
<step n="3" goal="Architecture">
<invoke-workflow input="{{prd}}">architecture</invoke-workflow>
<template-output>architecture</template-output>
</step>
</workflow>
```
@@ -426,9 +964,9 @@ Check requirements against goals.
### Design Principles
1. **Keep steps focused** - Single goal per step
2. **Limit scope** - 5-10 steps maximum
2. **Limit scope** - 5-12 steps maximum
3. **Build progressively** - Start simple, add detail
4. **Checkpoint often** - Save after major sections
4. **Checkpoint often** - Save after major workflow sections and ensure documents are being drafted from the start
5. **Make sections optional** - Let users skip when appropriate
### Instruction Guidelines
@@ -502,7 +1040,7 @@ Web bundles allow workflows to be deployed as self-contained packages for web en
### Creating a Web Bundle
Add this section to your workflow.yaml:
Add this section to your workflow.yaml ensuring critically all dependant files or workflows are listed:
```yaml
web_bundle:
@@ -561,6 +1099,8 @@ web_bundle:
# Sub-workflow reference
validation_workflow: 'bmad/bmm/workflows/validate-requirements/workflow.yaml'
standalone: true
web_bundle_files:
# Core workflow files
- 'bmad/bmm/workflows/analyze-requirements/instructions.md'
@@ -599,14 +1139,9 @@ web_bundle:
- Combine related steps
- Make sections optional
- Create multiple focused workflows with a parent orchestration
- Reduce elicitation points
### User Confusion
- Add clearer step goals
- Provide more examples
- Explain section purpose
---
_For implementation details, see:_