mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
doc updates
This commit is contained in:
Brian Madison
@@ -41,6 +41,14 @@ agent:
|
||||
workflow: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
|
||||
description: Create a new BMAD Core workflow with proper structure
|
||||
|
||||
- trigger: edit-agent
|
||||
workflow: "{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml"
|
||||
description: Edit existing agents while following best practices
|
||||
|
||||
- trigger: edit-module
|
||||
workflow: "{project-root}/bmad/bmb/workflows/edit-module/workflow.yaml"
|
||||
description: Edit existing modules (structure, agents, workflows, documentation)
|
||||
|
||||
- trigger: edit-workflow
|
||||
workflow: "{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml"
|
||||
description: Edit existing workflows while following best practices
|
||||
|
||||
@@ -361,6 +361,13 @@ When building agents:
|
||||
- Workflows can be incomplete (marked "todo")
|
||||
- Workflow paths must be valid or "todo"
|
||||
|
||||
**Workflow Interaction Styles** (BMAD v6 default):
|
||||
|
||||
- **Intent-based + Interactive**: Workflows adapt to user context and skill level
|
||||
- Workflows collaborate with users, not just extract data
|
||||
- See workflow-creation-guide.md "Instruction Styles" section for details
|
||||
- When creating workflows for your agent, default to intent-based unless you need prescriptive control
|
||||
|
||||
### With Tasks
|
||||
|
||||
- Tasks are single operations
|
||||
|
||||
@@ -128,10 +128,51 @@
|
||||
|
||||
<action>Transform their natural language capabilities into technical YAML command structure, explaining the implementation approach as you structure each capability into workflows, actions, or prompts</action>
|
||||
|
||||
<check if="agent will invoke workflows or have significant user interaction">
|
||||
<action>Discuss interaction style for this agent:
|
||||
|
||||
Since this agent will {{invoke_workflows/interact_significantly}}, consider how it should interact with users:
|
||||
|
||||
**For Full/Module Agents with workflows:**
|
||||
|
||||
**Interaction Style** (for workflows this agent invokes):
|
||||
|
||||
- **Intent-based (Recommended)**: Workflows adapt conversation to user context, skill level, needs
|
||||
- **Prescriptive**: Workflows use structured questions with specific options
|
||||
- **Mixed**: Strategic use of both (most workflows will be mixed)
|
||||
|
||||
**Interactivity Level** (for workflows this agent invokes):
|
||||
|
||||
- **High (Collaborative)**: Constant user collaboration, iterative refinement
|
||||
- **Medium (Guided)**: Key decision points with validation
|
||||
- **Low (Autonomous)**: Minimal input, final review
|
||||
|
||||
Explain: "Most BMAD v6 workflows default to **intent-based + medium/high interactivity**
|
||||
for better user experience. Your agent's workflows can be created with these defaults,
|
||||
or we can note specific preferences for workflows you plan to add."
|
||||
|
||||
**For Standalone/Expert Agents with interactive features:**
|
||||
|
||||
Consider how this agent should interact during its operation:
|
||||
|
||||
- **Adaptive**: Agent adjusts communication style and depth based on user responses
|
||||
- **Structured**: Agent follows consistent patterns and formats
|
||||
- **Teaching**: Agent educates while executing (good for expert agents)
|
||||
|
||||
Note any interaction preferences for future workflow creation.
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>If they seem engaged, explore whether they'd like to add special prompts for complex analyses or critical setup steps for agent activation</action>
|
||||
|
||||
<action>Build the YAML menu structure naturally from the conversation, ensuring each command has proper trigger, workflow/action reference, and description</action>
|
||||
|
||||
<action>For commands that will invoke workflows, note whether those workflows exist or need to be created:
|
||||
|
||||
- Existing workflows: Verify paths are correct
|
||||
- New workflows needed: Note that they'll be created with intent-based + interactive defaults unless specified
|
||||
</action>
|
||||
|
||||
<example>
|
||||
```yaml
|
||||
menu:
|
||||
|
||||
@@ -14,6 +14,7 @@ src/modules/{module-code}/
|
||||
├── agents/ # Agent definitions (.agent.yaml)
|
||||
├── workflows/ # Workflow folders
|
||||
├── tasks/ # Task files
|
||||
├── tools/ # Tool files
|
||||
├── templates/ # Shared templates
|
||||
├── data/ # Static data
|
||||
├── _module-installer/ # Installation configuration
|
||||
@@ -27,11 +28,11 @@ src/modules/{module-code}/
|
||||
├── agents/ # Compiled agent files (.md)
|
||||
├── workflows/ # Workflow instances
|
||||
├── tasks/ # Task files
|
||||
├── tools/ # Tool files
|
||||
├── templates/ # Templates
|
||||
├── data/ # Module data
|
||||
├── config.yaml # Generated from install-config.yaml
|
||||
└── README.md # Module documentation
|
||||
|
||||
```
|
||||
|
||||
## Module Types by Complexity
|
||||
|
||||
@@ -72,7 +72,7 @@ Based on type, determine which files are needed:
|
||||
Store decisions for later use.
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Gather workflow metadata">
|
||||
<step n="2" goal="Gather workflow metadata and invocation settings">
|
||||
Collect essential configuration details:
|
||||
- Description (clear purpose statement)
|
||||
- Author name (default to user_name or "BMad")
|
||||
@@ -80,40 +80,149 @@ Collect essential configuration details:
|
||||
- Any required input documents
|
||||
- Any required tools or dependencies
|
||||
|
||||
<action>Determine standalone property - this controls how the workflow can be invoked:
|
||||
|
||||
Explain to the user:
|
||||
|
||||
**Standalone Property** controls whether the workflow can be invoked directly or only called by other workflows/agents.
|
||||
|
||||
**standalone: true (DEFAULT - Recommended for most workflows)**:
|
||||
|
||||
- Users can invoke directly via IDE commands or `/workflow-name`
|
||||
- Shows up in IDE command palette
|
||||
- Can also be called from agent menus or other workflows
|
||||
- Use for: User-facing workflows, entry-point workflows, any workflow users run directly
|
||||
|
||||
**standalone: false (Use for helper/internal workflows)**:
|
||||
|
||||
- Cannot be invoked directly by users
|
||||
- Only called via `<invoke-workflow>` from other workflows or agent menus
|
||||
- Doesn't appear in IDE command palette
|
||||
- Use for: Internal utilities, sub-workflows, helpers that don't make sense standalone
|
||||
|
||||
Most workflows should be `standalone: true` to give users direct access.
|
||||
</action>
|
||||
|
||||
<ask>Should this workflow be directly invokable by users?
|
||||
|
||||
1. **Yes (Recommended)** - Users can run it directly (standalone: true)
|
||||
2. **No** - Only called by other workflows/agents (standalone: false)
|
||||
|
||||
Most workflows choose option 1:</ask>
|
||||
|
||||
<action>Store {{standalone_setting}} as true or false based on response</action>
|
||||
|
||||
Create the workflow name in kebab-case and verify it doesn't conflict with existing workflows.
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Design workflow steps">
|
||||
Work with user to outline the workflow steps:
|
||||
- How many major steps? (Recommend 5-10 max)
|
||||
<step n="3" goal="Understand workflow interaction style and design steps">
|
||||
<critical>Instruction style and interactivity level fundamentally shape the user experience - choose thoughtfully</critical>
|
||||
|
||||
<action>Reference the comprehensive "Instruction Styles: Intent-Based vs Prescriptive" section from the loaded creation guide</action>
|
||||
|
||||
<action>Discuss instruction style collaboratively with the user:
|
||||
|
||||
Explain that there are two primary approaches:
|
||||
|
||||
**Intent-Based (RECOMMENDED as default)**:
|
||||
|
||||
- Gives AI goals and principles, lets it adapt conversation naturally
|
||||
- More flexible, conversational, responsive to user context
|
||||
- Better for: discovery, complex decisions, teaching, varied user skill levels
|
||||
- Uses <action> tags with guiding instructions
|
||||
- Example from architecture workflow: Facilitates decisions adapting to user_skill_level
|
||||
|
||||
**Prescriptive**:
|
||||
|
||||
- Provides exact questions and specific options
|
||||
- More controlled, predictable, consistent across runs
|
||||
- Better for: simple data collection, finite options, compliance, quick setup
|
||||
- Uses <ask> tags with specific question text
|
||||
- Example: Platform selection with 5 defined choices
|
||||
|
||||
Explain that **most workflows should default to intent-based** but use prescriptive for simple data points.
|
||||
The architecture workflow is an excellent example of intent-based with prescriptive moments.
|
||||
</action>
|
||||
|
||||
<ask>For this workflow's PRIMARY style:
|
||||
|
||||
1. **Intent-based (Recommended)** - Adaptive, conversational, responds to user context
|
||||
2. **Prescriptive** - Structured, consistent, controlled interactions
|
||||
3. **Mixed/Balanced** - I'll help you decide step-by-step
|
||||
|
||||
What feels right for your workflow's purpose?</ask>
|
||||
|
||||
<action>Store {{instruction_style}} preference</action>
|
||||
|
||||
<action>Now discuss interactivity level:
|
||||
|
||||
Beyond style, consider **how interactive** this workflow should be:
|
||||
|
||||
**High Interactivity (Collaborative)**:
|
||||
|
||||
- Constant back-and-forth with user
|
||||
- User guides direction, AI facilitates
|
||||
- Iterative refinement and review
|
||||
- Best for: creative work, complex decisions, learning experiences
|
||||
- Example: Architecture workflow's collaborative decision-making
|
||||
|
||||
**Medium Interactivity (Guided)**:
|
||||
|
||||
- Key decision points have interaction
|
||||
- AI proposes, user confirms or refines
|
||||
- Validation checkpoints
|
||||
- Best for: most document workflows, structured processes
|
||||
- Example: PRD workflow with sections to review
|
||||
|
||||
**Low Interactivity (Autonomous)**:
|
||||
|
||||
- Minimal user input required
|
||||
- AI works independently with guidelines
|
||||
- User reviews final output
|
||||
- Best for: automated generation, batch processing
|
||||
- Example: Generating user stories from epics
|
||||
</action>
|
||||
|
||||
<ask>What interactivity level suits this workflow?
|
||||
|
||||
1. **High** - Highly collaborative, user actively involved throughout
|
||||
2. **Medium** - Guided with key decision points (most common)
|
||||
3. **Low** - Autonomous with final review
|
||||
|
||||
Select the level that matches your workflow's purpose:</ask>
|
||||
|
||||
<action>Store {{interactivity_level}} preference</action>
|
||||
|
||||
<action>Explain how these choices will inform the workflow design:
|
||||
|
||||
- Intent-based + High interactivity: Conversational discovery with open questions
|
||||
- Intent-based + Medium: Facilitated guidance with confirmation points
|
||||
- Intent-based + Low: Principle-based autonomous generation
|
||||
- Prescriptive + any level: Structured questions, but frequency varies
|
||||
- Mixed: Strategic use of both styles where each works best
|
||||
</action>
|
||||
|
||||
<action>Now work with user to outline workflow steps:
|
||||
|
||||
- How many major steps? (Recommend 3-7 for most workflows)
|
||||
- What is the goal of each step?
|
||||
- Which steps are optional?
|
||||
- Which steps need user input?
|
||||
- Which steps need heavy user collaboration vs autonomous execution?
|
||||
- Which steps should repeat?
|
||||
- What variables/outputs does each step produce?
|
||||
|
||||
<ask>What instruction style should this workflow favor?
|
||||
Consider their instruction_style and interactivity_level choices when designing step flow:
|
||||
|
||||
**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
|
||||
- High interactivity: More granular steps with collaboration
|
||||
- Low interactivity: Larger autonomous steps with review
|
||||
- Intent-based: Focus on goals and principles in step descriptions
|
||||
- Prescriptive: Define specific questions and options
|
||||
</action>
|
||||
|
||||
- More flexible and conversational
|
||||
- LLM chooses appropriate questions based on context
|
||||
- Better for complex discovery and iterative refinement
|
||||
- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
|
||||
<action>Create a step outline that matches the chosen style and interactivity level</action>
|
||||
<action>Note which steps should be intent-based vs prescriptive (if mixed approach)</action>
|
||||
|
||||
**2. Prescriptive** - Provide exact wording for questions and options
|
||||
|
||||
- More controlled and predictable
|
||||
- Ensures consistency across runs
|
||||
- Better for simple data collection or specific compliance needs
|
||||
- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
|
||||
|
||||
Note: Your choice will be the _primary_ style, but we'll use the other when it makes more sense for specific steps.</ask>
|
||||
|
||||
<action>Store instruction_style preference (intent-based or prescriptive)</action>
|
||||
<action>Explain that both styles have value and will be mixed appropriately</action>
|
||||
|
||||
Create a step outline with clear goals and outputs.
|
||||
<template-output>step_outline</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Create workflow.yaml">
|
||||
@@ -130,6 +239,7 @@ Replace all placeholders following the workflow creation guide conventions:
|
||||
Include:
|
||||
|
||||
- All metadata from steps 1-2
|
||||
- **Standalone property**: Use {{standalone_setting}} from step 2 (true or false)
|
||||
- Proper paths for installed_path using variable substitution
|
||||
- Template/instructions/validation paths based on workflow type:
|
||||
- Document workflow: all files (template, instructions, validation)
|
||||
@@ -151,6 +261,38 @@ date: system-generated
|
||||
|
||||
<critical>This standard config ensures workflows can run autonomously and communicate properly with users</critical>
|
||||
|
||||
<critical>ALWAYS include the standalone property:</critical>
|
||||
|
||||
```yaml
|
||||
standalone: { { standalone_setting } } # true or false from step 2
|
||||
```
|
||||
|
||||
**Example complete workflow.yaml structure**:
|
||||
|
||||
```yaml
|
||||
name: 'workflow-name'
|
||||
description: 'Clear purpose statement'
|
||||
|
||||
# Paths
|
||||
installed_path: '{project-root}/bmad/module/workflows/name'
|
||||
template: '{installed_path}/template.md'
|
||||
instructions: '{installed_path}/instructions.md'
|
||||
validation: '{installed_path}/checklist.md'
|
||||
|
||||
# Critical variables from config
|
||||
config_source: '{project-root}/bmad/module/config.yaml'
|
||||
output_folder: '{config_source}:output_folder'
|
||||
user_name: '{config_source}:user_name'
|
||||
communication_language: '{config_source}:communication_language'
|
||||
date: system-generated
|
||||
|
||||
# Output
|
||||
default_output_file: '{output_folder}/document.md'
|
||||
|
||||
# Invocation control
|
||||
standalone: true # or false based on step 2 decision
|
||||
```
|
||||
|
||||
Follow path conventions from guide:
|
||||
|
||||
- Use {project-root} for absolute paths
|
||||
|
||||
@@ -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
|
||||
@@ -395,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>
|
||||
```
|
||||
|
||||
@@ -441,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>
|
||||
```
|
||||
|
||||
@@ -463,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
|
||||
@@ -539,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:
|
||||
@@ -598,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'
|
||||
@@ -636,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:_
|
||||
|
||||
112
src/modules/bmb/workflows/edit-agent/README.md
Normal file
112
src/modules/bmb/workflows/edit-agent/README.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Edit Agent Workflow
|
||||
|
||||
Interactive workflow for editing existing BMAD Core agents while maintaining best practices and conventions.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow helps you refine and improve existing agents by:
|
||||
|
||||
- Analyzing agents against BMAD Core best practices
|
||||
- Identifying issues and improvement opportunities
|
||||
- Providing guided editing for specific aspects
|
||||
- Validating changes against agent standards
|
||||
- Ensuring consistency with agent architecture
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this workflow when you need to:
|
||||
|
||||
- Fix issues in existing agents
|
||||
- Add new menu items or workflows
|
||||
- Improve agent persona or communication style
|
||||
- Update configuration handling
|
||||
- Convert between agent types (full/hybrid/standalone)
|
||||
- Optimize agent structure and clarity
|
||||
|
||||
## What You'll Need
|
||||
|
||||
- Path to the agent file you want to edit (.yaml or .md)
|
||||
- Understanding of what changes you want to make
|
||||
- Access to the agent documentation (loaded automatically)
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
1. **Load and analyze target agent** - Provide path to agent file
|
||||
2. **Analyze against best practices** - Automatic audit of agent structure
|
||||
3. **Select editing focus** - Choose what aspect to edit
|
||||
4. **Load relevant documentation** - Auto-loads guides based on your choice
|
||||
5. **Perform edits** - Review and approve changes iteratively
|
||||
6. **Validate all changes** - Comprehensive validation checklist
|
||||
7. **Generate change summary** - Summary of improvements made
|
||||
|
||||
## Editing Options
|
||||
|
||||
The workflow provides 12 focused editing options:
|
||||
|
||||
1. **Fix critical issues** - Address broken references, syntax errors
|
||||
2. **Add/fix standard config** - Ensure config loading and variable usage
|
||||
3. **Refine persona** - Improve role, communication style, principles
|
||||
4. **Update activation** - Modify activation steps and greeting
|
||||
5. **Manage menu items** - Add, remove, or reorganize commands
|
||||
6. **Update workflow references** - Fix paths, add new workflows
|
||||
7. **Enhance menu handlers** - Improve handler logic
|
||||
8. **Improve command triggers** - Refine asterisk commands
|
||||
9. **Optimize agent type** - Convert between full/hybrid/standalone
|
||||
10. **Add new capabilities** - Add menu items, workflows, features
|
||||
11. **Remove bloat** - Delete unused commands, redundant instructions
|
||||
12. **Full review and update** - Comprehensive improvements
|
||||
|
||||
## Agent Documentation Loaded
|
||||
|
||||
This workflow automatically loads:
|
||||
|
||||
- **Agent Types Guide** - Understanding full, hybrid, and standalone agents
|
||||
- **Agent Architecture** - Structure, activation, and menu patterns
|
||||
- **Command Patterns** - Menu handlers and command triggers
|
||||
- **Communication Styles** - Persona and communication guidance
|
||||
- **Workflow Execution Engine** - How agents execute workflows
|
||||
|
||||
## Output
|
||||
|
||||
The workflow modifies your agent file in place, maintaining the original format (YAML or markdown). Changes are reviewed and approved by you before being applied.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start with analysis** - Let the workflow audit your agent first
|
||||
- **Focus your edits** - Choose specific aspects to improve
|
||||
- **Review each change** - Approve or modify proposed changes
|
||||
- **Validate thoroughly** - Use the validation step to catch issues
|
||||
- **Test after editing** - Invoke the edited agent to verify it works
|
||||
|
||||
## Tips
|
||||
|
||||
- If you're unsure what needs improvement, choose option 12 (Full review)
|
||||
- For quick fixes, choose the specific option (like option 6 for workflow paths)
|
||||
- The workflow loads documentation automatically - you don't need to read it first
|
||||
- You can make multiple rounds of edits in one session
|
||||
- Use the validation step to ensure you didn't miss anything
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- **create-agent** - Create new agents from scratch
|
||||
- **edit-workflow** - Edit workflows referenced by agents
|
||||
- **audit-workflow** - Audit workflows for compliance
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
User: I want to add a new workflow to the PM agent
|
||||
Workflow: Analyzes agent → Loads it → You choose option 5 (manage menu items)
|
||||
→ Adds new menu item with workflow reference → Validates → Done
|
||||
```
|
||||
|
||||
## Activation
|
||||
|
||||
Invoke via BMad Builder agent:
|
||||
|
||||
```
|
||||
/bmad:bmb:agents:bmad-builder
|
||||
Then select: *edit-agent
|
||||
```
|
||||
|
||||
Or directly via workflow.xml with this workflow config.
|
||||
112
src/modules/bmb/workflows/edit-agent/checklist.md
Normal file
112
src/modules/bmb/workflows/edit-agent/checklist.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Edit Agent - Validation Checklist
|
||||
|
||||
Use this checklist to validate agent edits meet BMAD Core standards.
|
||||
|
||||
## Agent Structure Validation
|
||||
|
||||
- [ ] Agent file format is valid (YAML or markdown/XML)
|
||||
- [ ] Agent type is clearly identified (full, hybrid, standalone)
|
||||
- [ ] File naming follows convention: `{agent-name}.agent.yaml` or `{agent-name}.agent.md`
|
||||
|
||||
## Persona Validation
|
||||
|
||||
- [ ] Role is clearly defined and specific
|
||||
- [ ] Identity/purpose articulates what the agent does
|
||||
- [ ] Communication style is specified (if custom style desired)
|
||||
- [ ] Principles are listed and actionable (if applicable)
|
||||
|
||||
## Activation Validation
|
||||
|
||||
- [ ] Step 1: Loads persona from current agent file
|
||||
- [ ] Step 2: Loads config file (if agent needs user context)
|
||||
- [ ] Step 3: Sets user context variables (user_name, etc.)
|
||||
- [ ] Step 4: Displays greeting using user_name and shows menu
|
||||
- [ ] Step 5: WAITs for user input (doesn't auto-execute)
|
||||
- [ ] Step 6: Processes user selection (number or trigger text)
|
||||
- [ ] Step 7: Executes appropriate menu handler
|
||||
|
||||
## Menu Validation
|
||||
|
||||
- [ ] All menu items numbered sequentially
|
||||
- [ ] Each item has cmd attribute with asterisk trigger (*help, *create, etc.)
|
||||
- [ ] Workflow paths are correct (if workflow attribute present)
|
||||
- [ ] Help command is present (\*help)
|
||||
- [ ] Exit command is present (\*exit)
|
||||
- [ ] Menu items are in logical order
|
||||
|
||||
## Configuration Validation
|
||||
|
||||
- [ ] Config file path is correct for module
|
||||
- [ ] Config variables loaded in activation step 2
|
||||
- [ ] Error handling present if config fails to load
|
||||
- [ ] user_name used in greeting and communication
|
||||
- [ ] communication_language used for output
|
||||
- [ ] output_folder used for file outputs (if applicable)
|
||||
|
||||
## Menu Handler Validation
|
||||
|
||||
- [ ] menu-handlers section is present
|
||||
- [ ] Workflow handler loads {project-root}/bmad/core/tasks/workflow.xml
|
||||
- [ ] Workflow handler passes yaml path as 'workflow-config' parameter
|
||||
- [ ] Handlers check for attributes (workflow, exec, tmpl, data, action)
|
||||
- [ ] Handler logic is complete and follows patterns
|
||||
|
||||
## Workflow Integration Validation
|
||||
|
||||
- [ ] All workflow paths exist and are correct
|
||||
- [ ] Workflow paths use {project-root} variable
|
||||
- [ ] Workflows are appropriate for agent's purpose
|
||||
- [ ] Workflow parameters are passed correctly
|
||||
|
||||
## Communication Validation
|
||||
|
||||
- [ ] Agent communicates in {communication_language}
|
||||
- [ ] Communication style matches persona
|
||||
- [ ] Error messages are clear and helpful
|
||||
- [ ] Confirmation messages for user actions
|
||||
|
||||
## Rules Validation
|
||||
|
||||
- [ ] Rules section defines agent behavior clearly
|
||||
- [ ] File loading rules are specified
|
||||
- [ ] Menu trigger format rules are clear
|
||||
- [ ] Communication rules align with persona
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, etc.)
|
||||
- [ ] No broken references or missing files
|
||||
- [ ] Syntax is valid (YAML or XML)
|
||||
- [ ] Indentation is consistent
|
||||
- [ ] Agent purpose is clear from reading persona alone
|
||||
|
||||
## Type-Specific Validation
|
||||
|
||||
### Full Agent
|
||||
|
||||
- [ ] Has complete menu system with multiple items
|
||||
- [ ] Loads config file for user context
|
||||
- [ ] Supports multiple workflows
|
||||
- [ ] Session management is clear
|
||||
|
||||
### Hybrid Agent
|
||||
|
||||
- [ ] Simplified activation (may skip some steps)
|
||||
- [ ] Focused set of workflows
|
||||
- [ ] May or may not have menu
|
||||
- [ ] Config loading is appropriate
|
||||
|
||||
### Standalone Agent
|
||||
|
||||
- [ ] Single focused purpose
|
||||
- [ ] Minimal activation (1-3 steps)
|
||||
- [ ] No menu system
|
||||
- [ ] Direct execution pattern
|
||||
- [ ] May not need config file
|
||||
|
||||
## Final Checks
|
||||
|
||||
- [ ] Agent file has been saved
|
||||
- [ ] File path is in correct module directory
|
||||
- [ ] Agent is ready for testing
|
||||
- [ ] Documentation is updated (if needed)
|
||||
290
src/modules/bmb/workflows/edit-agent/instructions.md
Normal file
290
src/modules/bmb/workflows/edit-agent/instructions.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# Edit Agent - Agent Editor Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
|
||||
<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and deeply understand the target agent">
|
||||
<ask>What is the path to the agent you want to edit?</ask>
|
||||
|
||||
<action>Load the agent file from the provided path</action>
|
||||
<action>Load ALL agent documentation to inform understanding:
|
||||
|
||||
- Agent types guide: {agent_types}
|
||||
- Agent architecture: {agent_architecture}
|
||||
- Command patterns: {agent_commands}
|
||||
- Communication styles: {communication_styles}
|
||||
- Workflow execution engine: {workflow_execution_engine}
|
||||
</action>
|
||||
|
||||
<action>Analyze the agent structure thoroughly:
|
||||
|
||||
- Parse persona (role, identity, communication_style, principles)
|
||||
- Understand activation flow and steps
|
||||
- Map menu items and their workflows
|
||||
- Identify configuration dependencies
|
||||
- Assess agent type (full, hybrid, standalone)
|
||||
- Check workflow references for validity
|
||||
- Evaluate against best practices from loaded guides
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
|
||||
Present a warm, conversational summary adapted to the agent's complexity:
|
||||
|
||||
- What this agent does (its role and purpose)
|
||||
- How it's structured (type, menu items, workflows)
|
||||
- What you notice (strengths, potential improvements, issues)
|
||||
- Your initial assessment of its health
|
||||
|
||||
Be conversational, not clinical. Help {user_name} see their agent through your eyes.
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of what this agent should do?</ask>
|
||||
<template-output>agent_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover improvement goals collaboratively">
|
||||
<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
|
||||
|
||||
<action>Engage in collaborative discovery:
|
||||
|
||||
Ask open-ended questions to understand their goals:
|
||||
|
||||
- What prompted you to want to edit this agent?
|
||||
- What isn't working the way you'd like?
|
||||
- Are there specific behaviors you want to change?
|
||||
- Is there functionality you want to add or remove?
|
||||
- How do users interact with this agent? What feedback have they given?
|
||||
|
||||
Listen for clues about:
|
||||
|
||||
- Functional issues (broken references, missing workflows)
|
||||
- User experience issues (confusing menu, unclear communication)
|
||||
- Performance issues (too slow, too verbose, not adaptive enough)
|
||||
- Maintenance issues (hard to update, bloated, inconsistent)
|
||||
- Integration issues (doesn't work well with other agents/workflows)
|
||||
</action>
|
||||
|
||||
<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
|
||||
|
||||
Organize by priority and user goals:
|
||||
|
||||
- CRITICAL issues blocking functionality
|
||||
- IMPORTANT improvements enhancing user experience
|
||||
- NICE-TO-HAVE enhancements for polish
|
||||
|
||||
Present these conversationally, explaining WHY each matters and HOW it would help.
|
||||
</action>
|
||||
|
||||
<action>Collaborate on priorities:
|
||||
|
||||
Don't just list options - discuss them:
|
||||
|
||||
- "I noticed {{issue}} - this could cause {{problem}}. Does this concern you?"
|
||||
- "The agent could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
|
||||
- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
|
||||
|
||||
Let the conversation flow naturally. Build a shared vision of what "better" looks like.
|
||||
</action>
|
||||
|
||||
<template-output>improvement_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
|
||||
<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
|
||||
|
||||
<action>For each improvement area, facilitate collaboratively:
|
||||
|
||||
1. **Explain the current state and why it matters**
|
||||
- Show relevant sections of the agent
|
||||
- Explain how it works now and implications
|
||||
- Connect to user's goals from step 2
|
||||
|
||||
2. **Propose improvements with rationale**
|
||||
- Suggest specific changes that align with best practices
|
||||
- Explain WHY each change helps
|
||||
- Provide examples from the loaded guides when helpful
|
||||
- Show before/after comparisons for clarity
|
||||
|
||||
3. **Collaborate on the approach**
|
||||
- Ask if the proposed change addresses their need
|
||||
- Invite modifications or alternative approaches
|
||||
- Explain tradeoffs when relevant
|
||||
- Adapt based on their feedback
|
||||
|
||||
4. **Apply changes iteratively**
|
||||
- Make one focused improvement at a time
|
||||
- Show the updated section
|
||||
- Confirm it meets their expectation
|
||||
- Move to next improvement or refine current one
|
||||
</action>
|
||||
|
||||
<action>Common improvement patterns to facilitate:
|
||||
|
||||
**If fixing broken references:**
|
||||
|
||||
- Identify all broken paths
|
||||
- Explain what each reference should point to
|
||||
- Verify new paths exist before updating
|
||||
- Update and confirm working
|
||||
|
||||
**If refining persona/communication:**
|
||||
|
||||
- Review current persona definition
|
||||
- Discuss desired communication style with examples
|
||||
- Explore communication styles guide for patterns
|
||||
- Refine language to match intent
|
||||
- Test tone with example interactions
|
||||
|
||||
**If updating activation:**
|
||||
|
||||
- Walk through current activation flow
|
||||
- Identify bottlenecks or confusion points
|
||||
- Propose streamlined flow
|
||||
- Ensure config loading works correctly
|
||||
- Verify all session variables are set
|
||||
|
||||
**If managing menu items:**
|
||||
|
||||
- Review current menu organization
|
||||
- Discuss if structure serves user mental model
|
||||
- Add/remove/reorganize as needed
|
||||
- Ensure all workflow references are valid
|
||||
- Update triggers to be intuitive
|
||||
|
||||
**If enhancing menu handlers:**
|
||||
|
||||
- Explain current handler logic
|
||||
- Identify where handlers could be smarter
|
||||
- Propose enhanced logic based on agent architecture patterns
|
||||
- Ensure handlers properly invoke workflows
|
||||
|
||||
**If optimizing agent type:**
|
||||
|
||||
- Discuss whether current type fits use case
|
||||
- Explain characteristics of full/hybrid/standalone
|
||||
- If converting, guide through structural changes
|
||||
- Ensure all pieces align with new type
|
||||
</action>
|
||||
|
||||
<action>Throughout improvements, educate when helpful:
|
||||
|
||||
Share insights from the guides naturally:
|
||||
|
||||
- "The agent architecture guide suggests {{pattern}} for this scenario"
|
||||
- "Looking at the command patterns, we could use {{approach}}"
|
||||
- "The communication styles guide has a great example of {{technique}}"
|
||||
|
||||
Connect improvements to broader BMAD principles without being preachy.
|
||||
</action>
|
||||
|
||||
<ask>After each significant change:
|
||||
|
||||
- "Does this feel right for what you're trying to achieve?"
|
||||
- "Want to refine this further, or move to the next improvement?"
|
||||
- "Is there anything about this change that concerns you?"
|
||||
</ask>
|
||||
|
||||
<template-output>improvement_implementation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Validate improvements holistically">
|
||||
<action>Run comprehensive validation conversationally:
|
||||
|
||||
Don't just check boxes - explain what you're validating and why it matters:
|
||||
|
||||
- "Let me verify all the workflow paths resolve correctly..."
|
||||
- "Checking that the activation flow works smoothly..."
|
||||
- "Making sure menu handlers are wired up properly..."
|
||||
- "Validating config loading is robust..."
|
||||
</action>
|
||||
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
<action>Check all items from checklist systematically</action>
|
||||
|
||||
<check if="validation_issues_found">
|
||||
<action>Present issues conversationally:
|
||||
|
||||
Explain what's wrong and implications:
|
||||
|
||||
- "I found {{issue}} which could cause {{problem}}"
|
||||
- "The {{component}} needs {{fix}} because {{reason}}"
|
||||
|
||||
Propose fixes immediately:
|
||||
|
||||
- "I can fix this by {{solution}}. Should I?"
|
||||
- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
|
||||
</action>
|
||||
|
||||
<action>Fix approved issues and re-validate</action>
|
||||
</check>
|
||||
|
||||
<check if="validation_passes">
|
||||
<action>Confirm success warmly:
|
||||
|
||||
"Excellent! Everything validates cleanly:
|
||||
|
||||
- All paths resolve correctly
|
||||
- Activation flow is solid
|
||||
- Menu structure is clear
|
||||
- Handlers work properly
|
||||
- Config loading is robust
|
||||
|
||||
Your agent is in great shape."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Review improvements and guide next steps">
|
||||
<action>Create a conversational summary of what improved:
|
||||
|
||||
Tell the story of the transformation:
|
||||
|
||||
- "We started with {{initial_state}}"
|
||||
- "You wanted to {{user_goals}}"
|
||||
- "We made these key improvements: {{changes_list}}"
|
||||
- "Now your agent {{improved_capabilities}}"
|
||||
|
||||
Highlight the impact:
|
||||
|
||||
- "This means users will experience {{benefit}}"
|
||||
- "The agent is now more {{quality}}"
|
||||
- "It follows best practices for {{patterns}}"
|
||||
</action>
|
||||
|
||||
<action>Guide next steps based on changes made:
|
||||
|
||||
If significant structural changes:
|
||||
|
||||
- "Since we restructured the activation, you should test the agent with a real user interaction"
|
||||
|
||||
If workflow references changed:
|
||||
|
||||
- "The agent now uses {{new_workflows}} - make sure those workflows are up to date"
|
||||
|
||||
If this is part of larger module work:
|
||||
|
||||
- "This agent is part of {{module}} - consider if other agents need similar improvements"
|
||||
|
||||
Be a helpful guide to what comes next, not just a task completer.
|
||||
</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- Test the edited agent by invoking it
|
||||
- Edit another agent
|
||||
- Make additional refinements to this one
|
||||
- Return to your module work
|
||||
</ask>
|
||||
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
35
src/modules/bmb/workflows/edit-agent/workflow.yaml
Normal file
35
src/modules/bmb/workflows/edit-agent/workflow.yaml
Normal file
@@ -0,0 +1,35 @@
|
||||
# Edit Agent - Agent Editor Configuration
|
||||
name: "edit-agent"
|
||||
description: "Edit existing BMAD agents while following all best practices and conventions"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables load from config_source
|
||||
config_source: "{project-root}/bmad/bmb/config.yaml"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_name: "{config_source}:user_name"
|
||||
|
||||
# Required Data Files - Critical for understanding agent conventions
|
||||
agent_types: "{project-root}/bmad/bmb/workflows/create-agent/agent-types.md"
|
||||
agent_architecture: "{project-root}/bmad/bmb/workflows/create-agent/agent-architecture.md"
|
||||
agent_commands: "{project-root}/bmad/bmb/workflows/create-agent/agent-command-patterns.md"
|
||||
communication_styles: "{project-root}/bmad/bmb/workflows/create-agent/communication-styles.md"
|
||||
|
||||
# Workflow execution engine reference
|
||||
workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
|
||||
|
||||
# Optional docs that can be used to understand the target agent
|
||||
recommended_inputs:
|
||||
- target_agent: "Path to the agent.yaml or agent.md file to edit"
|
||||
- example_agents: "{project-root}/bmad/bmm/agents/"
|
||||
- agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.xml"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmb/workflows/edit-agent"
|
||||
template: false # This is an action workflow - no template needed
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
standalone: true
|
||||
|
||||
# Web bundle configuration
|
||||
web_bundle: false # BMB workflows run locally in BMAD-METHOD project
|
||||
187
src/modules/bmb/workflows/edit-module/README.md
Normal file
187
src/modules/bmb/workflows/edit-module/README.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Edit Module Workflow
|
||||
|
||||
Interactive workflow for editing existing BMAD modules, including structure, agents, workflows, configuration, and documentation.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow helps you improve and maintain BMAD modules by:
|
||||
|
||||
- Analyzing module structure against best practices
|
||||
- Managing agents and workflows within the module
|
||||
- Updating configuration and documentation
|
||||
- Ensuring cross-module integration works correctly
|
||||
- Maintaining installer configuration (for source modules)
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this workflow when you need to:
|
||||
|
||||
- Add new agents or workflows to a module
|
||||
- Update module configuration
|
||||
- Improve module documentation
|
||||
- Reorganize module structure
|
||||
- Set up cross-module workflow sharing
|
||||
- Fix issues in module organization
|
||||
- Update installer configuration
|
||||
|
||||
## What You'll Need
|
||||
|
||||
- Path to the module directory you want to edit
|
||||
- Understanding of what changes you want to make
|
||||
- Access to module documentation (loaded automatically)
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
1. **Load and analyze target module** - Provide path to module directory
|
||||
2. **Analyze against best practices** - Automatic audit of module structure
|
||||
3. **Select editing focus** - Choose what aspect to edit
|
||||
4. **Load relevant documentation and tools** - Auto-loads guides and workflows
|
||||
5. **Perform edits** - Review and approve changes iteratively
|
||||
6. **Validate all changes** - Comprehensive validation checklist
|
||||
7. **Generate change summary** - Summary of improvements made
|
||||
|
||||
## Editing Options
|
||||
|
||||
The workflow provides 12 focused editing options:
|
||||
|
||||
1. **Fix critical issues** - Address missing files, broken references
|
||||
2. **Update module config** - Edit config.yaml fields
|
||||
3. **Manage agents** - Add, edit, or remove agents
|
||||
4. **Manage workflows** - Add, edit, or remove workflows
|
||||
5. **Update documentation** - Improve README files and guides
|
||||
6. **Reorganize structure** - Fix directory organization
|
||||
7. **Add new agent** - Create and integrate new agent
|
||||
8. **Add new workflow** - Create and integrate new workflow
|
||||
9. **Update installer** - Modify installer configuration (source only)
|
||||
10. **Cross-module integration** - Set up workflow sharing with other modules
|
||||
11. **Remove deprecated items** - Delete unused agents, workflows, or files
|
||||
12. **Full module review** - Comprehensive analysis and improvements
|
||||
|
||||
## Integration with Other Workflows
|
||||
|
||||
This workflow integrates with:
|
||||
|
||||
- **edit-agent** - For editing individual agents
|
||||
- **edit-workflow** - For editing individual workflows
|
||||
- **create-agent** - For adding new agents
|
||||
- **create-workflow** - For adding new workflows
|
||||
|
||||
When you select options to manage agents or workflows, the appropriate specialized workflow is invoked automatically.
|
||||
|
||||
## Module Structure
|
||||
|
||||
A proper BMAD module has:
|
||||
|
||||
```
|
||||
module-code/
|
||||
├── agents/ # Agent definitions
|
||||
│ └── *.agent.yaml
|
||||
├── workflows/ # Workflow definitions
|
||||
│ └── workflow-name/
|
||||
│ ├── workflow.yaml
|
||||
│ ├── instructions.md
|
||||
│ ├── checklist.md
|
||||
│ └── README.md
|
||||
├── config.yaml # Module configuration
|
||||
└── README.md # Module documentation
|
||||
```
|
||||
|
||||
## Standard Module Config
|
||||
|
||||
Every module config.yaml should have:
|
||||
|
||||
```yaml
|
||||
module_name: 'Full Module Name'
|
||||
module_code: 'xyz'
|
||||
user_name: 'User Name'
|
||||
communication_language: 'english'
|
||||
output_folder: 'path/to/output'
|
||||
```
|
||||
|
||||
Optional fields may be added for module-specific needs.
|
||||
|
||||
## Cross-Module Integration
|
||||
|
||||
Modules can share workflows:
|
||||
|
||||
```yaml
|
||||
# In agent menu item:
|
||||
workflow: '{project-root}/bmad/other-module/workflows/shared-workflow/workflow.yaml'
|
||||
```
|
||||
|
||||
Common patterns:
|
||||
|
||||
- BMM uses CIS brainstorming workflows
|
||||
- All modules can use core workflows
|
||||
- Modules can invoke each other's workflows
|
||||
|
||||
## Output
|
||||
|
||||
The workflow modifies module files in place, including:
|
||||
|
||||
- config.yaml
|
||||
- Agent files
|
||||
- Workflow files
|
||||
- README and documentation files
|
||||
- Directory structure (if reorganizing)
|
||||
|
||||
Changes are reviewed and approved by you before being applied.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start with analysis** - Let the workflow audit your module first
|
||||
- **Use specialized workflows** - Let edit-agent and edit-workflow handle detailed edits
|
||||
- **Update documentation** - Keep README files current with changes
|
||||
- **Validate thoroughly** - Use the validation step to catch structural issues
|
||||
- **Test after editing** - Invoke agents and workflows to verify they work
|
||||
|
||||
## Tips
|
||||
|
||||
- For adding agents/workflows, use options 7-8 to create and integrate in one step
|
||||
- For quick config changes, use option 2 (update module config)
|
||||
- Cross-module integration (option 10) helps set up workflow sharing
|
||||
- Full module review (option 12) is great for inherited or legacy modules
|
||||
- The workflow handles path updates when you reorganize structure
|
||||
|
||||
## Source vs Installed Modules
|
||||
|
||||
**Source modules** (in src/modules/):
|
||||
|
||||
- Have installer files in tools/cli/installers/
|
||||
- Can configure web bundles
|
||||
- Are the development source of truth
|
||||
|
||||
**Installed modules** (in bmad/):
|
||||
|
||||
- Are deployed to target projects
|
||||
- Use config.yaml for user customization
|
||||
- Are compiled from source during installation
|
||||
|
||||
This workflow works with both, but installer options only apply to source modules.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
User: I want to add a new workflow to BMM for API design
|
||||
Workflow: Analyzes BMM → You choose option 8 (add new workflow)
|
||||
→ Invokes create-workflow → Creates workflow
|
||||
→ Integrates it into module → Updates README → Done
|
||||
```
|
||||
|
||||
## Activation
|
||||
|
||||
Invoke via BMad Builder agent:
|
||||
|
||||
```
|
||||
/bmad:bmb:agents:bmad-builder
|
||||
Then select: *edit-module
|
||||
```
|
||||
|
||||
Or directly via workflow.xml with this workflow config.
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Module Structure Guide** - Comprehensive module architecture documentation
|
||||
- **BMM Module** - Example of full-featured module
|
||||
- **BMB Module** - Example of builder/tooling module
|
||||
- **CIS Module** - Example of workflow library module
|
||||
165
src/modules/bmb/workflows/edit-module/checklist.md
Normal file
165
src/modules/bmb/workflows/edit-module/checklist.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Edit Module - Validation Checklist
|
||||
|
||||
Use this checklist to validate module edits meet BMAD Core standards.
|
||||
|
||||
## Module Structure Validation
|
||||
|
||||
- [ ] Module has clear 3-letter code (bmm, bmb, cis, etc.)
|
||||
- [ ] Module is in correct location (src/modules/ for source, bmad/ for installed)
|
||||
- [ ] agents/ directory exists
|
||||
- [ ] workflows/ directory exists
|
||||
- [ ] config.yaml exists in module root
|
||||
- [ ] README.md exists in module root
|
||||
- [ ] Directory structure follows BMAD conventions
|
||||
|
||||
## Configuration Validation
|
||||
|
||||
### Required Fields
|
||||
|
||||
- [ ] module_name is descriptive and clear
|
||||
- [ ] module_code is 3-letter code matching directory name
|
||||
- [ ] user_name field present
|
||||
- [ ] communication_language field present
|
||||
- [ ] output_folder field present
|
||||
|
||||
### Optional Fields (if used)
|
||||
|
||||
- [ ] custom_agent_location documented
|
||||
- [ ] custom_module_location documented
|
||||
- [ ] Module-specific fields documented in README
|
||||
|
||||
### File Quality
|
||||
|
||||
- [ ] config.yaml is valid YAML syntax
|
||||
- [ ] No duplicate keys
|
||||
- [ ] Values are appropriate types (strings, paths, etc.)
|
||||
- [ ] Comments explain non-obvious fields
|
||||
|
||||
## Agent Validation
|
||||
|
||||
### Agent Files
|
||||
|
||||
- [ ] All agents in agents/ directory
|
||||
- [ ] Agent files follow naming: {agent-name}.agent.yaml or .md
|
||||
- [ ] Agent filenames use kebab-case
|
||||
- [ ] No orphaned or temporary agent files
|
||||
|
||||
### Agent Content
|
||||
|
||||
- [ ] Each agent has clear role and purpose
|
||||
- [ ] Agents reference workflows correctly
|
||||
- [ ] Agent workflow paths are valid
|
||||
- [ ] Agents load module config correctly (if needed)
|
||||
- [ ] Agent menu items reference existing workflows
|
||||
|
||||
### Agent Integration
|
||||
|
||||
- [ ] All agents listed in module README
|
||||
- [ ] Agent relationships documented (if applicable)
|
||||
- [ ] Cross-agent workflows properly linked
|
||||
|
||||
## Workflow Validation
|
||||
|
||||
### Workflow Structure
|
||||
|
||||
- [ ] All workflows in workflows/ directory
|
||||
- [ ] Each workflow directory has workflow.yaml
|
||||
- [ ] Each workflow directory has instructions.md
|
||||
- [ ] Workflow directories use kebab-case naming
|
||||
- [ ] No orphaned or incomplete workflow directories
|
||||
|
||||
### Workflow Content
|
||||
|
||||
- [ ] workflow.yaml is valid YAML
|
||||
- [ ] workflow.yaml has name field
|
||||
- [ ] workflow.yaml has description field
|
||||
- [ ] workflow.yaml has author field
|
||||
- [ ] instructions.md has proper <workflow> structure
|
||||
- [ ] Workflow steps are numbered and logical
|
||||
|
||||
### Workflow Integration
|
||||
|
||||
- [ ] All workflows listed in module README
|
||||
- [ ] Workflow paths in agents are correct
|
||||
- [ ] Cross-module workflow references are valid
|
||||
- [ ] Sub-workflow references exist
|
||||
|
||||
## Documentation Validation
|
||||
|
||||
### Module README
|
||||
|
||||
- [ ] Module README describes purpose clearly
|
||||
- [ ] README lists all agents with descriptions
|
||||
- [ ] README lists all workflows with descriptions
|
||||
- [ ] README includes installation instructions (if applicable)
|
||||
- [ ] README explains module's role in BMAD ecosystem
|
||||
|
||||
### Workflow READMEs
|
||||
|
||||
- [ ] Each workflow has its own README.md
|
||||
- [ ] Workflow READMEs explain purpose
|
||||
- [ ] Workflow READMEs list inputs/outputs
|
||||
- [ ] Workflow READMEs include usage examples
|
||||
|
||||
### Other Documentation
|
||||
|
||||
- [ ] Usage guides present (if needed)
|
||||
- [ ] Architecture docs present (if complex module)
|
||||
- [ ] Examples provided (if applicable)
|
||||
|
||||
## Cross-References Validation
|
||||
|
||||
- [ ] Agent workflow references point to existing workflows
|
||||
- [ ] Workflow sub-workflow references are valid
|
||||
- [ ] Cross-module references use correct paths
|
||||
- [ ] Config file paths use {project-root} correctly
|
||||
- [ ] No hardcoded absolute paths
|
||||
|
||||
## Installer Validation (Source Modules Only)
|
||||
|
||||
- [ ] Installer script exists in tools/cli/installers/
|
||||
- [ ] Installer script name: install-{module-code}.js
|
||||
- [ ] Module metadata in installer is correct
|
||||
- [ ] Web bundle configuration valid (if applicable)
|
||||
- [ ] Installation paths are correct
|
||||
- [ ] Dependencies documented in installer
|
||||
|
||||
## Web Bundle Validation (If Applicable)
|
||||
|
||||
- [ ] Web bundles configured in workflow.yaml files
|
||||
- [ ] All referenced files included in web_bundle_files
|
||||
- [ ] Paths are bmad/-relative (not project-root)
|
||||
- [ ] No config_source references in web bundles
|
||||
- [ ] Invoked workflows included in dependencies
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No placeholder text remains ({MODULE_NAME}, {CODE}, etc.)
|
||||
- [ ] No broken file references
|
||||
- [ ] No duplicate content across files
|
||||
- [ ] Consistent naming conventions throughout
|
||||
- [ ] Module purpose is clear from README alone
|
||||
|
||||
## Integration Checks
|
||||
|
||||
- [ ] Module doesn't conflict with other modules
|
||||
- [ ] Shared resources properly documented
|
||||
- [ ] Dependencies on other modules explicit
|
||||
- [ ] Module can be installed independently (if designed that way)
|
||||
|
||||
## User Experience
|
||||
|
||||
- [ ] Module purpose is immediately clear
|
||||
- [ ] Agents have intuitive names
|
||||
- [ ] Workflows have descriptive names
|
||||
- [ ] Menu items are logically organized
|
||||
- [ ] Error messages are helpful
|
||||
- [ ] Success messages confirm actions
|
||||
|
||||
## Final Checks
|
||||
|
||||
- [ ] All files have been saved
|
||||
- [ ] File permissions are correct
|
||||
- [ ] Git status shows expected changes
|
||||
- [ ] Module is ready for testing
|
||||
- [ ] Documentation accurately reflects changes
|
||||
339
src/modules/bmb/workflows/edit-module/instructions.md
Normal file
339
src/modules/bmb/workflows/edit-module/instructions.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# Edit Module - Module Editor Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-module/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
|
||||
<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and deeply understand the target module">
|
||||
<ask>What is the path to the module you want to edit? (provide path to module directory like bmad/bmm/ or src/modules/bmm/)</ask>
|
||||
|
||||
<action>Load the module directory structure completely:
|
||||
|
||||
- Scan all directories and files
|
||||
- Load config.yaml
|
||||
- Load README.md
|
||||
- List all agents in agents/ directory
|
||||
- List all workflows in workflows/ directory
|
||||
- Check for installer files (if in src/modules/)
|
||||
- Identify any custom structure or patterns
|
||||
</action>
|
||||
|
||||
<action>Load ALL module documentation to inform understanding:
|
||||
|
||||
- Module structure guide: {module_structure_guide}
|
||||
- Study reference modules: BMM, BMB, CIS
|
||||
- Understand BMAD module patterns and conventions
|
||||
</action>
|
||||
|
||||
<action>Analyze the module deeply:
|
||||
|
||||
- Identify module purpose and role in BMAD ecosystem
|
||||
- Understand agent organization and relationships
|
||||
- Map workflow organization and dependencies
|
||||
- Evaluate config structure and completeness
|
||||
- Check documentation quality and currency
|
||||
- Assess installer configuration (if source module)
|
||||
- Identify cross-module integrations
|
||||
- Evaluate against best practices from loaded guides
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
|
||||
Present a warm, conversational summary adapted to the module's complexity:
|
||||
|
||||
- What this module provides (its purpose and value in BMAD)
|
||||
- How it's organized (agents, workflows, structure)
|
||||
- What you notice (strengths, potential improvements, issues)
|
||||
- How it fits in the larger BMAD ecosystem
|
||||
- Your initial assessment based on best practices
|
||||
|
||||
Be conversational and insightful. Help {user_name} see their module through your eyes.
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of what this module should provide?</ask>
|
||||
<template-output>module_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover improvement goals collaboratively">
|
||||
<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
|
||||
|
||||
<action>Engage in collaborative discovery:
|
||||
|
||||
Ask open-ended questions to understand their goals:
|
||||
|
||||
- What prompted you to want to edit this module?
|
||||
- What feedback have you gotten from users of this module?
|
||||
- Are there specific agents or workflows that need attention?
|
||||
- Is the module fulfilling its intended purpose?
|
||||
- Are there new capabilities you want to add?
|
||||
- How well does it integrate with other modules?
|
||||
- Is the documentation helping users understand and use the module?
|
||||
|
||||
Listen for clues about:
|
||||
|
||||
- Structural issues (poor organization, hard to navigate)
|
||||
- Agent/workflow issues (outdated, broken, missing functionality)
|
||||
- Configuration issues (missing fields, incorrect setup)
|
||||
- Documentation issues (outdated, incomplete, unclear)
|
||||
- Integration issues (doesn't work well with other modules)
|
||||
- Installer issues (installation problems, missing files)
|
||||
- User experience issues (confusing, hard to use)
|
||||
</action>
|
||||
|
||||
<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
|
||||
|
||||
Organize by priority and user goals:
|
||||
|
||||
- CRITICAL issues blocking module functionality
|
||||
- IMPORTANT improvements enhancing user experience
|
||||
- NICE-TO-HAVE enhancements for polish
|
||||
|
||||
Present these conversationally, explaining WHY each matters and HOW it would help.
|
||||
</action>
|
||||
|
||||
<action>Collaborate on priorities:
|
||||
|
||||
Don't just list options - discuss them:
|
||||
|
||||
- "I noticed {{issue}} - this could make it hard for users to {{problem}}. Want to address this?"
|
||||
- "The module could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
|
||||
- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
|
||||
|
||||
Let the conversation flow naturally. Build a shared vision of what "better" looks like.
|
||||
</action>
|
||||
|
||||
<template-output>improvement_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
|
||||
<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
|
||||
<critical>For agent and workflow edits, invoke specialized workflows rather than doing inline</critical>
|
||||
|
||||
<action>For each improvement area, facilitate collaboratively:
|
||||
|
||||
1. **Explain the current state and why it matters**
|
||||
- Show relevant sections of the module
|
||||
- Explain how it works now and implications
|
||||
- Connect to user's goals from step 2
|
||||
|
||||
2. **Propose improvements with rationale**
|
||||
- Suggest specific changes that align with best practices
|
||||
- Explain WHY each change helps
|
||||
- Provide examples from reference modules when helpful
|
||||
- Reference the structure guide's patterns naturally
|
||||
|
||||
3. **Collaborate on the approach**
|
||||
- Ask if the proposed change addresses their need
|
||||
- Invite modifications or alternative approaches
|
||||
- Explain tradeoffs when relevant
|
||||
- Adapt based on their feedback
|
||||
|
||||
4. **Apply changes appropriately**
|
||||
- For agent edits: Invoke edit-agent workflow
|
||||
- For workflow edits: Invoke edit-workflow workflow
|
||||
- For module-level changes: Make directly and iteratively
|
||||
- Show updates and confirm satisfaction
|
||||
</action>
|
||||
|
||||
<action>Common improvement patterns to facilitate:
|
||||
|
||||
**If improving module organization:**
|
||||
|
||||
- Discuss how the current structure serves (or doesn't serve) users
|
||||
- Propose reorganization that aligns with mental models
|
||||
- Consider feature-based vs type-based organization
|
||||
- Plan the reorganization steps
|
||||
- Update all references after moving files
|
||||
|
||||
**If updating module configuration:**
|
||||
|
||||
- Review current config.yaml fields
|
||||
- Check for missing standard fields (user_name, communication_language, output_folder)
|
||||
- Add module-specific fields as needed
|
||||
- Remove unused or outdated fields
|
||||
- Ensure config is properly documented
|
||||
|
||||
**If managing agents:**
|
||||
|
||||
- Ask which agent needs attention and why
|
||||
- For editing existing agent: <invoke-workflow path="{agent_editor}">
|
||||
- For adding new agent: Guide creation and integration
|
||||
- For removing agent: Confirm, remove, update references
|
||||
- Ensure all agent references in workflows remain valid
|
||||
|
||||
**If managing workflows:**
|
||||
|
||||
- Ask which workflow needs attention and why
|
||||
- For editing existing workflow: <invoke-workflow path="{workflow_editor}">
|
||||
- For adding new workflow: Guide creation and integration
|
||||
- For removing workflow: Confirm, remove, update agent references
|
||||
- Ensure all workflow files are properly organized
|
||||
|
||||
**If improving documentation:**
|
||||
|
||||
- Review current README and identify gaps
|
||||
- Discuss what users need to know
|
||||
- Update module overview and purpose
|
||||
- List agents and workflows with clear descriptions
|
||||
- Add usage examples if helpful
|
||||
- Ensure installation/setup instructions are clear
|
||||
|
||||
**If setting up cross-module integration:**
|
||||
|
||||
- Identify which workflows from other modules are needed
|
||||
- Show how to reference workflows properly: {project-root}/bmad/{{module}}/workflows/{{workflow}}/workflow.yaml
|
||||
- Document the integration in README
|
||||
- Ensure dependencies are clear
|
||||
- Consider adding example usage
|
||||
|
||||
**If updating installer (source modules only):**
|
||||
|
||||
- Review installer script for correctness
|
||||
- Check web bundle configurations
|
||||
- Verify all files are included
|
||||
- Test installation paths
|
||||
- Update module metadata
|
||||
</action>
|
||||
|
||||
<action>When invoking specialized workflows:
|
||||
|
||||
Explain why you're handing off:
|
||||
|
||||
- "This agent needs detailed attention. Let me invoke the edit-agent workflow to give it proper focus."
|
||||
- "The workflow editor can handle this more thoroughly. I'll pass control there."
|
||||
|
||||
After the specialized workflow completes, return and continue:
|
||||
|
||||
- "Great! That agent/workflow is updated. Want to work on anything else in the module?"
|
||||
</action>
|
||||
|
||||
<action>Throughout improvements, educate when helpful:
|
||||
|
||||
Share insights from the guides naturally:
|
||||
|
||||
- "The module structure guide recommends {{pattern}} for this scenario"
|
||||
- "Looking at how BMM organized this, we could use {{approach}}"
|
||||
- "The BMAD convention is to {{pattern}} which helps with {{benefit}}"
|
||||
|
||||
Connect improvements to broader BMAD principles without being preachy.
|
||||
</action>
|
||||
|
||||
<ask>After each significant change:
|
||||
|
||||
- "Does this organization feel more intuitive?"
|
||||
- "Want to refine this further, or move to the next improvement?"
|
||||
- "How does this change affect users of the module?"
|
||||
</ask>
|
||||
|
||||
<template-output>improvement_implementation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Validate improvements holistically">
|
||||
<action>Run comprehensive validation conversationally:
|
||||
|
||||
Don't just check boxes - explain what you're validating and why it matters:
|
||||
|
||||
- "Let me verify the module structure is solid..."
|
||||
- "Checking that all agent workflow references are valid..."
|
||||
- "Making sure config.yaml has all necessary fields..."
|
||||
- "Validating documentation is complete and accurate..."
|
||||
- "Ensuring cross-module references work correctly..."
|
||||
</action>
|
||||
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
<action>Check all items from checklist systematically</action>
|
||||
|
||||
<check if="validation_issues_found">
|
||||
<action>Present issues conversationally:
|
||||
|
||||
Explain what's wrong and implications:
|
||||
|
||||
- "I found {{issue}} which could cause {{problem}} for users"
|
||||
- "The {{component}} needs {{fix}} because {{reason}}"
|
||||
|
||||
Propose fixes immediately:
|
||||
|
||||
- "I can fix this by {{solution}}. Should I?"
|
||||
- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
|
||||
</action>
|
||||
|
||||
<action>Fix approved issues and re-validate</action>
|
||||
</check>
|
||||
|
||||
<check if="validation_passes">
|
||||
<action>Confirm success warmly:
|
||||
|
||||
"Excellent! Everything validates cleanly:
|
||||
|
||||
- Module structure is well-organized
|
||||
- All agent and workflow references are valid
|
||||
- Configuration is complete
|
||||
- Documentation is thorough and current
|
||||
- Cross-module integrations work properly
|
||||
- Installer is correct (if applicable)
|
||||
|
||||
Your module is in great shape."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Review improvements and guide next steps">
|
||||
<action>Create a conversational summary of what improved:
|
||||
|
||||
Tell the story of the transformation:
|
||||
|
||||
- "We started with {{initial_state}}"
|
||||
- "You wanted to {{user_goals}}"
|
||||
- "We made these key improvements: {{changes_list}}"
|
||||
- "Now your module {{improved_capabilities}}"
|
||||
|
||||
Highlight the impact:
|
||||
|
||||
- "This means users will experience {{benefit}}"
|
||||
- "The module is now more {{quality}}"
|
||||
- "It follows best practices for {{patterns}}"
|
||||
</action>
|
||||
|
||||
<action>Guide next steps based on changes made:
|
||||
|
||||
If structure changed significantly:
|
||||
|
||||
- "Since we reorganized the structure, you should update any external references to this module"
|
||||
|
||||
If agents or workflows were updated:
|
||||
|
||||
- "The updated agents/workflows should be tested with real user interactions"
|
||||
|
||||
If cross-module integration was added:
|
||||
|
||||
- "Test the integration with {{other_module}} to ensure it works smoothly"
|
||||
|
||||
If installer was updated:
|
||||
|
||||
- "Test the installation process to verify all files are included correctly"
|
||||
|
||||
If this is part of larger BMAD work:
|
||||
|
||||
- "Consider if patterns from this module could benefit other modules"
|
||||
|
||||
Be a helpful guide to what comes next, not just a task completer.
|
||||
</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- Test the edited module by invoking one of its agents
|
||||
- Edit a specific agent or workflow in more detail
|
||||
- Make additional refinements to the module
|
||||
- Work on a different module
|
||||
</ask>
|
||||
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
36
src/modules/bmb/workflows/edit-module/workflow.yaml
Normal file
36
src/modules/bmb/workflows/edit-module/workflow.yaml
Normal file
@@ -0,0 +1,36 @@
|
||||
# Edit Module - Module Editor Configuration
|
||||
name: "edit-module"
|
||||
description: "Edit existing BMAD modules (structure, agents, workflows, documentation) while following all best practices"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables load from config_source
|
||||
config_source: "{project-root}/bmad/bmb/config.yaml"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_name: "{config_source}:user_name"
|
||||
|
||||
# Required Data Files - Critical for understanding module conventions
|
||||
module_structure_guide: "{project-root}/bmad/bmb/workflows/create-module/module-structure.md"
|
||||
|
||||
# Related workflow editors
|
||||
agent_editor: "{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml"
|
||||
workflow_editor: "{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml"
|
||||
|
||||
# Optional docs that can be used to understand the target module
|
||||
recommended_inputs:
|
||||
- target_module: "Path to the module directory to edit"
|
||||
- bmm_module: "{project-root}/bmad/bmm/"
|
||||
- bmb_module: "{project-root}/bmad/bmb/"
|
||||
- cis_module: "{project-root}/bmad/cis/"
|
||||
- existing_agents: "{project-root}/bmad/*/agents/"
|
||||
- existing_workflows: "{project-root}/bmad/*/workflows/"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmb/workflows/edit-module"
|
||||
template: false # This is an action workflow - no template needed
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
standalone: true
|
||||
|
||||
# Web bundle configuration
|
||||
web_bundle: false # BMB workflows run locally in BMAD-METHOD project
|
||||
@@ -2,404 +2,341 @@
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml</critical>
|
||||
<critical>Study the workflow creation guide thoroughly at: {workflow_creation_guide}</critical>
|
||||
<critical>Communicate in {communication_language} throughout the workflow editing process</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
|
||||
<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and analyze target workflow">
|
||||
<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow folder)</ask>
|
||||
<step n="1" goal="Load and deeply understand the target workflow">
|
||||
<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow directory)</ask>
|
||||
|
||||
<action>Load the workflow.yaml file from the provided path</action>
|
||||
<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
|
||||
<action>List all associated files (template.md, instructions.md, checklist.md, data files)</action>
|
||||
<action>Load any existing instructions.md and template.md files if present</action>
|
||||
<action>Load the target workflow completely:
|
||||
|
||||
Display a summary:
|
||||
|
||||
- Workflow name and description
|
||||
- Type of workflow
|
||||
- Files present
|
||||
- Current structure overview
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Analyze against best practices">
|
||||
<action>Load the complete workflow creation guide from: {workflow_creation_guide}</action>
|
||||
<action>Check the workflow against the guide's best practices:</action>
|
||||
|
||||
Analyze for:
|
||||
|
||||
- **Critical headers**: Are workflow engine references present?
|
||||
- **File structure**: Are all expected files present for this workflow type?
|
||||
- **Variable consistency**: Do variable names match between files?
|
||||
- **Step structure**: Are steps properly numbered and focused?
|
||||
- **XML tags**: Are tags used correctly and consistently?
|
||||
- **Instructions clarity**: Are instructions specific with examples and limits?
|
||||
- **Template variables**: Use snake_case and descriptive names?
|
||||
- **Validation criteria**: Are checklist items measurable and specific?
|
||||
|
||||
**Standard Config Audit:**
|
||||
|
||||
- **workflow.yaml config block**: Check for standard config variables
|
||||
- Is config_source defined?
|
||||
- Are output_folder, user_name, communication_language pulled from config?
|
||||
- Is date set to system-generated?
|
||||
- **Instructions usage**: Do instructions use config variables?
|
||||
- Does it communicate in {communication_language}?
|
||||
- Does it address {user_name}?
|
||||
- Does it write to {output_folder}?
|
||||
- **Template usage**: Does template.md include config variables in metadata?
|
||||
|
||||
**YAML/File Alignment:**
|
||||
|
||||
- **Unused yaml fields**: Are there variables in workflow.yaml not used in instructions OR template?
|
||||
- **Missing variables**: Are there hardcoded values that should be variables?
|
||||
- **Web bundle completeness**: If web_bundle exists, does it include all dependencies?
|
||||
- All referenced files listed?
|
||||
- Called workflows included?
|
||||
|
||||
<action>Create a list of identified issues or improvement opportunities</action>
|
||||
<action>Prioritize issues by importance (critical, important, nice-to-have)</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Select editing focus">
|
||||
Present the editing menu to the user:
|
||||
|
||||
**What aspect would you like to edit?**
|
||||
|
||||
1. **Fix critical issues** - Address missing headers, broken references
|
||||
2. **Add/fix standard config** - Ensure standard config block and variable usage
|
||||
3. **Update workflow.yaml** - Modify configuration, paths, metadata
|
||||
4. **Refine instructions** - Improve steps, add detail, fix flow
|
||||
5. **Update template** - Fix variables, improve structure (if applicable)
|
||||
6. **Enhance validation** - Make checklist more specific and measurable
|
||||
7. **Add new features** - Add steps, optional sections, or capabilities
|
||||
8. **Configure web bundle** - Add/update web bundle for deployment
|
||||
9. **Remove bloat** - Delete unused yaml fields, duplicate values
|
||||
10. **Optimize for clarity** - Improve descriptions, add examples
|
||||
11. **Adjust instruction style** - Convert between intent-based and prescriptive styles
|
||||
12. **Full review and update** - Comprehensive improvements across all files
|
||||
|
||||
<ask>Select an option (1-12) or describe a custom edit:</ask>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Load relevant documentation">
|
||||
Based on the selected edit type, load appropriate reference materials:
|
||||
|
||||
<check if="option 2 (Add/fix standard config) selected">
|
||||
<action>Prepare standard config block template:</action>
|
||||
|
||||
```yaml
|
||||
# Critical variables from config
|
||||
config_source: '{project-root}/bmad/{module}/config.yaml'
|
||||
output_folder: '{config_source}:output_folder'
|
||||
user_name: '{config_source}:user_name'
|
||||
communication_language: '{config_source}:communication_language'
|
||||
date: system-generated
|
||||
```
|
||||
|
||||
<action>Check if workflow.yaml has existing config section (don't duplicate)</action>
|
||||
<action>Identify missing config variables to add</action>
|
||||
<action>Check instructions.md for config variable usage</action>
|
||||
<action>Check template.md for config variable usage</action>
|
||||
</check>
|
||||
|
||||
<check if="editing instructions or adding features">
|
||||
<action>Review the "Writing Instructions" section of the creation guide</action>
|
||||
<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
|
||||
</check>
|
||||
|
||||
<check if="editing templates">
|
||||
<action>Review the "Templates and Variables" section of the creation guide</action>
|
||||
<action>Ensure variable naming conventions are followed</action>
|
||||
</check>
|
||||
|
||||
<action if="editing validation">Review the "Validation" section and measurable criteria examples</action>
|
||||
|
||||
<check if="option 9 (Remove bloat) selected">
|
||||
<action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
|
||||
<action>Identify yaml fields not used in any file</action>
|
||||
<action>Check for duplicate fields in web_bundle section</action>
|
||||
</check>
|
||||
|
||||
<check if="configuring web bundle">
|
||||
<action>Review the "Web Bundles" section of the creation guide</action>
|
||||
<action>Scan all workflow files for referenced resources</action>
|
||||
<action>Create inventory of all files that must be included</action>
|
||||
<action>Scan instructions for invoke-workflow calls - those yamls must be included</action>
|
||||
</check>
|
||||
|
||||
<check if="fixing critical issues">
|
||||
<action>Load the workflow execution engine documentation</action>
|
||||
<action>Verify all required elements are present</action>
|
||||
</check>
|
||||
|
||||
<check if="adjusting instruction style (option 11) selected">
|
||||
<action>Analyze current instruction style in instructions.md:</action>
|
||||
|
||||
- Count action tags vs ask tags
|
||||
- Identify goal-oriented language ("guide", "explore", "help") vs prescriptive ("choose", "select", "specify")
|
||||
- Assess whether steps are open-ended or structured with specific options
|
||||
<action>Determine current dominant style: intent-based, prescriptive, or mixed</action>
|
||||
<action>Load the instruction style guide section from create-workflow</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Perform edits" repeat="until-complete">
|
||||
Based on the selected focus area:
|
||||
|
||||
<check if="configuring web bundle (option 7) selected">
|
||||
<action>Check if web_bundle section exists in workflow.yaml</action>
|
||||
|
||||
If creating new web bundle:
|
||||
|
||||
1. Extract workflow metadata (name, description, author)
|
||||
2. Convert all file paths to bmad/-relative format
|
||||
3. Remove any {config_source} references
|
||||
4. Scan instructions.md for all file references:
|
||||
- Data files (CSV, JSON)
|
||||
- Sub-workflows
|
||||
- Shared templates
|
||||
- Any included files
|
||||
5. Scan template.md for any includes
|
||||
6. Create complete web_bundle_files array
|
||||
7. **CRITICAL**: Check for invoke-workflow calls in instructions:
|
||||
- If workflow invokes other workflows, add existing_workflows field
|
||||
- Maps workflow variable name to bmad/-relative path
|
||||
- Signals bundler to recursively include invoked workflow's web_bundle
|
||||
- Example: `existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"`
|
||||
8. Generate web_bundle section
|
||||
|
||||
If updating existing web bundle:
|
||||
|
||||
1. Verify all paths are bmad/-relative
|
||||
2. Check for missing files in web_bundle_files
|
||||
3. Remove any config dependencies
|
||||
4. Update file list with newly referenced files
|
||||
</check>
|
||||
|
||||
<check if="adjusting instruction style (option 11) selected">
|
||||
<action>Present current style analysis to user:</action>
|
||||
|
||||
**Current Instruction Style Analysis:**
|
||||
|
||||
- Current dominant style: {{detected_style}}
|
||||
- Intent-based elements: {{intent_count}}
|
||||
- Prescriptive elements: {{prescriptive_count}}
|
||||
|
||||
**Understanding Intent-Based vs Prescriptive:**
|
||||
|
||||
**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
|
||||
|
||||
- More flexible and conversational
|
||||
- LLM chooses appropriate questions based on context
|
||||
- Better for complex discovery and iterative refinement
|
||||
- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
|
||||
|
||||
**2. Prescriptive** - Provide exact wording for questions and options
|
||||
|
||||
- More controlled and predictable
|
||||
- Ensures consistency across runs
|
||||
- Better for simple data collection or specific compliance needs
|
||||
- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
|
||||
|
||||
**When to use Intent-Based:**
|
||||
|
||||
- Complex discovery processes (user research, requirements gathering)
|
||||
- Creative brainstorming and ideation
|
||||
- Iterative refinement workflows
|
||||
- When user input quality matters more than consistency
|
||||
- Workflows requiring adaptation to context
|
||||
|
||||
**When to use Prescriptive:**
|
||||
|
||||
- Simple data collection (platform, format, yes/no choices)
|
||||
- Compliance verification and standards adherence
|
||||
- Configuration with finite options
|
||||
- When consistency is critical across all executions
|
||||
- Quick setup wizards
|
||||
|
||||
**Best Practice: Mix Both Styles**
|
||||
|
||||
Even workflows with a primary style should use the other when appropriate. For example:
|
||||
|
||||
```xml
|
||||
<!-- Intent-based workflow with prescriptive moments -->
|
||||
<step n="1" goal="Understand user vision">
|
||||
<action>Explore the user's vision, uncovering their creative intent and target experience</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Capture basic metadata">
|
||||
<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask> <!-- Prescriptive for simple choice -->
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Deep dive into details">
|
||||
<action>Guide user to articulate their approach, exploring mechanics and unique aspects</action> <!-- Back to intent-based -->
|
||||
</step>
|
||||
```
|
||||
|
||||
<ask>What would you like to do?
|
||||
|
||||
1. **Make more intent-based** - Convert prescriptive ask tags to goal-oriented action tags where appropriate
|
||||
2. **Make more prescriptive** - Convert open-ended action tags to specific ask tags with options
|
||||
3. **Optimize mix** - Use intent-based for complex steps, prescriptive for simple data collection
|
||||
4. **Review specific steps** - Show me each step and let me decide individually
|
||||
5. **Cancel** - Keep current style
|
||||
|
||||
Select option (1-5):</ask>
|
||||
|
||||
<action>Store user's style adjustment preference as {{style_adjustment_choice}}</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 1 (make more intent-based)">
|
||||
<action>Identify prescriptive ask tags that could be converted to intent-based action tags</action>
|
||||
<action>For each candidate conversion:
|
||||
|
||||
- Show original prescriptive version
|
||||
- Suggest intent-based alternative focused on goals
|
||||
- Explain the benefit of the conversion
|
||||
- Ask for approval
|
||||
- workflow.yaml configuration
|
||||
- instructions.md (if exists)
|
||||
- template.md (if exists)
|
||||
- checklist.md (if exists)
|
||||
- Any additional data files referenced
|
||||
</action>
|
||||
<action>Apply approved conversions</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 2 (make more prescriptive)">
|
||||
<action>Identify open-ended action tags that could be converted to prescriptive ask tags</action>
|
||||
<action>For each candidate conversion:
|
||||
<action>Load ALL workflow documentation to inform understanding:
|
||||
|
||||
- Show original intent-based version
|
||||
- Suggest prescriptive alternative with specific options
|
||||
- Explain when prescriptive is better here
|
||||
- Ask for approval
|
||||
- Workflow creation guide: {workflow_creation_guide}
|
||||
- Workflow execution engine: {workflow_execution_engine}
|
||||
- Study example workflows from: {project-root}/bmad/bmm/workflows/
|
||||
</action>
|
||||
<action>Apply approved conversions</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 3 (optimize mix)">
|
||||
<action>Analyze each step for complexity and purpose</action>
|
||||
<action>Recommend style for each step:
|
||||
<action>Analyze the workflow deeply:
|
||||
|
||||
- Simple data collection → Prescriptive
|
||||
- Complex discovery → Intent-based
|
||||
- Binary decisions → Prescriptive
|
||||
- Creative exploration → Intent-based
|
||||
- Standards/compliance → Prescriptive
|
||||
- Iterative refinement → Intent-based
|
||||
- Identify workflow type (document, action, interactive, autonomous, meta)
|
||||
- Understand purpose and user journey
|
||||
- Map out step flow and logic
|
||||
- Check variable consistency across files
|
||||
- Evaluate instruction style (intent-based vs prescriptive)
|
||||
- Assess template structure (if applicable)
|
||||
- Review validation criteria
|
||||
- Identify config dependencies
|
||||
- Check for web bundle configuration
|
||||
- Evaluate against best practices from loaded guides
|
||||
</action>
|
||||
<action>Show recommendations with reasoning</action>
|
||||
<action>Apply approved optimizations</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 4 (review specific steps)">
|
||||
<action>Present each step one at a time</action>
|
||||
<action>For each step:
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
|
||||
- Show current instruction text
|
||||
- Identify current style (intent-based, prescriptive, or mixed)
|
||||
- Offer to keep, convert to intent-based, or convert to prescriptive
|
||||
- Apply user's choice before moving to next step
|
||||
Present a warm, conversational summary adapted to the workflow's complexity:
|
||||
|
||||
- What this workflow accomplishes (its purpose and value)
|
||||
- How it's structured (type, steps, interactive points)
|
||||
- What you notice (strengths, potential improvements, issues)
|
||||
- Your initial assessment based on best practices
|
||||
- How it fits in the larger BMAD ecosystem
|
||||
|
||||
Be conversational and insightful. Help {user_name} see their workflow through your eyes.
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of what this workflow should accomplish?</ask>
|
||||
<template-output>workflow_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover improvement goals collaboratively">
|
||||
<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
|
||||
|
||||
<action>Engage in collaborative discovery:
|
||||
|
||||
Ask open-ended questions to understand their goals:
|
||||
|
||||
- What prompted you to want to edit this workflow?
|
||||
- What feedback have you gotten from users running it?
|
||||
- Are there specific steps that feel clunky or confusing?
|
||||
- Is the workflow achieving its intended outcome?
|
||||
- Are there new capabilities you want to add?
|
||||
- Is the instruction style working well for your users?
|
||||
|
||||
Listen for clues about:
|
||||
|
||||
- User experience issues (confusing steps, unclear instructions)
|
||||
- Functional issues (broken references, missing validation)
|
||||
- Performance issues (too many steps, repetitive, tedious)
|
||||
- Maintainability issues (hard to update, bloated, inconsistent variables)
|
||||
- Instruction style mismatch (too prescriptive when should be adaptive, or vice versa)
|
||||
- Integration issues (doesn't work well with other workflows)
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action if="choice is 5 (cancel)"><goto step="3">Return to editing menu</goto></action>
|
||||
<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
|
||||
|
||||
<action>Show the current content that will be edited</action>
|
||||
<action>Explain the proposed changes and why they improve the workflow</action>
|
||||
<action>Generate the updated content following all conventions from the guide</action>
|
||||
Organize by priority and user goals:
|
||||
|
||||
<ask>Review the proposed changes. Options:
|
||||
- CRITICAL issues blocking successful runs
|
||||
- IMPORTANT improvements enhancing user experience
|
||||
- NICE-TO-HAVE enhancements for polish
|
||||
|
||||
- [a] Accept and apply
|
||||
- [e] Edit/modify the changes
|
||||
- [s] Skip this change
|
||||
- [n] Move to next file/section
|
||||
- [d] Done with edits
|
||||
Present these conversationally, explaining WHY each matters and HOW it would help.
|
||||
</action>
|
||||
|
||||
<action>Assess instruction style fit:
|
||||
|
||||
Based on the workflow's purpose and your analysis:
|
||||
|
||||
- Is the current style (intent-based vs prescriptive) appropriate?
|
||||
- Would users benefit from more/less structure?
|
||||
- Are there steps that should be more adaptive?
|
||||
- Are there steps that need more specificity?
|
||||
|
||||
Discuss style as part of improvement discovery, not as a separate concern.
|
||||
</action>
|
||||
|
||||
<action>Collaborate on priorities:
|
||||
|
||||
Don't just list options - discuss them:
|
||||
|
||||
- "I noticed {{issue}} - this could make users feel {{problem}}. Want to address this?"
|
||||
- "The workflow could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
|
||||
- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
|
||||
|
||||
Let the conversation flow naturally. Build a shared vision of what "better" looks like.
|
||||
</action>
|
||||
|
||||
<template-output>improvement_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
|
||||
<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
|
||||
|
||||
<action>For each improvement area, facilitate collaboratively:
|
||||
|
||||
1. **Explain the current state and why it matters**
|
||||
- Show relevant sections of the workflow
|
||||
- Explain how it works now and implications
|
||||
- Connect to user's goals from step 2
|
||||
|
||||
2. **Propose improvements with rationale**
|
||||
- Suggest specific changes that align with best practices
|
||||
- Explain WHY each change helps
|
||||
- Provide examples from the loaded guides when helpful
|
||||
- Show before/after comparisons for clarity
|
||||
- Reference the creation guide's patterns naturally
|
||||
|
||||
3. **Collaborate on the approach**
|
||||
- Ask if the proposed change addresses their need
|
||||
- Invite modifications or alternative approaches
|
||||
- Explain tradeoffs when relevant
|
||||
- Adapt based on their feedback
|
||||
|
||||
4. **Apply changes iteratively**
|
||||
- Make one focused improvement at a time
|
||||
- Show the updated section
|
||||
- Confirm it meets their expectation
|
||||
- Move to next improvement or refine current one
|
||||
</action>
|
||||
|
||||
<action>Common improvement patterns to facilitate:
|
||||
|
||||
**If refining instruction style:**
|
||||
|
||||
- Discuss where the workflow feels too rigid or too loose
|
||||
- Identify steps that would benefit from intent-based approach
|
||||
- Identify steps that need prescriptive structure
|
||||
- Convert between styles thoughtfully, explaining tradeoffs
|
||||
- Show how each style serves the user differently
|
||||
- Test proposed changes by reading them aloud
|
||||
|
||||
**If improving step flow:**
|
||||
|
||||
- Walk through the user journey step by step
|
||||
- Identify friction points or redundancy
|
||||
- Propose streamlined flow
|
||||
- Consider where steps could merge or split
|
||||
- Ensure each step has clear goal and value
|
||||
- Check that repeat conditions make sense
|
||||
|
||||
**If fixing variable consistency:**
|
||||
|
||||
- Identify variables used across files
|
||||
- Find mismatches in naming or usage
|
||||
- Propose consistent naming scheme
|
||||
- Update all files to match
|
||||
- Verify variables are defined in workflow.yaml
|
||||
|
||||
**If enhancing validation:**
|
||||
|
||||
- Review current checklist (if exists)
|
||||
- Discuss what "done well" looks like
|
||||
- Make criteria specific and measurable
|
||||
- Add validation for new features
|
||||
- Remove outdated or vague criteria
|
||||
|
||||
**If updating configuration:**
|
||||
|
||||
- Review standard config pattern
|
||||
- Check if user context variables are needed
|
||||
- Ensure output_folder, user_name, communication_language are used appropriately
|
||||
- Add missing config dependencies
|
||||
- Clean up unused config fields
|
||||
|
||||
**If adding/updating templates:**
|
||||
|
||||
- Understand the document structure needed
|
||||
- Design template variables that match instruction outputs
|
||||
- Ensure variable names are descriptive snake_case
|
||||
- Include proper metadata headers
|
||||
- Test that all variables can be filled
|
||||
|
||||
**If configuring web bundle:**
|
||||
|
||||
- Identify all files the workflow depends on
|
||||
- Check for invoked workflows (must be included)
|
||||
- Verify paths are bmad/-relative
|
||||
- Remove config_source dependencies
|
||||
- Build complete file list
|
||||
|
||||
**If improving user interaction:**
|
||||
|
||||
- Find places where <ask> could be more open-ended
|
||||
- Add educational context where users might be lost
|
||||
- Remove unnecessary confirmation steps
|
||||
- Make questions clearer and more purposeful
|
||||
- Balance guidance with user autonomy
|
||||
</action>
|
||||
|
||||
<action>Throughout improvements, educate when helpful:
|
||||
|
||||
Share insights from the guides naturally:
|
||||
|
||||
- "The creation guide recommends {{pattern}} for workflows like this"
|
||||
- "Looking at examples in BMM, this type of step usually {{approach}}"
|
||||
- "The execution engine expects {{structure}} for this to work properly"
|
||||
|
||||
Connect improvements to broader BMAD principles without being preachy.
|
||||
</action>
|
||||
|
||||
<ask>After each significant change:
|
||||
|
||||
- "Does this flow feel better for what you're trying to achieve?"
|
||||
- "Want to refine this further, or move to the next improvement?"
|
||||
- "How does this change affect the user experience?"
|
||||
</ask>
|
||||
|
||||
<check if="user selects 'a'">
|
||||
<action>Apply the changes to the file</action>
|
||||
<action>Log the change for the summary</action>
|
||||
</check>
|
||||
|
||||
<check if="user selects 'e'">
|
||||
<ask>What modifications would you like to make?</ask>
|
||||
<goto step="5">Regenerate with modifications</goto>
|
||||
</check>
|
||||
|
||||
<action if="user selects 'd'"><continue>Proceed to validation</continue></action>
|
||||
<template-output>improvement_implementation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Validate all changes" optional="true">
|
||||
<action>Run a comprehensive validation check:</action>
|
||||
<step n="4" goal="Validate improvements holistically">
|
||||
<action>Run comprehensive validation conversationally:
|
||||
|
||||
**Basic Validation:**
|
||||
Don't just check boxes - explain what you're validating and why it matters:
|
||||
|
||||
- [ ] All file paths resolve correctly
|
||||
- [ ] Variable names are consistent across files
|
||||
- [ ] Step numbering is sequential and logical
|
||||
- [ ] Required XML tags are properly formatted
|
||||
- [ ] No placeholders remain (like {TITLE} or {WORKFLOW_CODE})
|
||||
- [ ] Instructions match the workflow type
|
||||
- [ ] Template variables match instruction outputs (if applicable)
|
||||
- [ ] Checklist criteria are measurable (if present)
|
||||
- [ ] Critical headers are present in instructions
|
||||
- [ ] YAML syntax is valid
|
||||
- "Let me verify all file references resolve correctly..."
|
||||
- "Checking that variables are consistent across all files..."
|
||||
- "Making sure the step flow is logical and complete..."
|
||||
- "Validating template variables match instruction outputs..."
|
||||
- "Ensuring config dependencies are properly set up..."
|
||||
</action>
|
||||
|
||||
**Standard Config Validation:**
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
<action>Check all items from checklist systematically</action>
|
||||
|
||||
- [ ] workflow.yaml contains config_source
|
||||
- [ ] output_folder, user_name, communication_language pulled from config
|
||||
- [ ] date set to system-generated
|
||||
- [ ] Instructions communicate in {communication_language} where appropriate
|
||||
- [ ] Instructions address {user_name} where appropriate
|
||||
- [ ] Instructions write to {output_folder} for file outputs
|
||||
- [ ] Template optionally includes {{user_name}}, {{date}} in metadata (if document workflow)
|
||||
- [ ] Template does NOT use {{communication_language}} in headers (agent-only variable)
|
||||
<check if="validation_issues_found">
|
||||
<action>Present issues conversationally:
|
||||
|
||||
**YAML/File Alignment:**
|
||||
Explain what's wrong and implications:
|
||||
|
||||
- [ ] All workflow.yaml variables used in instructions OR template
|
||||
- [ ] No unused yaml fields (bloat-free)
|
||||
- [ ] No duplicate fields between top-level and web_bundle
|
||||
- [ ] Template variables match <template-output> tags in instructions
|
||||
- "I found {{issue}} which could cause {{problem}} when users run this"
|
||||
- "The {{component}} needs {{fix}} because {{reason}}"
|
||||
|
||||
**Web bundle validation (if applicable):**
|
||||
Propose fixes immediately:
|
||||
|
||||
- [ ] web_bundle section present if needed
|
||||
- [ ] All paths are bmad/-relative (no {project-root})
|
||||
- [ ] No {config_source} variables in web bundle
|
||||
- [ ] All referenced files listed in web_bundle_files
|
||||
- [ ] Instructions, validation, template paths correct
|
||||
- [ ] Called workflows (<invoke-workflow>) included in web_bundle_files
|
||||
- [ ] Complete file inventory verified
|
||||
- "I can fix this by {{solution}}. Should I?"
|
||||
- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
|
||||
</action>
|
||||
|
||||
<check if="any validation fails">
|
||||
<ask>Issues found. Would you like to fix them? (y/n)</ask>
|
||||
<check if="yes">
|
||||
<goto step="5">Return to editing</goto>
|
||||
</check>
|
||||
<action>Fix approved issues and re-validate</action>
|
||||
</check>
|
||||
|
||||
<check if="validation_passes">
|
||||
<action>Confirm success warmly:
|
||||
|
||||
"Excellent! Everything validates cleanly:
|
||||
|
||||
- All file references resolve
|
||||
- Variables are consistent throughout
|
||||
- Step flow is logical and complete
|
||||
- Template aligns with instructions (if applicable)
|
||||
- Config dependencies are set up correctly
|
||||
- Web bundle is complete (if applicable)
|
||||
|
||||
Your workflow is in great shape."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Generate change summary">
|
||||
<action>Create a summary of all changes made for {user_name} in {communication_language}:</action>
|
||||
<step n="5" goal="Review improvements and guide next steps">
|
||||
<action>Create a conversational summary of what improved:
|
||||
|
||||
**Summary Structure:**
|
||||
Tell the story of the transformation:
|
||||
|
||||
- Workflow name
|
||||
- Changes made (file-by-file descriptions)
|
||||
- Improvements (how workflow is now better aligned with best practices)
|
||||
- Files modified (complete list with paths)
|
||||
- Next steps (suggestions for additional improvements or testing)
|
||||
- "We started with {{initial_state}}"
|
||||
- "You wanted to {{user_goals}}"
|
||||
- "We made these key improvements: {{changes_list}}"
|
||||
- "Now your workflow {{improved_capabilities}}"
|
||||
|
||||
Highlight the impact:
|
||||
|
||||
- "This means users will experience {{benefit}}"
|
||||
- "The workflow is now more {{quality}}"
|
||||
- "It follows best practices for {{patterns}}"
|
||||
</action>
|
||||
|
||||
<action>Guide next steps based on changes made:
|
||||
|
||||
If instruction style changed:
|
||||
|
||||
- "Since we made the workflow more {{style}}, you might want to test it with a real user to see how it feels"
|
||||
|
||||
If template was updated:
|
||||
|
||||
- "The template now has {{new_variables}} - run the workflow to generate a sample document"
|
||||
|
||||
If this is part of larger module work:
|
||||
|
||||
- "This workflow is part of {{module}} - consider if other workflows need similar improvements"
|
||||
|
||||
If web bundle was configured:
|
||||
|
||||
- "The web bundle is now set up - you can test deploying this workflow standalone"
|
||||
|
||||
Be a helpful guide to what comes next, not just a task completer.
|
||||
</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- Test the edited workflow
|
||||
- Make additional edits
|
||||
- Exit
|
||||
- Test the edited workflow by running it
|
||||
- Edit another workflow
|
||||
- Make additional refinements to this one
|
||||
- Return to your module work
|
||||
</ask>
|
||||
|
||||
<action if="test workflow">Invoke the edited workflow for testing</action>
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
||||
Reference in New Issue
Block a user