bmad-method 4.21.2 → 4.22.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [4.22.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.22.0...v4.22.1) (2025-06-30)
+
+
+### Bug Fixes
+
+* update expansion versions ([6905fe7](https://github.com/bmadcode/BMAD-METHOD/commit/6905fe72f6c2abefbfd65729d1be85752130a1d2))
+
+# [4.22.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.21.2...v4.22.0) (2025-06-30)
+
+
+### Features
+
+* create doc more explicit and readme improvement ([a1b30d9](https://github.com/bmadcode/BMAD-METHOD/commit/a1b30d9341d2ceff79db2c7e178860c5ef0d99e5))
+
 ## [4.21.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.21.1...v4.21.2) (2025-06-30)
 
 

package/README.md

@@ -13,7 +13,7 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
 
 ⭐ **If you find this project helpful or useful, please give it a star in the upper right hand corner!** It helps others discover BMad-METHOD and you will be notified of updates!
 
-## 🧭 Quick Navigation - Find Your Path
+## Quick Navigation
 
 ### 🚨 MUST READ: Understanding the BMAD Workflow
 
@@ -50,13 +50,14 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
 - **[Contributing](#contributing)** → Help improve BMAD
 - **[Support](#support)** → Get help and connect
 
-## 🔄 Important: Keeping Your BMad Installation Updated
+## Important: Keep Your BMad Installation Updated
 
 **Stay up-to-date effortlessly!** If you already have BMad-METHOD installed in your project, simply run:
 
 ```bash
 npx bmad-method install
 # OR
+git pull
 npm run install:bmad
 ```
 
@@ -69,7 +70,7 @@ This will:
 
 This makes it easy to benefit from the latest improvements, bug fixes, and new agents without losing your customizations! If for some reason this fails, you can rename or remove your .bmad-code folder and run the install again. The main thing to look out for is if you have set up custom modes that are not file driven (Cursor is the only one at this time that is not done through project files lagging behind) - you will want to ensure your sm and dev custom modes especially are kept up to date.
 
-## 🚀 Quick Start
+## Quick Start
 
 ### One Command for Everything (IDE Installation)
 
@@ -78,6 +79,7 @@ This makes it easy to benefit from the latest improvements, bug fixes, and new a
 ```bash
 npx bmad-method install
 # OR if you already have BMad installed:
+git pull
 npm run install:bmad
 ```
 

package/bmad-core/core-config.yml

@@ -1,4 +1,4 @@
-version: 4.20.1
+version: 4.21.1
 markdownExploder: true
 prd:
   prdFile: docs/prd.md

package/dist/agents/analyst.txt

@@ -652,76 +652,73 @@ Present these numbered options to the user:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
+- Use @{examples} for guidance but never output them
 
-### 4. Template Processing Rules
+### 4. Key Execution Patterns
 
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
-- Use @{examples} for guidance but never output them
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-### 5. Content Generation
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- **Incremental Mode**: Present each major section for review before proceeding
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 6. Validation
+### 5. Validation & Final Presentation
 
-If template specifies a checklist:
+- Run any specified checklists
+- Present clean, formatted content only
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-- Run the appropriate checklist against completed document
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+## Common Mistakes to Avoid
 
-### 7. Final Presentation
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
 
-- Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
 
-## Important Notes
+## Remember
 
-- Template markup is for AI processing only - never expose to users
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#advanced-elicitation ====================

package/dist/agents/architect.txt

@@ -107,76 +107,73 @@ dependencies:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
-
-### 1. Identify Template and Context
-
-- Determine which template to use (user-provided or list available for selection to user)
+## CRITICAL RULES
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+## Execution Flow
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 1. Identify Template
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
 
-### 2. Determine Interaction Mode
+### 2. Ask Interaction Mode
 
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
+- Use @{examples} for guidance but never output them
 
-### 4. Template Processing Rules
+### 4. Key Execution Patterns
 
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
-- Use @{examples} for guidance but never output them
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-### 5. Content Generation
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- **Incremental Mode**: Present each major section for review before proceeding
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 6. Validation
+### 5. Validation & Final Presentation
 
-If template specifies a checklist:
+- Run any specified checklists
+- Present clean, formatted content only
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-- Run the appropriate checklist against completed document
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+## Common Mistakes to Avoid
 
-### 7. Final Presentation
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
 
-- Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
 
-## Important Notes
+## Remember
 
-- Template markup is for AI processing only - never expose to users
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#create-deep-research-prompt ====================

package/dist/agents/bmad-master.txt

@@ -1173,76 +1173,73 @@ Present these numbered options to the user:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
-
-### 1. Identify Template and Context
-
-- Determine which template to use (user-provided or list available for selection to user)
+## CRITICAL RULES
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
-
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+## Execution Flow
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
+- Use @{examples} for guidance but never output them
 
-### 4. Template Processing Rules
+### 4. Key Execution Patterns
 
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
-- Use @{examples} for guidance but never output them
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-### 5. Content Generation
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- **Incremental Mode**: Present each major section for review before proceeding
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 6. Validation
+### 5. Validation & Final Presentation
 
-If template specifies a checklist:
+- Run any specified checklists
+- Present clean, formatted content only
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-- Run the appropriate checklist against completed document
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+## Common Mistakes to Avoid
 
-### 7. Final Presentation
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
 
-- Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
 
-## Important Notes
+## Remember
 
-- Template markup is for AI processing only - never expose to users
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#document-project ====================

package/dist/agents/bmad-orchestrator.txt

@@ -263,76 +263,73 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
-
-### 1. Identify Template and Context
-
-- Determine which template to use (user-provided or list available for selection to user)
+## CRITICAL RULES
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
-
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+## Execution Flow
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
+- Use @{examples} for guidance but never output them
 
-### 4. Template Processing Rules
+### 4. Key Execution Patterns
 
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
-- Use @{examples} for guidance but never output them
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-### 5. Content Generation
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- **Incremental Mode**: Present each major section for review before proceeding
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 6. Validation
+### 5. Validation & Final Presentation
 
-If template specifies a checklist:
+- Run any specified checklists
+- Present clean, formatted content only
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-- Run the appropriate checklist against completed document
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+## Common Mistakes to Avoid
 
-### 7. Final Presentation
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
 
-- Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
 
-## Important Notes
+## Remember
 
-- Template markup is for AI processing only - never expose to users
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#kb-mode-interaction ====================