mirror of
https://github.com/R0m1k3/xtremflow.git
synced 2026-10-19 21:18:06 +02:00
feat: security overhaul (proxy ssrf fix, streaming sanitization, docker optimization)
This commit is contained in:
Michael committed
1 parent
6d87ada2b8
commit
8df9a37baa
810 files changed
+131090
-151
No files matched your search
@@ -0,0 +1,220 @@
|
||||
# Standalone Workflow Builder Architecture
|
||||
|
||||
This document describes the architecture of the standalone workflow builder system - a pure markdown approach to creating structured workflows.
|
||||
|
||||
## Core Architecture Principles
|
||||
|
||||
### 1. Micro-File Design
|
||||
|
||||
Each workflow consists of multiple focused, self-contained files, driven from a workflow.md file that is initially loaded:
|
||||
|
||||
```
|
||||
workflow-folder/
|
||||
├── workflow.md # Main workflow configuration
|
||||
├── steps/ # Step instruction files (focused, self-contained)
|
||||
│ ├── step-01-init.md
|
||||
│ ├── step-02-profile.md
|
||||
│ └── step-N-[name].md
|
||||
├── templates/ # Content templates
|
||||
│ ├── profile-section.md
|
||||
│ └── [other-sections].md
|
||||
└── data/ # Optional data files
|
||||
└── [data-files].csv/.json
|
||||
```
|
||||
|
||||
### 2. Just-In-Time (JIT) Loading
|
||||
|
||||
- **Single File in Memory**: Only the current step file is loaded
|
||||
- **No Future Peeking**: Step files must not reference future steps
|
||||
- **Sequential Processing**: Steps execute in strict order
|
||||
- **On-Demand Loading**: Templates load only when needed
|
||||
|
||||
### 3. State Management
|
||||
|
||||
- **Frontmatter Tracking**: Workflow state stored in output document frontmatter
|
||||
- **Progress Array**: `stepsCompleted` tracks completed steps
|
||||
- **Last Step Marker**: `lastStep` indicates where to resume
|
||||
- **Append-Only Building**: Documents grow by appending content
|
||||
|
||||
### 4. Execution Model
|
||||
|
||||
```
|
||||
1. Load workflow.md → Read configuration
|
||||
2. Execute step-01-init.md → Initialize or detect continuation
|
||||
3. For each step:
|
||||
a. Load step file completely
|
||||
b. Execute instructions sequentially
|
||||
c. Wait for user input at menu points
|
||||
d. Only proceed with 'C' (Continue)
|
||||
e. Update document/frontmatter
|
||||
f. Load next step
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### Workflow File (workflow.md)
|
||||
|
||||
- **Purpose**: Entry point and configuration
|
||||
- **Content**: Role definition, goal, architecture rules
|
||||
- **Action**: Points to step-01-init.md
|
||||
|
||||
### Step Files (step-NN-[name].md)
|
||||
|
||||
- **Size**: Focused and concise (typically 5-10KB)
|
||||
- **Structure**: Frontmatter + sequential instructions
|
||||
- **Features**: Self-contained rules, menu handling, state updates
|
||||
|
||||
### Frontmatter Variables
|
||||
|
||||
Standard variables in step files:
|
||||
|
||||
```yaml
|
||||
workflow_path: '{project-root}/_bmad/bmb/reference/workflows/[workflow-name]'
|
||||
thisStepFile: '{workflow_path}/steps/step-[N]-[name].md'
|
||||
nextStepFile: '{workflow_path}/steps/step-[N+1]-[name].md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/[output-name]-{project_name}.md'
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Fresh Workflow
|
||||
|
||||
```
|
||||
workflow.md
|
||||
↓
|
||||
step-01-init.md (creates document)
|
||||
↓
|
||||
step-02-[name].md
|
||||
↓
|
||||
step-03-[name].md
|
||||
↓
|
||||
...
|
||||
↓
|
||||
step-N-[final].md (completes workflow)
|
||||
```
|
||||
|
||||
### Continuation Workflow
|
||||
|
||||
```
|
||||
workflow.md
|
||||
↓
|
||||
step-01-init.md (detects existing document)
|
||||
↓
|
||||
step-01b-continue.md (analyzes state)
|
||||
↓
|
||||
step-[appropriate-next].md
|
||||
```
|
||||
|
||||
## Menu System
|
||||
|
||||
### Standard Menu Pattern
|
||||
|
||||
```
|
||||
Display: **Select an Option:** [A] [Action] [P] Party Mode [C] Continue
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {advancedElicitationTask}
|
||||
- IF P: Execute {partyModeWorkflow}
|
||||
- IF C: Save content, update frontmatter, load next step
|
||||
```
|
||||
|
||||
### Menu Rules
|
||||
|
||||
- **Halt Required**: Always wait for user input
|
||||
- **Continue Only**: Only proceed with 'C' selection
|
||||
- **State Persistence**: Save before loading next step
|
||||
- **Loop Back**: Return to menu after other actions
|
||||
|
||||
## Collaborative Dialogue Model
|
||||
|
||||
### Not Command-Response
|
||||
|
||||
- **Facilitator Role**: AI guides, user decides
|
||||
- **Equal Partnership**: Both parties contribute
|
||||
- **No Assumptions**: Don't assume user wants next step
|
||||
- **Explicit Consent**: Always ask for input
|
||||
|
||||
### Example Pattern
|
||||
|
||||
```
|
||||
AI: "Tell me about your dietary preferences."
|
||||
User: [provides information]
|
||||
AI: "Thank you. Now let's discuss your cooking habits."
|
||||
[Continue conversation]
|
||||
AI: **Menu Options**
|
||||
```
|
||||
|
||||
## CSV Intelligence (Optional)
|
||||
|
||||
### Data-Driven Behavior
|
||||
|
||||
- Configuration in CSV files
|
||||
- Dynamic menu options
|
||||
- Variable substitution
|
||||
- Conditional logic
|
||||
|
||||
### Example Structure
|
||||
|
||||
```csv
|
||||
variable,type,value,description
|
||||
cooking_frequency,choice,"daily|weekly|occasionally","How often user cooks"
|
||||
meal_type,multi,"breakfast|lunch|dinner|snacks","Types of meals to plan"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### File Size Limits
|
||||
|
||||
- **Step Files**: Keep focused and reasonably sized (5-10KB typical)
|
||||
- **Templates**: Keep focused and reusable
|
||||
- **Workflow File**: Keep lean, no implementation details
|
||||
|
||||
### Sequential Enforcement
|
||||
|
||||
- **Numbered Steps**: Use sequential numbering (1, 2, 3...)
|
||||
- **No Skipping**: Each step must complete
|
||||
- **State Updates**: Mark completion in frontmatter
|
||||
|
||||
### Error Prevention
|
||||
|
||||
- **Path Variables**: Use frontmatter variables, never hardcode
|
||||
- **Complete Loading**: Always read entire file before execution
|
||||
- **Menu Halts**: Never proceed without 'C' selection
|
||||
|
||||
## Migration from XML
|
||||
|
||||
### Advantages
|
||||
|
||||
- **No Dependencies**: Pure markdown, no XML parsing
|
||||
- **Human Readable**: Files are self-documenting
|
||||
- **Git Friendly**: Clean diffs and merges
|
||||
- **Flexible**: Easier to modify and extend
|
||||
|
||||
### Key Differences
|
||||
|
||||
| XML Workflows | Standalone Workflows |
|
||||
| ----------------- | ----------------------- |
|
||||
| Single large file | Multiple micro-files |
|
||||
| Complex structure | Simple sequential steps |
|
||||
| Parser required | Any markdown viewer |
|
||||
| Rigid format | Flexible organization |
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Critical Rules
|
||||
|
||||
- **NEVER** load multiple step files
|
||||
- **ALWAYS** read complete step file first
|
||||
- **NEVER** skip steps or optimize
|
||||
- **ALWAYS** update frontmatter of the output file when a step is complete
|
||||
- **NEVER** proceed without user consent
|
||||
|
||||
### Success Metrics
|
||||
|
||||
- Documents created correctly
|
||||
- All steps completed sequentially
|
||||
- User satisfied with collaborative process
|
||||
- Clean, maintainable file structure
|
||||
|
||||
This architecture ensures disciplined, predictable workflow execution while maintaining flexibility for different use cases.
|
||||
@@ -0,0 +1,19 @@
|
||||
propose,type,tool_name,description,url,requires_install
|
||||
always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/_bmad/core/workflows/party-mode/workflow.md,no
|
||||
always,workflow,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
|
||||
always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/_bmad/core/tasks/brainstorming.xml,no
|
||||
always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
|
||||
always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no
|
||||
always,llm-tool-feature,sub-agents,"Allows LLM to create and manage specialized sub-agents that handle specific tasks or modules within larger workflows, improving efficiency through parallel processing and modular task delegation.",,no
|
||||
always,llm-tool-feature,sub-processes,"Enables LLM to initiate and manage subprocesses that operate independently, allowing for parallel processing of complex tasks and improved resource utilization during long-running operations.",,no
|
||||
always,tool-memory,sidecar-file,"Creates a persistent history file that gets written during workflow execution and loaded on future runs, enabling continuity through session-to-session state management. Used for agent or workflow initialization with previous session context, learning from past interactions, and maintaining progress across multiple executions.",,no
|
||||
example,tool-memory,vector-database,"Stores and retrieves semantic information through embeddings for intelligent memory access, enabling workflows to find relevant past experiences, patterns, or context based on meaning rather than exact matches. Useful for complex learning systems, pattern recognition, and semantic search across workflow history.",https://github.com/modelcontextprotocol/servers/tree/main/src/rag-agent,yes
|
||||
example,mcp,context-7,"A curated knowledge base of API documentation and third-party tool references, enabling LLM to access accurate and current information for integration and development tasks when specific technical documentation is needed.",https://github.com/modelcontextprotocol/servers/tree/main/src/context-7,yes
|
||||
example,mcp,playwright,"Provides capabilities for LLM to perform web browser automation including navigation, form submission, data extraction, and testing actions on web pages, facilitating automated web interactions and quality assurance.",https://github.com/modelcontextprotocol/servers/tree/main/src/playwright,yes
|
||||
example,workflow,security-auditor,"Analyzes workflows and code for security vulnerabilities, compliance issues, and best practices violations, providing detailed security assessments and remediation recommendations for production-ready systems.",,no
|
||||
example,task,code-review,"Performs systematic code analysis with peer review perspectives, identifying bugs, performance issues, style violations, and architectural problems through adversarial review techniques.",,no
|
||||
example,mcp,git-integration,"Enables direct Git repository operations including commits, branches, merges, and history analysis, allowing workflows to interact with version control systems for code management and collaboration.",https://github.com/modelcontextprotocol/servers/tree/main/src/git,yes
|
||||
example,mcp,database-connector,"Provides direct database connectivity for querying, updating, and managing data across multiple database types, enabling workflows to interact with structured data sources and perform data-driven operations.",https://github.com/modelcontextprotocol/servers/tree/main/src/postgres,yes
|
||||
example,task,api-testing,"Automated API endpoint testing with request/response validation, authentication handling, and comprehensive reporting for REST, GraphQL, and other API types through systematic test generation.",,no
|
||||
example,workflow,deployment-manager,"Orchestrates application deployment across multiple environments with rollback capabilities, health checks, and automated release pipelines for continuous integration and delivery workflows.",,no
|
||||
example,task,data-validator,"Validates data quality, schema compliance, and business rules through comprehensive data profiling with detailed reporting and anomaly detection for data-intensive workflows.",,no
|
||||
|
@@ -0,0 +1,206 @@
|
||||
# CSV Data File Standards for BMAD Workflows
|
||||
|
||||
## Purpose and Usage
|
||||
|
||||
CSV data files in BMAD workflows serve specific purposes for different workflow types:
|
||||
|
||||
**For Agents:** Provide structured data that agents need to reference but cannot realistically generate (such as specific configurations, domain-specific data, or structured knowledge bases).
|
||||
|
||||
**For Expert Agents:** Supply specialized knowledge bases, reference data, or persistent information that the expert agent needs to access consistently across sessions.
|
||||
|
||||
**For Workflows:** Include reference data, configuration parameters, or structured inputs that guide workflow execution and decision-making.
|
||||
|
||||
**Key Principle:** CSV files should contain data that is essential, structured, and not easily generated by LLMs during execution.
|
||||
|
||||
## Intent-Based Design Principle
|
||||
|
||||
**Core Philosophy:** The closer workflows stay to **intent** rather than **prescriptive** instructions, the more creative and adaptive the LLM experience becomes.
|
||||
|
||||
**CSV Enables Intent-Based Design:**
|
||||
|
||||
- **Instead of:** Hardcoded scripts with exact phrases LLM must say
|
||||
- **CSV Provides:** Clear goals and patterns that LLM adapts creatively to context
|
||||
- **Result:** Natural, contextual conversations rather than rigid scripts
|
||||
|
||||
**Example - Advanced Elicitation:**
|
||||
|
||||
- **Prescriptive Alternative:** 50 separate files with exact conversation scripts
|
||||
- **Intent-Based Reality:** One CSV row with method goal + pattern → LLM adapts to user
|
||||
- **Benefit:** Same method works differently for different users while maintaining essence
|
||||
|
||||
**Intent vs Prescriptive Spectrum:**
|
||||
|
||||
- **Highly Prescriptive:** "Say exactly: 'Based on my analysis, I recommend...'"
|
||||
- **Balanced Intent:** "Help the user understand the implications using your professional judgment"
|
||||
- **CSV Goal:** Provide just enough guidance to enable creative, context-aware execution
|
||||
|
||||
## Primary Use Cases
|
||||
|
||||
### 1. Knowledge Base Indexing (Document Lookup Optimization)
|
||||
|
||||
**Problem:** Large knowledge bases with hundreds of documents cause context blowup and missed details when LLMs try to process them all.
|
||||
|
||||
**CSV Solution:** Create a knowledge base index with:
|
||||
|
||||
- **Column 1:** Keywords and topics
|
||||
- **Column 2:** Document file path/location
|
||||
- **Column 3:** Section or line number where relevant content starts
|
||||
- **Column 4:** Content type or summary (optional)
|
||||
|
||||
**Result:** Transform from context-blowing document loads to surgical precision lookups, creating agents with near-infinite knowledge bases while maintaining optimal context usage.
|
||||
|
||||
### 2. Workflow Sequence Optimization
|
||||
|
||||
**Problem:** Complex workflows (e.g., game development) with hundreds of potential steps for different scenarios become unwieldy and context-heavy.
|
||||
|
||||
**CSV Solution:** Create a workflow routing table:
|
||||
|
||||
- **Column 1:** Scenario type (e.g., "2D Platformer", "RPG", "Puzzle Game")
|
||||
- **Column 2:** Required step sequence (e.g., "step-01,step-03,step-07,step-12")
|
||||
- **Column 3:** Document sections to include
|
||||
- **Column 4:** Specialized parameters or configurations
|
||||
|
||||
**Result:** Step 1 determines user needs, finds closest match in CSV, confirms with user, then follows optimized sequence - truly optimal for context usage.
|
||||
|
||||
### 3. Method Registry (Dynamic Technique Selection)
|
||||
|
||||
**Problem:** Tasks need to select optimal techniques from dozens of options based on context, without hardcoding selection logic.
|
||||
|
||||
**CSV Solution:** Create a method registry with:
|
||||
|
||||
- **Column 1:** Category (collaboration, advanced, technical, creative, etc.)
|
||||
- **Column 2:** Method name and rich description
|
||||
- **Column 3:** Execution pattern or flow guide (e.g., "analysis → insights → action")
|
||||
- **Column 4:** Complexity level or use case indicators
|
||||
|
||||
**Example:** Advanced Elicitation task analyzes content context, selects 5 best-matched methods from 50 options, then executes dynamically using CSV descriptions.
|
||||
|
||||
**Result:** Smart, context-aware technique selection without hardcoded logic - infinitely extensible method libraries.
|
||||
|
||||
### 4. Configuration Management
|
||||
|
||||
**Problem:** Complex systems with many configuration options that vary by use case.
|
||||
|
||||
**CSV Solution:** Configuration lookup tables mapping scenarios to specific parameter sets.
|
||||
|
||||
## What NOT to Include in CSV Files
|
||||
|
||||
**Avoid Web-Searchable Data:** Do not include information that LLMs can readily access through web search or that exists in their training data, such as:
|
||||
|
||||
- Common programming syntax or standard library functions
|
||||
- General knowledge about widely used technologies
|
||||
- Historical facts or commonly available information
|
||||
- Basic terminology or standard definitions
|
||||
|
||||
**Include Specialized Data:** Focus on data that is:
|
||||
|
||||
- Specific to your project or domain
|
||||
- Not readily available through web search
|
||||
- Essential for consistent workflow execution
|
||||
- Too voluminous for LLM context windows
|
||||
|
||||
## CSV Data File Standards
|
||||
|
||||
### 1. Purpose Validation
|
||||
|
||||
- **Essential Data Only:** CSV must contain data that cannot be reasonably generated by LLMs
|
||||
- **Domain Specific:** Data should be specific to the workflow's domain or purpose
|
||||
- **Consistent Usage:** All columns and data must be referenced and used somewhere in the workflow
|
||||
- **No Redundancy:** Avoid data that duplicates functionality already available to LLMs
|
||||
|
||||
### 2. Structural Standards
|
||||
|
||||
- **Valid CSV Format:** Proper comma-separated values with quoted fields where needed
|
||||
- **Consistent Columns:** All rows must have the same number of columns
|
||||
- **No Missing Data:** Empty values should be explicitly marked (e.g., "", "N/A", or NULL)
|
||||
- **Header Row:** First row must contain clear, descriptive column headers
|
||||
- **Proper Encoding:** UTF-8 encoding required for special characters
|
||||
|
||||
### 3. Content Standards
|
||||
|
||||
- **No LLM-Generated Content:** Avoid data that LLMs can easily generate (e.g., generic phrases, common knowledge)
|
||||
- **Specific and Concrete:** Use specific values rather than vague descriptions
|
||||
- **Verifiable Data:** Data should be factual and verifiable when possible
|
||||
- **Consistent Formatting:** Date formats, numbers, and text should follow consistent patterns
|
||||
|
||||
### 4. Column Standards
|
||||
|
||||
- **Clear Headers:** Column names must be descriptive and self-explanatory
|
||||
- **Consistent Data Types:** Each column should contain consistent data types
|
||||
- **No Unused Columns:** Every column must be referenced and used in the workflow
|
||||
- **Appropriate Width:** Columns should be reasonably narrow and focused
|
||||
|
||||
### 5. File Size Standards
|
||||
|
||||
- **Efficient Structure:** CSV files should be as small as possible while maintaining functionality
|
||||
- **No Redundant Rows:** Avoid duplicate or nearly identical rows
|
||||
- **Compressed Data:** Use efficient data representation (e.g., codes instead of full descriptions)
|
||||
- **Maximum Size:** Individual CSV files should not exceed 1MB unless absolutely necessary
|
||||
|
||||
### 6. Documentation Standards
|
||||
|
||||
- **Documentation Required:** Each CSV file should have documentation explaining its purpose
|
||||
- **Column Descriptions:** Each column must be documented with its usage and format
|
||||
- **Data Sources:** Source of data should be documented when applicable
|
||||
- **Update Procedures:** Process for updating CSV data should be documented
|
||||
|
||||
### 7. Integration Standards
|
||||
|
||||
- **File References:** CSV files must be properly referenced in workflow configuration
|
||||
- **Access Patterns:** Workflow must clearly define how and when CSV data is accessed
|
||||
- **Error Handling:** Workflow must handle cases where CSV files are missing or corrupted
|
||||
- **Version Control:** CSV files should be versioned when changes occur
|
||||
|
||||
### 8. Quality Assurance
|
||||
|
||||
- **Data Validation:** CSV data should be validated for correctness and completeness
|
||||
- **Format Consistency:** Consistent formatting across all rows and columns
|
||||
- **No Ambiguity:** Data entries should be clear and unambiguous
|
||||
- **Regular Review:** CSV content should be reviewed periodically for relevance
|
||||
|
||||
### 9. Security Considerations
|
||||
|
||||
- **No Sensitive Data:** Avoid including sensitive, personal, or confidential information
|
||||
- **Data Sanitization:** CSV data should be sanitized for security issues
|
||||
- **Access Control:** Access to CSV files should be controlled when necessary
|
||||
- **Audit Trail:** Changes to CSV files should be logged when appropriate
|
||||
|
||||
### 10. Performance Standards
|
||||
|
||||
- **Fast Loading:** CSV files must load quickly within workflow execution
|
||||
- **Memory Efficient:** Structure should minimize memory usage during processing
|
||||
- **Optimized Queries:** If data lookup is needed, optimize for efficient access
|
||||
- **Caching Strategy**: Consider whether data can be cached for performance
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
When creating CSV data files for BMAD workflows:
|
||||
|
||||
1. **Start with Purpose:** Clearly define why CSV is needed instead of LLM generation
|
||||
2. **Design Structure:** Plan columns and data types before creating the file
|
||||
3. **Test Integration:** Ensure workflow properly accesses and uses CSV data
|
||||
4. **Document Thoroughly:** Provide complete documentation for future maintenance
|
||||
5. **Validate Quality:** Check data quality, format consistency, and integration
|
||||
6. **Monitor Usage:** Track how CSV data is used and optimize as needed
|
||||
|
||||
## Common Anti-Patterns to Avoid
|
||||
|
||||
- **Generic Phrases:** CSV files containing common phrases or LLM-generated content
|
||||
- **Redundant Data:** Duplicating information easily available to LLMs
|
||||
- **Overly Complex:** Unnecessarily complex CSV structures when simple data suffices
|
||||
- **Unused Columns:** Columns that are defined but never referenced in workflows
|
||||
- **Poor Formatting:** Inconsistent data formats, missing values, or structural issues
|
||||
- **No Documentation:** CSV files without clear purpose or usage documentation
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For each CSV file, verify:
|
||||
|
||||
- [ ] Purpose is essential and cannot be replaced by LLM generation
|
||||
- [ ] All columns are used in the workflow
|
||||
- [ ] Data is properly formatted and consistent
|
||||
- [ ] File is efficiently sized and structured
|
||||
- [ ] Documentation is complete and clear
|
||||
- [ ] Integration with workflow is tested and working
|
||||
- [ ] Security considerations are addressed
|
||||
- [ ] Performance requirements are met
|
||||
@@ -0,0 +1,220 @@
|
||||
# Intent vs Prescriptive Spectrum
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
The **Intent vs Prescriptive Spectrum** is a fundamental design principle for BMAD workflows and agents. It determines how much creative freedom an LLM has versus how strictly it must follow predefined instructions.
|
||||
|
||||
**Key Principle:** The closer workflows stay to **intent**, the more creative and adaptive the LLM experience becomes. The closer they stay to **prescriptive**, the more consistent and controlled the output becomes.
|
||||
|
||||
## Understanding the Spectrum
|
||||
|
||||
### **Intent-Based Design** (Creative Freedom)
|
||||
|
||||
**Focus**: What goal should be achieved
|
||||
**Approach**: Trust the LLM to determine the best method
|
||||
**Result**: Creative, adaptive, context-aware interactions
|
||||
**Best For**: Creative exploration, problem-solving, personalized experiences
|
||||
|
||||
### **Prescriptive Design** (Structured Control)
|
||||
|
||||
**Focus**: Exactly what to say and do
|
||||
**Approach**: Detailed scripts and specific instructions
|
||||
**Result**: Consistent, predictable, controlled outcomes
|
||||
**Best For**: Compliance, safety-critical, standardized processes
|
||||
|
||||
## Spectrum Examples
|
||||
|
||||
### **Highly Intent-Based** (Creative End)
|
||||
|
||||
```markdown
|
||||
**Example:** Story Exploration Workflow
|
||||
**Instruction:** "Help the user explore their dream imagery to craft compelling narratives, use multiple turns of conversation to really push users to develop their ideas, giving them hints and ideas also to prime them effectively to bring out their creativity"
|
||||
**LLM Freedom:** Adapts questions, explores tangents, follows creative inspiration
|
||||
**Outcome:** Unique, personalized storytelling experiences
|
||||
```
|
||||
|
||||
### **Balanced Middle** (Professional Services)
|
||||
|
||||
```markdown
|
||||
**Example:** Business Strategy Workflow
|
||||
**Instruction:** "Guide the user through SWOT analysis using your business expertise. when complete tell them 'here is your final report {report output}'
|
||||
**LLM Freedom:** Professional judgment in analysis, structured but adaptive approach
|
||||
**Outcome:** Professional, consistent yet tailored business insights
|
||||
```
|
||||
|
||||
### **Highly Prescriptive** (Control End)
|
||||
|
||||
```markdown
|
||||
**Example:** Medical Intake Form
|
||||
**Instruction:** "Ask exactly: 'Do you currently experience any of the following symptoms: fever, cough, fatigue?' Wait for response, then ask exactly: 'When did these symptoms begin?'"
|
||||
**LLM Freedom:** Minimal - must follow exact script for medical compliance
|
||||
**Outcome:** Consistent, medically compliant patient data collection
|
||||
```
|
||||
|
||||
## Spectrum Positioning Guide
|
||||
|
||||
### **Choose Intent-Based When:**
|
||||
|
||||
- ✅ Creative exploration and innovation are goals
|
||||
- ✅ Personalization and adaptation to user context are important
|
||||
- ✅ Human-like conversation and natural interaction are desired
|
||||
- ✅ Problem-solving requires flexible thinking
|
||||
- ✅ User experience and engagement are priorities
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Creative brainstorming sessions
|
||||
- Personal coaching or mentoring
|
||||
- Exploratory research and discovery
|
||||
- Artistic content creation
|
||||
- Collaborative problem-solving
|
||||
|
||||
### **Choose Prescriptive When:**
|
||||
|
||||
- ✅ Compliance with regulations or standards is required
|
||||
- ✅ Safety or legal considerations are paramount
|
||||
- ✅ Exact consistency across multiple sessions is essential
|
||||
- ✅ Training new users on specific procedures
|
||||
- ✅ Data collection must follow specific protocols
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Medical intake and symptom assessment
|
||||
- Legal compliance questionnaires
|
||||
- Safety checklists and procedures
|
||||
- Standardized testing protocols
|
||||
- Regulatory data collection
|
||||
|
||||
### **Choose Balanced When:**
|
||||
|
||||
- ✅ Professional expertise is required but adaptation is beneficial
|
||||
- ✅ Consistent quality with flexible application is needed
|
||||
- ✅ Domain expertise should guide but not constrain interactions
|
||||
- ✅ User trust and professional credibility are important
|
||||
- ✅ Complex processes require both structure and judgment
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Business consulting and advisory
|
||||
- Technical support and troubleshooting
|
||||
- Educational tutoring and instruction
|
||||
- Financial planning and advice
|
||||
- Project management facilitation
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
### **For Workflow Designers:**
|
||||
|
||||
1. **Early Spectrum Decision**: Determine spectrum position during initial design
|
||||
2. **User Education**: Explain spectrum choice and its implications to users
|
||||
3. **Consistent Application**: Maintain chosen spectrum throughout workflow
|
||||
4. **Context Awareness**: Adjust spectrum based on specific use case requirements
|
||||
|
||||
### **For Workflow Implementation:**
|
||||
|
||||
**Intent-Based Patterns:**
|
||||
|
||||
```markdown
|
||||
- "Help the user understand..." (vs "Explain that...")
|
||||
- "Guide the user through..." (vs "Follow these steps...")
|
||||
- "Use your professional judgment to..." (vs "Apply this specific method...")
|
||||
- "Adapt your approach based on..." (vs "Regardless of situation, always...")
|
||||
```
|
||||
|
||||
**Prescriptive Patterns:**
|
||||
|
||||
```markdown
|
||||
- "Say exactly: '...'" (vs "Communicate that...")
|
||||
- "Follow this script precisely: ..." (vs "Cover these points...")
|
||||
- "Do not deviate from: ..." (vs "Consider these options...")
|
||||
- "Must ask in this order: ..." (vs "Ensure you cover...")
|
||||
```
|
||||
|
||||
### **For Agents:**
|
||||
|
||||
**Intent-Based Agent Design:**
|
||||
|
||||
```yaml
|
||||
persona:
|
||||
communication_style: 'Adaptive professional who adjusts approach based on user context'
|
||||
guiding_principles:
|
||||
- 'Use creative problem-solving within professional boundaries'
|
||||
- 'Personalize approach while maintaining expertise'
|
||||
- 'Adapt conversation flow to user needs'
|
||||
```
|
||||
|
||||
**Prescriptive Agent Design:**
|
||||
|
||||
```yaml
|
||||
persona:
|
||||
communication_style: 'Follows standardized protocols exactly'
|
||||
governing_rules:
|
||||
- 'Must use approved scripts without deviation'
|
||||
- 'Follow sequence precisely as defined'
|
||||
- 'No adaptation of prescribed procedures'
|
||||
```
|
||||
|
||||
## Spectrum Calibration Questions
|
||||
|
||||
**Ask these during workflow design:**
|
||||
|
||||
1. **Consequence of Variation**: What happens if the LLM says something different?
|
||||
2. **User Expectation**: Does the user expect consistency or creativity?
|
||||
3. **Risk Level**: What are the risks of creative deviation vs. rigid adherence?
|
||||
4. **Expertise Required**: Is domain expertise application more important than consistency?
|
||||
5. **Regulatory Requirements**: Are there external compliance requirements?
|
||||
|
||||
## Best Practices
|
||||
|
||||
### **DO:**
|
||||
|
||||
- ✅ Make conscious spectrum decisions during design
|
||||
- ✅ Explain spectrum choices to users
|
||||
- ✅ Use intent-based design for creative and adaptive experiences
|
||||
- ✅ Use prescriptive design for compliance and consistency requirements
|
||||
- ✅ Consider balanced approaches for professional services
|
||||
- ✅ Document spectrum rationale for future reference
|
||||
|
||||
### **DON'T:**
|
||||
|
||||
- ❌ Mix spectrum approaches inconsistently within workflows
|
||||
- ❌ Default to prescriptive when intent-based would be more effective
|
||||
- ❌ Use creative freedom when compliance is required
|
||||
- ❌ Forget to consider user expectations and experience
|
||||
- ❌ Overlook risk assessment in spectrum selection
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
**When validating workflows:**
|
||||
|
||||
- Check if spectrum position is intentional and consistent
|
||||
- Verify prescriptive elements are necessary and justified
|
||||
- Ensure intent-based elements have sufficient guidance
|
||||
- Confirm spectrum alignment with user needs and expectations
|
||||
- Validate that risks are appropriately managed
|
||||
|
||||
## Examples in Practice
|
||||
|
||||
### **Medical Intake (Highly Prescriptive):**
|
||||
|
||||
- **Why**: Patient safety, regulatory compliance, consistent data collection
|
||||
- **Implementation**: Exact questions, specific order, no deviation permitted
|
||||
- **Benefit**: Reliable, medically compliant patient information
|
||||
|
||||
### **Creative Writing Workshop (Highly Intent):**
|
||||
|
||||
- **Why**: Creative exploration, personalized inspiration, artistic expression
|
||||
- **Implementation**: Goal guidance, creative freedom, adaptive prompts
|
||||
- **Benefit**: Unique, personalized creative works
|
||||
|
||||
### **Business Strategy (Balanced):**
|
||||
|
||||
- **Why**: Professional expertise with adaptive application
|
||||
- **Implementation**: Structured framework with professional judgment
|
||||
- **Benefit**: Professional, consistent yet tailored business insights
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Intent vs Prescriptive Spectrum is not about good vs. bad - it's about **appropriate design choices**. The best workflows make conscious decisions about where they fall on this spectrum based on their specific requirements, user needs, and risk considerations.
|
||||
|
||||
**Key Success Factor**: Choose your spectrum position intentionally, implement it consistently, and align it with your specific use case requirements.
|
||||
@@ -0,0 +1,469 @@
|
||||
# BMAD Step File Guidelines
|
||||
|
||||
**Version:** 1.0
|
||||
**Module:** bmb (BMAD Builder)
|
||||
**Purpose:** Definitive guide for creating BMAD workflow step files
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines.
|
||||
|
||||
---
|
||||
|
||||
## File Size Optimization
|
||||
|
||||
**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum).
|
||||
|
||||
If a step exceeds this limit:
|
||||
- Consider splitting into multiple steps
|
||||
- Extract content to `/data/` reference files
|
||||
- Optimize verbose explanations
|
||||
|
||||
---
|
||||
|
||||
## Required Frontmatter Structure
|
||||
|
||||
CRITICAL: Frontmatter should only have items that are used in the step file!
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: 'step-2-foo.md'
|
||||
description: 'Brief description of what this step accomplishes'
|
||||
|
||||
# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file!
|
||||
outputFile: {bmb_creations_output_folder}/output-file-name.md
|
||||
nextStepFile: './step-3-bar.md'
|
||||
|
||||
# Task References (as needed)
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
# ... other task-specific references
|
||||
---
|
||||
```
|
||||
|
||||
### Frontmatter Field Descriptions
|
||||
|
||||
| Field | Required | Description |
|
||||
| --------------- | --------- | --------------------------------- |
|
||||
| `name` | Yes | Step identifier (kebab-case) |
|
||||
| `description` | Yes | One-line summary of step purpose |
|
||||
| `outputFile` | Yes | Where results are documented |
|
||||
| Task references | As needed | Paths to external workflows/tasks |
|
||||
|
||||
---
|
||||
|
||||
## Document Structure
|
||||
|
||||
### 1. Title
|
||||
|
||||
```markdown
|
||||
# Step X: [Step Name]
|
||||
```
|
||||
|
||||
### 2. STEP GOAL
|
||||
|
||||
```markdown
|
||||
## STEP GOAL:
|
||||
|
||||
[Single sentence stating what this step accomplishes]
|
||||
```
|
||||
|
||||
### 3. Role Reinforcement
|
||||
|
||||
```markdown
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are a [specific role] who [does what]
|
||||
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring [your expertise], user brings [their expertise], together we [achieve goal]
|
||||
- ✅ Maintain [tone/approach] throughout
|
||||
```
|
||||
|
||||
### 4. Language Preference
|
||||
|
||||
```markdown
|
||||
### Language Preference:
|
||||
The user has chosen to communicate in the **{language}** language.
|
||||
You MUST respond in **{language}** throughout this step.
|
||||
```
|
||||
|
||||
**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it.
|
||||
|
||||
### 5. Step-Specific Rules
|
||||
|
||||
```markdown
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on [specific scope]
|
||||
- 🚫 FORBIDDEN to [prohibited action]
|
||||
- 💬 Approach: [how to engage]
|
||||
- 📋 Ensure [specific outcome]
|
||||
```
|
||||
|
||||
### 6. EXECUTION PROTOCOLS
|
||||
|
||||
```markdown
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- [What to do - use verbs]
|
||||
- [Another action]
|
||||
- 🚫 FORBIDDEN to [prohibited action]
|
||||
```
|
||||
|
||||
### 7. CONTEXT BOUNDARIES
|
||||
|
||||
```markdown
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: [what's available]
|
||||
- Focus: [what to focus on]
|
||||
- Limits: [boundaries]
|
||||
- Dependencies: [what this step depends on]
|
||||
```
|
||||
|
||||
### 8. Sequence of Instructions
|
||||
|
||||
```markdown
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. [First Action]
|
||||
|
||||
**[Action Description]**
|
||||
|
||||
### 2. [Second Action]
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
### 9. MENU OPTIONS
|
||||
|
||||
```markdown
|
||||
### X. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`...
|
||||
```
|
||||
|
||||
### 10. SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
```markdown
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- [Success criterion 1]
|
||||
- [Success criterion 2]
|
||||
- ...
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- [Failure criterion 1]
|
||||
- [Failure criterion 2]
|
||||
- ...
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## A/P/C Menu Convention
|
||||
|
||||
BMAD workflows use a fixed menu structure:
|
||||
|
||||
| Option | Meaning | Behavior |
|
||||
| ------ | -------------------- | ---------------------------------------------------- |
|
||||
| **A** | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu |
|
||||
| **P** | Party Mode | Execute partyModeWorkflow, then redisplay menu |
|
||||
| **C** | Continue/Accept | Save output, update frontmatter, load nextStepFile |
|
||||
| Other | Custom | Defined per step (e.g., F = Fix, X = Exit) |
|
||||
|
||||
**Rules:**
|
||||
- A and P MUST always be present
|
||||
- C MUST be present except in final step (use X or similar for exit)
|
||||
- After A/P → redisplay menu
|
||||
- After C → proceed to next step
|
||||
- Custom letters can be used for step-specific options
|
||||
|
||||
---
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
**Core Principle:** Each step only knows about its immediate next step.
|
||||
|
||||
### Implementation
|
||||
|
||||
1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C]
|
||||
|
||||
2. **Mode-aware routing** (for shared steps):
|
||||
```markdown
|
||||
## MODE-AWARE ROUTING:
|
||||
### If entered from CREATE mode:
|
||||
Load ./s-next-step.md
|
||||
|
||||
### If entered from EDIT mode:
|
||||
Load ./e-next-step.md
|
||||
|
||||
### If entered from VALIDATE mode:
|
||||
Load ./v-next-step.md
|
||||
```
|
||||
|
||||
3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing
|
||||
|
||||
---
|
||||
|
||||
## Mode-Aware Routing (Shared Steps)
|
||||
|
||||
Shared steps (`s-*.md`) must route based on the mode stored in the tracking file.
|
||||
|
||||
### Tracking File Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
mode: create # or edit | validate
|
||||
stepsCompleted:
|
||||
- c-01-brainstorm.md
|
||||
- s-01-discovery.md
|
||||
# ... other tracking fields
|
||||
---
|
||||
```
|
||||
|
||||
### Routing Implementation
|
||||
|
||||
```markdown
|
||||
## COMPLETION ROUTING:
|
||||
|
||||
1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted
|
||||
2. Save content to {trackingFile}
|
||||
3. Read {trackingFile}.mode
|
||||
4. Route based on mode:
|
||||
|
||||
### IF mode == create:
|
||||
Load ./s-next-create-step.md
|
||||
|
||||
### IF mode == edit:
|
||||
Load ./e-next-edit-step.md
|
||||
|
||||
### IF mode == validate:
|
||||
Load ./s-next-validate-step.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
### Tri-Modal Workflows
|
||||
|
||||
| Prefix | Meaning | Example |
|
||||
| ------ | ------------------ | ---------------------- |
|
||||
| `c-` | Create-specific | `c-01-brainstorm.md` |
|
||||
| `e-` | Edit-specific | `e-01-load-analyze.md` |
|
||||
| `v-` | Validate-specific | `v-01-load-review.md` |
|
||||
| `s-` | Shared by 2+ modes | `s-05-activation.md` |
|
||||
|
||||
### Numbering
|
||||
|
||||
- Within each prefix type, number sequentially
|
||||
- Restart numbering for each prefix type (c-01, e-01, v-01, s-01)
|
||||
- Use letters for sub-steps (s-06a, s-06b, s-06c)
|
||||
|
||||
---
|
||||
|
||||
## Language Preference Enforcement
|
||||
|
||||
**CRITICAL:** Every step MUST respect the user's chosen language.
|
||||
|
||||
### Implementation
|
||||
|
||||
```markdown
|
||||
### Language Preference:
|
||||
The user has chosen to communicate in the **{language}** language.
|
||||
You MUST respond in **{language}** throughout this step.
|
||||
```
|
||||
|
||||
### Reading Language Preference
|
||||
|
||||
From tracking file frontmatter:
|
||||
```yaml
|
||||
---
|
||||
userPreferences:
|
||||
language: spanish # or any language
|
||||
---
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- **MUST** read language preference from tracking file at step start
|
||||
- **MUST** respond in user's chosen language for ALL content
|
||||
- **MUST** include menu options in user's chosen language
|
||||
- **EXCEPTION:** Technical terms, file names, and code remain in English
|
||||
|
||||
---
|
||||
|
||||
## Data File References
|
||||
|
||||
When step content becomes too large (>200 lines), extract to `/data/` files:
|
||||
|
||||
### When to Extract
|
||||
|
||||
- Step file exceeds 200 lines
|
||||
- Content is reference material (rules, examples, patterns)
|
||||
- Content is reused across multiple steps
|
||||
|
||||
### How to Reference
|
||||
|
||||
```markdown
|
||||
## Reference Material:
|
||||
|
||||
Load and reference: `../data/{data-file-name}.md`
|
||||
|
||||
Key points from that file:
|
||||
- [Point 1]
|
||||
- [Point 2]
|
||||
```
|
||||
|
||||
### Data File Best Practices
|
||||
|
||||
- Keep data files focused on single topic
|
||||
- Use clear, descriptive names
|
||||
- Include examples and non-examples
|
||||
- Optimize for LLM usage (concise, structured)
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
### ❌ DON'T:
|
||||
|
||||
- Pre-load future steps (violates progressive disclosure)
|
||||
- Exceed 250 lines without splitting
|
||||
- Forget to update `stepsCompleted` array
|
||||
- Ignore user's language preference
|
||||
- Skip mode checking in shared steps
|
||||
- Use vague menu option letters (stick to A/P/C plus 1-2 custom)
|
||||
|
||||
### ✅ DO:
|
||||
|
||||
- Keep files under 200 lines
|
||||
- Read tracking file first thing
|
||||
- Route based on `mode` field
|
||||
- Include A/P in every menu
|
||||
- Use descriptive step names
|
||||
- Extract complex content to data files
|
||||
|
||||
---
|
||||
|
||||
## Template: New Step File
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: 'step-name'
|
||||
description: 'What this step does'
|
||||
|
||||
# File References
|
||||
thisStepFile: ./step-name.md
|
||||
workflowFile: ../workflow.md
|
||||
outputFile: {bmb_creations_output_folder}/output.md
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step X: [Step Name]
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
[Single sentence goal]
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are a [role] who [does what]
|
||||
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring [expertise], user brings [expertise], together we [achieve]
|
||||
- ✅ Maintain [tone] throughout
|
||||
|
||||
### Language Preference:
|
||||
The user has chosen to communicate in the **{language}** language.
|
||||
You MUST respond in **{language}** throughout this step.
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on [scope]
|
||||
- 🚫 FORBIDDEN to [prohibited action]
|
||||
- 💬 Approach: [how to engage]
|
||||
- 📋 Ensure [outcome]
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- [Action 1]
|
||||
- [Action 2]
|
||||
- 🚫 FORBIDDEN to [prohibited action]
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: [what's available]
|
||||
- Focus: [what to focus on]
|
||||
- Limits: [boundaries]
|
||||
- Dependencies: [what depends on what]
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. [First Action]
|
||||
|
||||
**Description of first action**
|
||||
|
||||
### 2. [Second Action]
|
||||
|
||||
**Description of second action**
|
||||
|
||||
...
|
||||
|
||||
### X. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`...
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- [Success criteria]
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- [Failure criteria]
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**End of Guidelines**
|
||||
@@ -0,0 +1,241 @@
|
||||
# BMAD Continuable Step 01 Init Template
|
||||
|
||||
This template provides the standard structure for step-01-init files that support workflow continuation. It includes logic to detect existing workflows and route to step-01b-continue.md for resumption.
|
||||
|
||||
Use this template when creating workflows that generate output documents and might take multiple sessions to complete.
|
||||
|
||||
<!-- TEMPLATE START -->
|
||||
|
||||
---
|
||||
|
||||
name: 'step-01-init'
|
||||
description: 'Initialize the [workflow-type] workflow by detecting continuation state and creating output document'
|
||||
|
||||
<!-- Path Definitions -->
|
||||
|
||||
workflow\*path: `{project-root}/_bmad/[module-path]/workflows/[workflow-name]`
|
||||
|
||||
# File References (all use {variable} format in file)
|
||||
|
||||
thisStepFile: `{workflow_path}/steps/step-01-init.md`
|
||||
nextStepFile: `{workflow_path}/steps/step-02-[step-name].md`
|
||||
workflowFile: `{workflow_path}/workflow.md`
|
||||
outputFile: `{output_folder}/[output-file-name]-{project_name}.md`
|
||||
continueFile: `{workflow_path}/steps/step-01b-continue.md`
|
||||
templateFile: `{workflow_path}/templates/[main-template].md`
|
||||
|
||||
# Template References
|
||||
|
||||
# This step doesn't use content templates, only the main template
|
||||
|
||||
---
|
||||
|
||||
# Step 1: Workflow Initialization
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
|
||||
- ✅ Maintain collaborative [adjective] tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus ONLY on initialization and setup
|
||||
- 🚫 FORBIDDEN to look ahead to future steps
|
||||
- 💬 Handle initialization professionally
|
||||
- 🚪 DETECT existing workflow state and handle continuation properly
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Show analysis before taking any action
|
||||
- 💾 Initialize document and update frontmatter
|
||||
- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
|
||||
- 🚫 FORBIDDEN to load next step until setup is complete
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Variables from workflow.md are available in memory
|
||||
- Previous context = what's in output document + frontmatter
|
||||
- Don't assume knowledge from other steps
|
||||
- Input document discovery happens in this step
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
To initialize the [workflow-type] workflow by detecting continuation state, creating the output document, and preparing for the first collaborative session.
|
||||
|
||||
## INITIALIZATION SEQUENCE:
|
||||
|
||||
### 1. Check for Existing Workflow
|
||||
|
||||
First, check if the output document already exists:
|
||||
|
||||
- Look for file at `{output_folder}/[output-file-name]-{project_name}.md`
|
||||
- If exists, read the complete file including frontmatter
|
||||
- If not exists, this is a fresh workflow
|
||||
|
||||
### 2. Handle Continuation (If Document Exists)
|
||||
|
||||
If the document exists and has frontmatter with `stepsCompleted`:
|
||||
|
||||
- **STOP here** and load `./step-01b-continue.md` immediately
|
||||
- Do not proceed with any initialization tasks
|
||||
- Let step-01b handle the continuation logic
|
||||
|
||||
### 3. Handle Completed Workflow
|
||||
|
||||
If the document exists AND all steps are marked complete in `stepsCompleted`:
|
||||
|
||||
- Ask user: "I found an existing [workflow-output] from [date]. Would you like to:
|
||||
1. Create a new [workflow-output]
|
||||
2. Update/modify the existing [workflow-output]"
|
||||
- If option 1: Create new document with timestamp suffix
|
||||
- If option 2: Load step-01b-continue.md
|
||||
|
||||
### 4. Fresh Workflow Setup (If No Document)
|
||||
|
||||
If no document exists or no `stepsCompleted` in frontmatter:
|
||||
|
||||
#### A. Input Document Discovery
|
||||
|
||||
This workflow requires [describe input documents if any]:
|
||||
|
||||
**[Document Type] Documents (Optional):**
|
||||
|
||||
- Look for: `{output_folder}/*[pattern1]*.md`
|
||||
- Look for: `{output_folder}/*[pattern2]*.md`
|
||||
- If found, load completely and add to `inputDocuments` frontmatter
|
||||
|
||||
#### B. Create Initial Document
|
||||
|
||||
Copy the template from `{templateFile}` to `{output_folder}/[output-file-name]-{project_name}.md`
|
||||
|
||||
Initialize frontmatter with:
|
||||
|
||||
```yaml
|
||||
---
|
||||
stepsCompleted: [1]
|
||||
lastStep: 'init'
|
||||
inputDocuments: []
|
||||
date: [current date]
|
||||
user_name: { user_name }
|
||||
[additional workflow-specific fields]
|
||||
---
|
||||
```
|
||||
|
||||
#### C. Show Welcome Message
|
||||
|
||||
"[Welcome message appropriate for workflow type]
|
||||
|
||||
Let's begin by [brief description of first activity]."
|
||||
|
||||
## ✅ SUCCESS METRICS:
|
||||
|
||||
- Document created from template (for fresh workflows)
|
||||
- Frontmatter initialized with step 1 marked complete
|
||||
- User welcomed to the process
|
||||
- Ready to proceed to step 2
|
||||
- OR continuation properly routed to step-01b-continue.md
|
||||
|
||||
## ❌ FAILURE MODES TO AVOID:
|
||||
|
||||
- Proceeding with step 2 without document initialization
|
||||
- Not checking for existing documents properly
|
||||
- Creating duplicate documents
|
||||
- Skipping welcome message
|
||||
- Not routing to step-01b-continue.md when needed
|
||||
|
||||
### 5. Present MENU OPTIONS
|
||||
|
||||
Display: **Proceeding to [next step description]...**
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- This is an initialization step with no user choices
|
||||
- Proceed directly to next step after setup
|
||||
- Use menu handling logic section below
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- After setup completion, immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description]
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
|
||||
- Document created from template (for fresh workflows)
|
||||
- update frontmatter `stepsCompleted` to add 1 at the end of the array before loading next step
|
||||
- Frontmatter initialized with `stepsCompleted: [1]`
|
||||
- User welcomed to the process
|
||||
- Ready to proceed to step 2
|
||||
- OR existing workflow properly routed to step-01b-continue.md
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
|
||||
- Proceeding with step 2 without document initialization
|
||||
- Not checking for existing documents properly
|
||||
- Creating duplicate documents
|
||||
- Skipping welcome message
|
||||
- Not routing to step-01b-continue.md when appropriate
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN initialization setup is complete and document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description].
|
||||
|
||||
<!-- TEMPLATE END -->
|
||||
|
||||
## Customization Guidelines
|
||||
|
||||
When adapting this template for your specific workflow:
|
||||
|
||||
### 1. Update Placeholders
|
||||
|
||||
Replace bracketed placeholders with your specific values:
|
||||
|
||||
- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
|
||||
- `[module-path]` - e.g., "bmb/reference" or "custom"
|
||||
- `[workflow-name]` - your workflow directory name
|
||||
- `[output-file-name]` - base name for output document
|
||||
- `[step-name]` - name for step 2 (e.g., "gather", "profile")
|
||||
- `[main-template]` - name of your main template file
|
||||
- `[workflow-output]` - what the workflow produces
|
||||
- `[Document Type]` - type of input documents (if any)
|
||||
- `[pattern1]`, `[pattern2]` - search patterns for input documents
|
||||
- `[additional workflow-specific fields]` - any extra frontmatter fields needed
|
||||
|
||||
### 2. Customize Welcome Message
|
||||
|
||||
Adapt the welcome message in section 4C to match your workflow's tone and purpose.
|
||||
|
||||
### 3. Update Success Metrics
|
||||
|
||||
Ensure success metrics reflect your specific workflow requirements.
|
||||
|
||||
### 4. Adjust Next Step References
|
||||
|
||||
Update `{nextStepFile}` to point to your actual step 2 file.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
1. **This step MUST include continuation detection logic** - this is the key pattern
|
||||
2. **Always include `continueFile` reference** in frontmatter
|
||||
3. **Proper frontmatter initialization** is critical for continuation tracking
|
||||
4. **Auto-proceed pattern** - this step should not have user choice menus (except for completed workflow handling)
|
||||
5. **Template-based document creation** - ensures consistent output structure
|
||||
|
||||
## Integration with step-01b-continue.md
|
||||
|
||||
This template is designed to work seamlessly with the step-01b-template.md continuation step. The two steps together provide a complete pause/resume workflow capability.
|
||||
@@ -0,0 +1,223 @@
|
||||
# BMAD Workflow Step 1B Continuation Template
|
||||
|
||||
This template provides the standard structure for workflow continuation steps. It handles resuming workflows that were started but not completed, ensuring seamless continuation across multiple sessions.
|
||||
|
||||
Use this template alongside **step-01-init-continuable-template.md** to create workflows that can be paused and resumed. The init template handles the detection and routing logic, while this template handles the resumption logic.
|
||||
|
||||
<!-- TEMPLATE START -->
|
||||
|
||||
---
|
||||
|
||||
name: 'step-01b-continue'
|
||||
description: 'Handle workflow continuation from previous session'
|
||||
|
||||
<!-- Path Definitions -->
|
||||
|
||||
workflow\*path: '{project-root}/_bmad/[module-path]/workflows/[workflow-name]'
|
||||
|
||||
# File References (all use {variable} format in file)
|
||||
|
||||
thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
|
||||
outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
|
||||
# Template References (if needed for analysis)
|
||||
|
||||
## analysisTemplate: '{workflow_path}/templates/[some-template].md'
|
||||
|
||||
# Step 1B: Workflow Continuation
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
To resume the [workflow-type] workflow from where it was left off, ensuring smooth continuation without loss of context or progress.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
|
||||
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
|
||||
- ✅ Maintain collaborative [adjective] tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus ONLY on analyzing and resuming workflow state
|
||||
- 🚫 FORBIDDEN to modify content completed in previous steps
|
||||
- 💬 Maintain continuity with previous sessions
|
||||
- 🚪 DETECT exact continuation point from frontmatter of incomplete file {outputFile}
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Show your analysis of current state before taking action
|
||||
- 💾 Keep existing frontmatter `stepsCompleted` values intact
|
||||
- 📖 Review the template content already generated in {outputFile}
|
||||
- 🚫 FORBIDDEN to modify content that was completed in previous steps
|
||||
- 📝 Update frontmatter with continuation timestamp when resuming
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Current [output-file-name] document is already loaded
|
||||
- Previous context = complete template + existing frontmatter
|
||||
- [Key data collected] already gathered in previous sessions
|
||||
- Last completed step = last value in `stepsCompleted` array from frontmatter
|
||||
|
||||
## CONTINUATION SEQUENCE:
|
||||
|
||||
### 1. Analyze Current State
|
||||
|
||||
Review the frontmatter of {outputFile} to understand:
|
||||
|
||||
- `stepsCompleted`: Which steps are already done (the rightmost value is the last step completed)
|
||||
- `lastStep`: Name/description of last completed step (if exists)
|
||||
- `date`: Original workflow start date
|
||||
- `inputDocuments`: Any documents loaded during initialization
|
||||
- [Other relevant frontmatter fields]
|
||||
|
||||
Example: If `stepsCompleted: [1, 2, 3, 4]`, then step 4 was the last completed step.
|
||||
|
||||
### 2. Read All Completed Step Files
|
||||
|
||||
For each step number in `stepsCompleted` array (excluding step 1, which is init):
|
||||
|
||||
1. **Construct step filename**: `step-[N]-[name].md`
|
||||
2. **Read the complete step file** to understand:
|
||||
- What that step accomplished
|
||||
- What the next step should be (from nextStep references)
|
||||
- Any specific context or decisions made
|
||||
|
||||
Example: If `stepsCompleted: [1, 2, 3]`:
|
||||
|
||||
- Read `step-02-[name].md`
|
||||
- Read `step-03-[name].md`
|
||||
- The last file will tell you what step-04 should be
|
||||
|
||||
### 3. Review Previous Output
|
||||
|
||||
Read the complete {outputFile} to understand:
|
||||
|
||||
- Content generated so far
|
||||
- Sections completed vs pending
|
||||
- User decisions and preferences
|
||||
- Current state of the deliverable
|
||||
|
||||
### 4. Determine Next Step
|
||||
|
||||
Based on the last completed step file:
|
||||
|
||||
1. **Find the nextStep reference** in the last completed step file
|
||||
2. **Validate the file exists** at the referenced path
|
||||
3. **Confirm the workflow is incomplete** (not all steps finished)
|
||||
|
||||
### 5. Welcome Back Dialog
|
||||
|
||||
Present a warm, context-aware welcome:
|
||||
|
||||
"Welcome back! I see we've completed [X] steps of your [workflow-type].
|
||||
|
||||
We last worked on [brief description of last step].
|
||||
|
||||
Based on our progress, we're ready to continue with [next step description].
|
||||
|
||||
Are you ready to continue where we left off?"
|
||||
|
||||
### 6. Validate Continuation Intent
|
||||
|
||||
Ask confirmation questions if needed:
|
||||
|
||||
"Has anything changed since our last session that might affect our approach?"
|
||||
"Are you still aligned with the goals and decisions we made earlier?"
|
||||
"Would you like to review what we've accomplished so far?"
|
||||
|
||||
### 7. Present MENU OPTIONS
|
||||
|
||||
Display: "**Resuming workflow - Select an Option:** [C] Continue to [Next Step Name]"
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
- Update frontmatter with continuation timestamp when 'C' is selected
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF C:
|
||||
1. Update frontmatter: add `lastContinued: [current date]`
|
||||
2. Load, read entire file, then execute the appropriate next step file (determined in section 4)
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN C is selected and continuation analysis is complete, will you then:
|
||||
|
||||
1. Update frontmatter in {outputFile} with continuation timestamp
|
||||
2. Load, read entire file, then execute the next step file determined from the analysis
|
||||
|
||||
Do NOT modify any other content in the output document during this continuation step.
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
|
||||
- Correctly identified last completed step from `stepsCompleted` array
|
||||
- Read and understood all previous step contexts
|
||||
- User confirmed readiness to continue
|
||||
- Frontmatter updated with continuation timestamp
|
||||
- Workflow resumed at appropriate next step
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
|
||||
- Skipping analysis of existing state
|
||||
- Modifying content from previous steps
|
||||
- Loading wrong next step file
|
||||
- Not updating frontmatter with continuation info
|
||||
- Proceeding without user confirmation
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
||||
<!-- TEMPLATE END -->
|
||||
|
||||
## Customization Guidelines
|
||||
|
||||
When adapting this template for your specific workflow:
|
||||
|
||||
### 1. Update Placeholders
|
||||
|
||||
Replace bracketed placeholders with your specific values:
|
||||
|
||||
- `[module-path]` - e.g., "bmb/reference" or "custom"
|
||||
- `[workflow-name]` - your workflow directory name
|
||||
- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
|
||||
- `[output-file-name]` - base name for output document
|
||||
- `[specific role]` - the role this workflow plays
|
||||
- `[your expertise]` - what expertise you bring
|
||||
- `[their expertise]` - what expertise user brings
|
||||
|
||||
### 2. Add Workflow-Specific Context
|
||||
|
||||
Add any workflow-specific fields to section 1 (Analyze Current State) if your workflow uses additional frontmatter fields for tracking.
|
||||
|
||||
### 3. Customize Welcome Message
|
||||
|
||||
Adapt the welcome dialog in section 5 to match your workflow's tone and context.
|
||||
|
||||
### 4. Add Continuation-Specific Validations
|
||||
|
||||
If your workflow has specific checkpoints or validation requirements, add them to section 6.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
1. **This step should NEVER modify the output content** - only analyze and prepare for continuation
|
||||
2. **Always preserve the `stepsCompleted` array** - don't modify it in this step
|
||||
3. **Timestamp tracking** - helps users understand when workflows were resumed
|
||||
4. **Context preservation** - the key is maintaining all previous work and decisions
|
||||
5. **Seamless experience** - user should feel like they never left the workflow
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: "step-{{stepNumber}}-{{stepName}}"
|
||||
description: "{{stepDescription}}"
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: "{project-root}/_bmad/{{targetModule}}/workflows/{{workflowName}}"
|
||||
|
||||
# File References
|
||||
thisStepFile: "{workflow_path}/steps/step-{{stepNumber}}-{{stepName}}.md"
|
||||
{{#hasNextStep}}
|
||||
nextStepFile: "{workflow_path}/steps/step-{{nextStepNumber}}-{{nextStepName}}.md"
|
||||
{{/hasNextStep}}
|
||||
workflowFile: "{workflow_path}/workflow.md"
|
||||
{{#hasOutput}}
|
||||
outputFile: "{output_folder}/{{outputFileName}}-{project_name}.md"
|
||||
{{/hasOutput}}
|
||||
|
||||
# Task References (list only if used in THIS step file instance and only the ones used, there might be others)
|
||||
advancedElicitationTask: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml"
|
||||
partyModeWorkflow: "{project-root}/_bmad/core/workflows/party-mode/workflow.md"
|
||||
|
||||
{{#hasTemplates}}
|
||||
# Template References
|
||||
{{#templates}}
|
||||
{{name}}: "{workflow_path}/templates/{{file}}"
|
||||
{{/templates}}
|
||||
{{/hasTemplates}}
|
||||
---
|
||||
|
||||
# Step {{stepNumber}}: {{stepTitle}}
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
{{stepGoal}}
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are a {{aiRole}}
|
||||
- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring {{aiExpertise}}, user brings {{userExpertise}}
|
||||
- ✅ Maintain collaborative {{collaborationStyle}} tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on {{stepFocus}}
|
||||
- 🚫 FORBIDDEN to {{forbiddenAction}}
|
||||
- 💬 Approach: {{stepApproach}}
|
||||
- 📋 {{additionalRule}}
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
{{#executionProtocols}}
|
||||
|
||||
- 🎯 {{.}}
|
||||
{{/executionProtocols}}
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: {{availableContext}}
|
||||
- Focus: {{contextFocus}}
|
||||
- Limits: {{contextLimits}}
|
||||
- Dependencies: {{contextDependencies}}
|
||||
|
||||
## SEQUENCE OF INSTRUCTIONS (Do not deviate, skip, or optimize)
|
||||
|
||||
{{#instructions}}
|
||||
|
||||
### {{number}}. {{title}}
|
||||
|
||||
{{content}}
|
||||
|
||||
{{#hasContentToAppend}}
|
||||
|
||||
#### Content to Append (if applicable):
|
||||
|
||||
```markdown
|
||||
{{contentToAppend}}
|
||||
```
|
||||
|
||||
{{/hasContentToAppend}}
|
||||
|
||||
{{/instructions}}
|
||||
|
||||
{{#hasMenu}}
|
||||
|
||||
### {{menuNumber}}. Present MENU OPTIONS
|
||||
|
||||
Display: **{{menuDisplay}}**
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
- Use menu handling logic section below
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
{{#menuOptions}}
|
||||
|
||||
- IF {{key}}: {{action}}
|
||||
{{/menuOptions}}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#{{menuNumber}}-present-menu-options)
|
||||
{{/hasMenu}}
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
{{completionNote}}
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
|
||||
{{#successCriteria}}
|
||||
|
||||
- {{.}}
|
||||
{{/successCriteria}}
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
|
||||
{{#failureModes}}
|
||||
|
||||
- {{.}}
|
||||
{{/failureModes}}
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,290 @@
|
||||
# BMAD Workflow Step Template
|
||||
|
||||
This template provides the standard structure for all BMAD workflow step files. Copy and modify this template for each new step you create.
|
||||
|
||||
<!-- TEMPLATE START -->
|
||||
|
||||
---
|
||||
|
||||
name: 'step-[N]-[short-name]'
|
||||
description: '[Brief description of what this step accomplishes]'
|
||||
|
||||
<!-- Path Definitions -->
|
||||
|
||||
workflow\*path: '{project-root}/_bmad/[module]/reference/workflows/[workflow-name]' # the folder the workflow.md file is in
|
||||
|
||||
# File References (all use {variable} format in file)
|
||||
|
||||
thisStepFile: '{workflow_path}/steps/step-[N]-[short-name].md'
|
||||
nextStep{N+1}: '{workflow_path}/steps/step-[N+1]-[next-short-name].md' # Remove for final step or no next step
|
||||
altStep{Y}: '{workflow_path}/steps/step-[Y]-[some-other-step].md' # if there is an alternate next story depending on logic
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
|
||||
|
||||
# Task References (IF THE workflow uses and it makes sense in this step to have these )
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
|
||||
# Template References (if this step uses a specific templates)
|
||||
|
||||
profileTemplate: '{workflow_path}/templates/profile-section.md'
|
||||
assessmentTemplate: '{workflow_path}/templates/assessment-section.md'
|
||||
strategyTemplate: '{workflow_path}/templates/strategy-section.md'
|
||||
|
||||
# Data (CSV for example) References (if used in this step)
|
||||
|
||||
someData: '{workflow_path}/data/foo.csv'
|
||||
|
||||
# Add more as needed - but ONLY what is used in this specific step file!
|
||||
|
||||
---
|
||||
|
||||
# Step [N]: [Step Name]
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
[State the goal in context of the overall workflow goal. Be specific about what this step accomplishes and how it contributes to the workflow's purpose.]
|
||||
|
||||
Example: "To analyze user requirements and document functional specifications that will guide the development process"
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
|
||||
- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
|
||||
- ✅ Maintain collaborative [adjective] tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on [specific task for this step]
|
||||
- 🚫 FORBIDDEN to [what not to do in this step]
|
||||
- 💬 Approach: [how to handle this specific task]
|
||||
- 📋 Additional rule relevant to this step
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 [Step-specific protocol 1]
|
||||
- 💾 [Step-specific protocol 2 - e.g., document updates]
|
||||
- 📖 [Step-specific protocol 3 - e.g., tracking requirements]
|
||||
- 🚫 [Step-specific restriction]
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: [what context is available from previous steps]
|
||||
- Focus: [what this step should concentrate on]
|
||||
- Limits: [what not to assume or do]
|
||||
- Dependencies: [what this step depends on]
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
[Detailed instructions for the step's work]
|
||||
|
||||
### 1. Title
|
||||
|
||||
[Specific instructions for first part of the work]
|
||||
|
||||
### 2. Title
|
||||
|
||||
[Specific instructions for second part of the work]
|
||||
|
||||
### N. Title (as many as needed)
|
||||
|
||||
<!-- not ever step will include advanced elicitation or party mode, in which case generally will just have the C option -->
|
||||
<!-- for example an init step 1 that loads data, or step 1b continues a workflow would not need advanced elicitation or party mode - but any step where the user and the llm work together on content, thats where it makes sense to include them -->
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: Execute {advancedElicitationTask} # Or custom action
|
||||
- IF P: Execute {partyModeWorkflow} # Or custom action
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution completes, redisplay the menu
|
||||
- User can chat or ask questions - always respond when conversation ends, redisplay the menu
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
[Specific conditions for completing this step and transitioning to the next, such as output to file being created with this tasks updates]
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [completion requirements], will you then load and read fully `[installed_path]/step-[next-number]-[name].md` to execute and begin [next step description].
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
|
||||
- [Step-specific success criteria 1]
|
||||
- [Step-specific success criteria 2]
|
||||
- Content properly saved/document updated
|
||||
- Menu presented and user input handled correctly
|
||||
- [General success criteria]
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
|
||||
- [Step-specific failure mode 1]
|
||||
- [Step-specific failure mode 2]
|
||||
- Proceeding without user input/selection
|
||||
- Not updating required documents/frontmatter
|
||||
- [Step-specific failure mode N]
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
||||
<!-- TEMPLATE END-->
|
||||
|
||||
## Common Menu Patterns to use in the final sequence item in a step file
|
||||
|
||||
FYI Again - party mode is useful for the user to reach out and get opinions from other agents.
|
||||
|
||||
Advanced elicitation is use to direct you to think of alternative outputs of a sequence you just performed.
|
||||
|
||||
### Standard Menu - when a sequence in a step results in content produced by the agent or human that could be improved before proceeding
|
||||
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [A] [Advanced Elicitation] [P] Party Mode [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: Execute {advancedElicitationTask}
|
||||
- IF P: Execute {partyModeWorkflow}
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
```
|
||||
|
||||
### Optional Menu - Auto-Proceed Menu (No User Choice or confirm, just flow right to the next step once completed)
|
||||
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Proceeding to [next action]...**"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- After [completion condition], immediately load, read entire file, then execute {nextStepFile}
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- This is an [auto-proceed reason] step with no user choices
|
||||
- Proceed directly to next step after setup
|
||||
```
|
||||
|
||||
### Custom Menu Options
|
||||
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [A] [Custom Action 1] [B] [Custom Action 2] [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: [Custom handler route for option A]
|
||||
- IF B: [Custom handler route for option B]
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
```
|
||||
|
||||
### Conditional Menu (Based on Workflow State)
|
||||
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [A] [Continue to Step Foo] [A] [Continue to Step Bar]"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: Execute {customAction}
|
||||
- IF C: Save content to {outputFile}, update frontmatter, check [condition]:
|
||||
- IF [condition true]: load, read entire file, then execute {pathA}
|
||||
- IF [condition false]: load, read entire file, then execute {pathB}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
- User can chat or ask questions - always respond and then end with display again of the menu options
|
||||
```
|
||||
|
||||
## Example Step Implementations
|
||||
|
||||
### Initialization Step Example
|
||||
|
||||
See [step-01-init.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01-init.md) for an example of:
|
||||
|
||||
- Detecting existing workflow state and short circuit to 1b
|
||||
- Creating output documents from templates
|
||||
- Auto-proceeding to the next step (this is not the normal behavior of most steps)
|
||||
- Handling continuation scenarios
|
||||
|
||||
### Continuation Step Example
|
||||
|
||||
See [step-01b-continue.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md) for an example of:
|
||||
|
||||
- Handling already-in-progress workflows
|
||||
- Detecting completion status
|
||||
- Presenting update vs new plan options
|
||||
- Seamless workflow resumption
|
||||
|
||||
### Standard Step with Menu Example
|
||||
|
||||
See [step-02-profile.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-02-profile.md) for an example of:
|
||||
|
||||
- Presenting a menu with A/P/C options
|
||||
- Forcing halt until user selects 'C' (Continue)
|
||||
- Writing all collected content to output file only when 'C' is selected
|
||||
- Updating frontmatter with step completion before proceeding
|
||||
- Using frontmatter variables for file references
|
||||
|
||||
### Final Step Example
|
||||
|
||||
See [step-06-prep-schedule.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-06-prep-schedule.md) for an example of:
|
||||
|
||||
- Completing workflow deliverables
|
||||
- Marking workflow as complete in frontmatter
|
||||
- Providing final success messages
|
||||
- Ending the workflow session gracefully
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep step files focused** - Each step should do one thing well
|
||||
2. **Be explicit in instructions** - No ambiguity about what to do
|
||||
3. **Include all critical rules** - Don't assume anything from other steps
|
||||
4. **Use clear, concise language** - Avoid jargon unless necessary
|
||||
5. **Ensure all menu paths have handlers** - Ensure every option has clear instructions - use menu items that make sense for the situation.
|
||||
6. **Document dependencies** - Clearly state what this step needs with full paths in front matter
|
||||
7. **Define success and failure clearly** - Both for the step and the workflow
|
||||
8. **Mark completion clearly** - Ensure final steps update frontmatter to indicate workflow completion
|
||||
@@ -0,0 +1,104 @@
|
||||
# BMAD Workflow Template
|
||||
|
||||
This template provides the standard structure for all BMAD workflow files. Copy and modify this template for each new workflow you create.
|
||||
|
||||
<!-- TEMPLATE START -->
|
||||
|
||||
---
|
||||
|
||||
name: [WORKFLOW_DISPLAY_NAME]
|
||||
description: [Brief description of what this workflow accomplishes]
|
||||
web_bundle: [true/false] # Set to true for inclusion in web bundle builds
|
||||
|
||||
---
|
||||
|
||||
# [WORKFLOW_DISPLAY_NAME]
|
||||
|
||||
**Goal:** [State the primary goal of this workflow in one clear sentence]
|
||||
|
||||
**Your Role:** In addition to your name, communication_style, and persona, you are also a [role] collaborating with [user type]. This is a partnership, not a client-vendor relationship. You bring [your expertise], while the user brings [their expertise]. Work together as equals.
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
### Core Principles
|
||||
|
||||
- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
|
||||
- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
|
||||
- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
|
||||
- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
|
||||
- **Append-Only Building**: Build documents by appending content as directed to the output file
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Always read the entire step file before taking any action
|
||||
2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
|
||||
3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
|
||||
4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
|
||||
5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
|
||||
6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
|
||||
|
||||
### Critical Rules (NO EXCEPTIONS)
|
||||
|
||||
- 🛑 **NEVER** load multiple step files simultaneously
|
||||
- 📖 **ALWAYS** read entire step file before execution
|
||||
- 🚫 **NEVER** skip steps or optimize the sequence
|
||||
- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
|
||||
- 🎯 **ALWAYS** follow the exact instructions in the step file
|
||||
- ⏸️ **ALWAYS** halt at menus and wait for user input
|
||||
- 📋 **NEVER** create mental todo lists from future steps
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Module Configuration Loading
|
||||
|
||||
Load and read full config from {project-root}/_bmad/[MODULE FOLDER]/config.yaml and resolve:
|
||||
|
||||
- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, [MODULE VARS]
|
||||
|
||||
### 2. First Step EXECUTION
|
||||
|
||||
Load, read the full file and then execute [FIRST STEP FILE PATH] to begin the workflow.
|
||||
|
||||
<!-- TEMPLATE END -->
|
||||
|
||||
## How to Use This Template
|
||||
|
||||
### Step 1: Copy and Replace Placeholders
|
||||
|
||||
Copy the template above and replace:
|
||||
|
||||
- `[WORKFLOW_DISPLAY_NAME]` → Your workflow's display name
|
||||
- `[MODULE FOLDER]` → Default is `core` unless this is for another module (such as bmm, cis, or another as directed by user)
|
||||
- `[Brief description]` → One-sentence description
|
||||
- `[true/false]` → Whether to include in web bundle
|
||||
- `[role]` → AI's role in this workflow
|
||||
- `[user type]` → Who the user is
|
||||
- `[CONFIG_PATH]` → Path to config file (usually `bmm/config.yaml` or `bmb/config.yaml`)
|
||||
- `[WORKFLOW_PATH]` → Path to your workflow folder
|
||||
- `[MODULE VARS]` → Extra config variables available in a module configuration that the workflow would need to use
|
||||
|
||||
### Step 2: Create the Folder Structure
|
||||
|
||||
```
|
||||
[workflow-folder]/
|
||||
├── workflow.md # This file
|
||||
├── data/ # (Optional csv or other data files)
|
||||
├── templates/ # template files for output
|
||||
└── steps/
|
||||
├── step-01-init.md
|
||||
├── step-02-[name].md
|
||||
└── ...
|
||||
|
||||
```
|
||||
|
||||
### Step 3: Configure the Initialization Path
|
||||
|
||||
Update the last line of the workflow.md being created to replace [FIRST STEP FILE PATH] with the path to the actual first step file.
|
||||
|
||||
Example: Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.
|
||||
|
||||
### NOTE: You can View a real example of a perfect workflow.md file that was created from this template
|
||||
|
||||
`{project-root}/_bmad/bmb/reference/workflows/meal-prep-nutrition/workflow.md`
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: { { workflowDisplayName } }
|
||||
description: { { workflowDescription } }
|
||||
web_bundle: { { webBundleFlag } }
|
||||
---
|
||||
|
||||
# {{workflowDisplayName}}
|
||||
|
||||
**Goal:** {{workflowGoal}}
|
||||
|
||||
**Your Role:** In addition to your name, communication_style, and persona, you are also a {{aiRole}} collaborating with {{userType}}. This is a partnership, not a client-vendor relationship. You bring {{aiExpertise}}, while the user brings {{userExpertise}}. Work together as equals.
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for disciplined execution:
|
||||
|
||||
### Core Principles
|
||||
|
||||
- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
|
||||
- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
|
||||
- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
|
||||
- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
|
||||
- **Append-Only Building**: Build documents by appending content as directed to the output file
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Always read the entire step file before taking any action
|
||||
2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
|
||||
3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
|
||||
4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
|
||||
5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
|
||||
6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
|
||||
|
||||
### Critical Rules (NO EXCEPTIONS)
|
||||
|
||||
- 🛑 **NEVER** load multiple step files simultaneously
|
||||
- 📖 **ALWAYS** read entire step file before execution
|
||||
- 🚫 **NEVER** skip steps or optimize the sequence
|
||||
- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
|
||||
- 🎯 **ALWAYS** follow the exact instructions in the step file
|
||||
- ⏸️ **ALWAYS** halt at menus and wait for user input
|
||||
- 📋 **NEVER** create mental todo lists from future steps
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Configuration Loading
|
||||
|
||||
Load and read full config from {project-root}/_bmad/{{targetModule}}/config.yaml and resolve:
|
||||
|
||||
- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
|
||||
|
||||
### 2. First Step EXECUTION
|
||||
|
||||
Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.
|
||||
@@ -0,0 +1,97 @@
|
||||
# BMAD Workflow Terms
|
||||
|
||||
## Core Components
|
||||
|
||||
### BMAD Workflow
|
||||
|
||||
A facilitated, guided process where the AI acts as a facilitator working collaboratively with a human. Workflows can serve any purpose - from document creation to brainstorming, technical implementation, or decision-making. The human may be a collaborative partner, beginner seeking guidance, or someone who wants the AI to execute specific tasks. Each workflow is self-contained and follows a disciplined execution model.
|
||||
|
||||
### workflow.md
|
||||
|
||||
The master control file that defines:
|
||||
|
||||
- Workflow metadata (name, description, version)
|
||||
- Step sequence and file paths
|
||||
- Required data files and dependencies
|
||||
- Execution rules and protocols
|
||||
|
||||
### Step File
|
||||
|
||||
An individual markdown file containing:
|
||||
|
||||
- One discrete step of the workflow
|
||||
- All rules and context needed for that step
|
||||
- common global rules get repeated and reinforced also in each step file, ensuring even in long workflows the agent remembers important rules and guidelines
|
||||
- Content generation guidance
|
||||
|
||||
### step-01-init.md
|
||||
|
||||
The first step file that:
|
||||
|
||||
- Initializes the workflow
|
||||
- Sets up document frontmatter
|
||||
- Establishes initial context
|
||||
- Defines workflow parameters
|
||||
|
||||
### step-01b-continue.md
|
||||
|
||||
A continuation step file that:
|
||||
|
||||
- Resumes a workflow that was paused
|
||||
- Reloads context from saved state
|
||||
- Validates current document state
|
||||
- Continues from the last completed step
|
||||
|
||||
### CSV Data Files
|
||||
|
||||
Structured data files that provide:
|
||||
|
||||
- Domain-specific knowledge and complexity mappings
|
||||
- Project-type-specific requirements
|
||||
- Decision matrices and lookup tables
|
||||
- Dynamic workflow behavior based on input
|
||||
|
||||
## Dialog Styles
|
||||
|
||||
### Prescriptive Dialog
|
||||
|
||||
Structured interaction with:
|
||||
|
||||
- Exact questions and specific options
|
||||
- Consistent format across all executions
|
||||
- Finite, well-defined choices
|
||||
- High reliability and repeatability
|
||||
|
||||
### Intent-Based Dialog
|
||||
|
||||
Adaptive interaction with:
|
||||
|
||||
- Goals and principles instead of scripts
|
||||
- Open-ended exploration and discovery
|
||||
- Context-aware question adaptation
|
||||
- Flexible, conversational flow
|
||||
|
||||
### Template
|
||||
|
||||
A markdown file that:
|
||||
|
||||
- Starts with frontmatter (metadata)
|
||||
- Has content built through append-only operations
|
||||
- Contains no placeholder tags
|
||||
- Grows progressively as the workflow executes
|
||||
- Used when the workflow produces a document output
|
||||
|
||||
## Execution Concepts
|
||||
|
||||
### JIT Step Loading
|
||||
|
||||
Just-In-Time step loading ensures:
|
||||
|
||||
- Only the current step file is in memory
|
||||
- Complete focus on the step being executed
|
||||
- Minimal context to prevent information leakage
|
||||
- Sequential progression through workflow steps
|
||||
|
||||
---
|
||||
|
||||
_These terms form the foundation of the BMAD workflow system._
|
||||
Reference in new issue
Block a user