bmad-method 6.0.0-alpha.13 → 6.0.0-alpha.15

package/src/modules/bmb/docs/agents/module-agent-architecture.md

@@ -27,7 +27,7 @@ Compiles to:
 ```yaml
 agent:
   metadata:
-    id: '{bmad_folder}/{module-code}/agents/{agent-name}.md'
+    id: '{*bmad_folder*}/{module-code}/agents/{agent-name}.md'
     name: 'Persona Name'
     title: 'Professional Title'
     icon: 'emoji'
@@ -41,29 +41,29 @@ agent:
 
   menu:
     - trigger: workflow-action
-      workflow: '{project-root}/{bmad_folder}/{module-code}/workflows/{workflow-name}/workflow.yaml'
+      workflow: '{project-root}/{*bmad_folder*}/{module-code}/workflows/{workflow-name}/workflow.yaml'
       description: 'Execute module workflow'
 
     - trigger: another-workflow
-      workflow: '{project-root}/{bmad_folder}/core/workflows/{workflow-name}/workflow.yaml'
+      workflow: '{project-root}/{*bmad_folder*}/core/workflows/{workflow-name}/workflow.yaml'
       description: 'Execute core workflow'
 
     - trigger: task-action
-      exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml'
+      exec: '{project-root}/{*bmad_folder*}/{module-code}/tasks/{task-name}.xml'
       description: 'Execute module task'
 
     - trigger: cross-module
-      workflow: '{project-root}/{bmad_folder}/other-module/workflows/{workflow-name}/workflow.yaml'
+      workflow: '{project-root}/{*bmad_folder*}/other-module/workflows/{workflow-name}/workflow.yaml'
       description: 'Execute workflow from another module'
 
     - trigger: with-template
-      exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
-      tmpl: '{project-root}/{bmad_folder}/{module-code}/templates/{template-name}.md'
+      exec: '{project-root}/{*bmad_folder*}/core/tasks/create-doc.xml'
+      tmpl: '{project-root}/{*bmad_folder*}/{module-code}/templates/{template-name}.md'
       description: 'Create document from template'
 
     - trigger: with-data
-      exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml'
-      data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv'
+      exec: '{project-root}/{*bmad_folder*}/{module-code}/tasks/{task-name}.xml'
+      data: '{project-root}/{*bmad_folder*}/_cfg/agent-manifest.csv'
       description: 'Execute task with data file'
 ```
 
@@ -71,7 +71,7 @@ agent:
 
 ### Metadata
 
-- **id**: Path with `{bmad_folder}` variable (resolved at install time)
+- **id**: Path with `{*bmad_folder*}` variable (resolved at install time)
 - **name**: Agent persona name
 - **title**: Professional role
 - **icon**: Single emoji
@@ -101,7 +101,7 @@ persona:
 ```yaml
 menu:
   - trigger: create-prd
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/prd/workflow.yaml'
     description: 'Create Product Requirements Document'
 ```
 
@@ -112,7 +112,7 @@ Invokes BMAD workflow engine to execute multi-step processes.
 ```yaml
 menu:
   - trigger: validate
-    exec: '{project-root}/{bmad_folder}/core/tasks/validate-workflow.xml'
+    exec: '{project-root}/{*bmad_folder*}/core/tasks/validate-workflow.xml'
     description: 'Validate document structure'
 ```
 
@@ -123,8 +123,8 @@ Executes single-operation tasks.
 ```yaml
 menu:
   - trigger: create-brief
-    exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
-    tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md'
+    exec: '{project-root}/{*bmad_folder*}/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/{*bmad_folder*}/bmm/templates/brief.md'
     description: 'Create a Product Brief from template'
 ```
 
@@ -135,8 +135,8 @@ Combines task execution with template file.
 ```yaml
 menu:
   - trigger: team-standup
-    exec: '{project-root}/{bmad_folder}/bmm/tasks/standup.xml'
-    data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv'
+    exec: '{project-root}/{*bmad_folder*}/bmm/tasks/standup.xml'
+    data: '{project-root}/{*bmad_folder*}/_cfg/agent-manifest.csv'
     description: 'Run team standup with agent roster'
 ```
 
@@ -160,12 +160,12 @@ Control visibility based on platform:
 ```yaml
 menu:
   - trigger: advanced-elicitation
-    exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
+    exec: '{project-root}/{*bmad_folder*}/core/tasks/advanced-elicitation.xml'
     description: 'Advanced elicitation techniques'
     web-only: true # Only shows in web bundle
 
   - trigger: git-operations
-    exec: '{project-root}/{bmad_folder}/bmm/tasks/git-flow.xml'
+    exec: '{project-root}/{*bmad_folder*}/bmm/tasks/git-flow.xml'
     description: 'Git workflow operations'
     ide-only: true # Only shows in IDE environments
 ```
@@ -175,7 +175,7 @@ menu:
 ### Core Variables
 
 - `{project-root}` - Root directory of installed project
-- `{bmad_folder}` - BMAD installation folder (usually `.bmad`)
+- `{*bmad_folder*}` - BMAD installation folder (usually `.bmad`)
 - `{user_name}` - User's name from module config
 - `{communication_language}` - Language preference
 - `{output_folder}` - Document output directory
@@ -186,7 +186,7 @@ menu:
 
 ```yaml
 # GOOD
-workflow: "{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml"
+workflow: "{project-root}/{*bmad_folder*}/bmm/workflows/prd/workflow.yaml"
 
 # BAD
 workflow: "/Users/john/project/.bmad/bmm/workflows/prd/workflow.yaml"
@@ -203,12 +203,12 @@ Module agents use the same injection process as simple agents:
 2. **Activation block** with standard steps
 3. **Menu handlers** based on usage (workflow, exec, tmpl, data)
 4. **Rules section** for consistent behavior
-5. **Auto-injected** *help and *exit commands
+5. **Auto-injected** \*help and \*exit commands
 
 **Key difference:** Module agents load **module-specific config** instead of core config:
 
 ```xml
-<step n="2">Load and read {project-root}/{bmad_folder}/{module}/config.yaml...</step>
+<step n="2">Load and read {project-root}/{*bmad_folder*}/{module}/config.yaml...</step>
 ```
 
 ## Reference Examples
@@ -252,15 +252,15 @@ Agents load this at activation for consistent behavior.
 ```yaml
 menu:
   - trigger: init
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-init/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/workflow-init/workflow.yaml'
     description: 'Initialize workflow path (START HERE)'
 
   - trigger: status
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/workflow-status/workflow.yaml'
     description: 'Check current workflow status'
 
   - trigger: next-step
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/next-step/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/next-step/workflow.yaml'
     description: 'Execute next workflow in sequence'
 ```
 
@@ -270,20 +270,20 @@ menu:
 menu:
   # Phase 1: Analysis
   - trigger: brainstorm
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
     description: 'Guided brainstorming session'
 
   - trigger: research
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/1-analysis/research/workflow.yaml'
     description: 'Market and technical research'
 
   # Phase 2: Planning
   - trigger: prd
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/prd/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/2-planning/prd/workflow.yaml'
     description: 'Create PRD'
 
   - trigger: architecture
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/2-planning/architecture/workflow.yaml'
     description: 'Design architecture'
 ```
 
@@ -292,17 +292,17 @@ menu:
 ```yaml
 menu:
   - trigger: party-mode
-    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/core/workflows/party-mode/workflow.yaml'
     description: 'Bring all agents together'
 
   - trigger: brainstorm
-    workflow: '{project-root}/{bmad_folder}/cis/workflows/brainstorming/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/cis/workflows/brainstorming/workflow.yaml'
     description: 'Use CIS brainstorming techniques'
 ```
 
 ## Best Practices
 
-1. **Use {bmad_folder} paths** - Portable across installations
+1. **Use {_bmad_folder_} paths** - Portable across installations
 2. **Organize workflows by phase** - Clear progression for users
 3. **Include workflow-status** - Help users track progress
 4. **Reference module config** - Consistent behavior
@@ -318,7 +318,7 @@ menu:
 ```yaml
 menu:
   - trigger: start
-    workflow: '{project-root}/{bmad_folder}/{module}/workflows/init/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/{module}/workflows/init/workflow.yaml'
     description: 'Start new project (BEGIN HERE)'
 ```
 
@@ -327,7 +327,7 @@ menu:
 ```yaml
 menu:
   - trigger: status
-    workflow: '{project-root}/{bmad_folder}/{module}/workflows/status/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/{module}/workflows/status/workflow.yaml'
     description: 'Check workflow progress'
 ```
 
@@ -336,27 +336,27 @@ menu:
 ```yaml
 menu:
   - trigger: party
-    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    workflow: '{project-root}/{*bmad_folder*}/core/workflows/party-mode/workflow.yaml'
     description: 'Multi-agent discussion'
 ```
 
 ## Module Agent vs Simple/Expert
 
-| Aspect        | Module Agent                     | Simple/Expert Agent             |
-| ------------- | -------------------------------- | ------------------------------- |
-| Location      | `{bmad_folder}/{module}/agents/` | `{bmad_folder}/custom/agents/`  |
-| Persona       | Fixed, professional              | Customizable via install_config |
-| Handlebars    | No templating                    | Yes, extensive                  |
-| Menu actions  | Workflows, tasks, templates      | Prompts, inline actions         |
-| Configuration | Module config.yaml               | Core config or none             |
-| Purpose       | Professional tooling             | Personal utilities              |
+| Aspect        | Module Agent                       | Simple/Expert Agent              |
+| ------------- | ---------------------------------- | -------------------------------- |
+| Location      | `{*bmad_folder*}/{module}/agents/` | `{*bmad_folder*}/custom/agents/` |
+| Persona       | Fixed, professional                | Customizable via install_config  |
+| Handlebars    | No templating                      | Yes, extensive                   |
+| Menu actions  | Workflows, tasks, templates        | Prompts, inline actions          |
+| Configuration | Module config.yaml                 | Core config or none              |
+| Purpose       | Professional tooling               | Personal utilities               |
 
 ## Validation Checklist
 
 - [ ] Valid YAML syntax
 - [ ] Metadata includes `module: "{module-code}"`
-- [ ] id uses `{bmad_folder}/{module}/agents/{name}.md`
-- [ ] All workflow paths use `{project-root}/{bmad_folder}/` prefix
+- [ ] id uses `{*bmad_folder*}/{module}/agents/{name}.md`
+- [ ] All workflow paths use `{project-root}/{*bmad_folder*}/` prefix
 - [ ] No hardcoded paths
 - [ ] No duplicate triggers
 - [ ] Each menu item has description

package/src/modules/bmb/docs/agents/simple-agent-architecture.md

@@ -217,9 +217,13 @@ Features demonstrated:
 # Copy to your project
 cp /path/to/commit-poet.agent.yaml .bmad/custom/agents/
 
-# Install with personalization
-bmad agent-install
-# or: npx bmad-method agent-install
+# Create custom.yaml and install
+echo "code: my-agent
+name: My Agent
+default_selected: true" > custom.yaml
+
+npx bmad-method install
+# or: bmad install
 ```
 
 The installer:

package/src/modules/bmb/docs/workflows/architecture.md

@@ -69,7 +69,7 @@ workflow-folder/
 Standard variables in step files:
 
 ```yaml
-workflow_path: '{project-root}/{bmad_folder}/bmb/reference/workflows/[workflow-name]'
+workflow_path: '{project-root}/{*bmad_folder*}/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'

package/src/modules/bmb/docs/workflows/templates/step-01-init-continuable-template.md

@@ -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_folder*}/[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.