bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/core/tasks/adv-elicit.md

@@ -0,0 +1,109 @@
+<!-- BMAD-CORE™ Advanced Elicitation Task v2.0 (LLM-Native) -->
+
+# Advanced Elicitation v2.0 (LLM-Native)
+
+```xml
+<task id="bmad/core/tasks/adv-elicit.md" name="Advanced Elicitation">
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each &lt;action&gt; within &lt;step&gt; is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+  </llm>
+
+  <integration description="When called from workflow">
+    <desc>When called during template workflow processing:</desc>
+    <i>1. Receive the current section content that was just generated</i>
+    <i>2. Apply elicitation methods iteratively to enhance that specific content</i>
+    <i>3. Return the enhanced version back when user selects 'x' to proceed and return back</i>
+    <i>4. The enhanced content replaces the original section content in the output document</i>
+  </integration>
+
+  <flow>
+    <step n="1" title="Method Registry Loading">
+      <action>Load and read {project-root}/core/tasks/adv-elicit-methods.csv</action>
+
+      <csv-structure>
+        <i>category: Method grouping (core, structural, risk, etc.)</i>
+        <i>method_name: Display name for the method</i>
+        <i>description: Rich explanation of what the method does, when to use it, and why it's valuable</i>
+        <i>output_pattern: Flexible flow guide using → arrows (e.g., "analysis → insights → action")</i>
+      </csv-structure>
+
+      <context-analysis>
+        <i>Use conversation history</i>
+        <i>Analyze: content type, complexity, stakeholder needs, risk level, and creative potential</i>
+      </context-analysis>
+
+      <smart-selection>
+        <i>1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential</i>
+        <i>2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV</i>
+        <i>3. Select 5 methods: Choose methods that best match the context based on their descriptions</i>
+        <i>4. Balance approach: Include mix of foundational and specialized techniques as appropriate</i>
+      </smart-selection>
+    </step>
+
+    <step n="2" title="Present Options &amp; Handle Responses">
+
+      <format>
+        **Advanced Elicitation Options**
+        Choose a number (1-5), r to shuffle, or x to proceed:
+
+        1. [Method Name]
+        2. [Method Name]
+        3. [Method Name]
+        4. [Method Name]
+        5. [Method Name]
+        r. Reshuffle the list with 5 new options
+        x. Proceed / No Further Actions
+      </format>
+
+      <response-handling>
+        <case n="1-5">
+          <i>Execute the selected method using its description from the CSV</i>
+          <i>Adapt the method's complexity and output format based on the current context</i>
+          <i>Apply the method creatively to the current section content being enhanced</i>
+          <i>Display the enhanced version showing what the method revealed or improved</i>
+          <i>CRITICAL: Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response.</i>
+          <i>CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to follow the instructions given by the user.</i>
+          <i>CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations</i>
+        </case>
+        <case n="r">
+          <i>Select 5 different methods from adv-elicit-methods.csv, present new list with same prompt format</i>
+        </case>
+        <case n="x">
+          <i>Complete elicitation and proceed</i>
+          <i>Return the fully enhanced content back to create-doc.md</i>
+          <i>The enhanced content becomes the final version for that section</i>
+          <i>Signal completion back to create-doc.md to continue with next section</i>
+        </case>
+        <case n="direct-feedback">
+          <i>Apply changes to current section content and re-present choices</i>
+        </case>
+        <case n="multiple-numbers">
+          <i>Execute methods in sequence on the content, then re-offer choices</i>
+        </case>
+      </response-handling>
+    </step>
+
+    <step n="3" title="Execution Guidelines">
+      <i>Method execution: Use the description from CSV to understand and apply each method</i>
+      <i>Output pattern: Use the pattern as a flexible guide (e.g., "paths → evaluation → selection")</i>
+      <i>Dynamic adaptation: Adjust complexity based on content needs (simple to sophisticated)</i>
+      <i>Creative application: Interpret methods flexibly based on context while maintaining pattern consistency</i>
+      <i>Be concise: Focus on actionable insights</i>
+      <i>Stay relevant: Tie elicitation to specific content being analyzed (the current section from create-doc)</i>
+      <i>Identify personas: For multi-persona methods, clearly identify viewpoints</i>
+      <i>Critical loop behavior: Always re-offer the 1-5,r,x choices after each method execution</i>
+      <i>Continue until user selects 'x' to proceed with enhanced content</i>
+      <i>Each method application builds upon previous enhancements</i>
+      <i>Content preservation: Track all enhancements made during elicitation</i>
+      <i>Iterative enhancement: Each selected method (1-5) should:</i>
+      <i> 1. Apply to the current enhanced version of the content</i>
+      <i> 2. Show the improvements made</i>
+      <i> 3. Return to the prompt for additional elicitations or completion</i>
+    </step>
+  </flow>
+</task>
+```

package/src/core/tasks/index-docs.md

@@ -0,0 +1,69 @@
+<!-- BMAD-CORE™ Index Documentation Task -->
+
+# Index Docs v1.1
+
+```xml
+<task id="bmad/core/tasks/index-docs" name="Index Docs" webskip="true">
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each &lt;action&gt; within &lt;step&gt; is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+  </llm>
+
+  <flow>
+    <step n="1" title="Scan Directory">
+      <i>List all files and subdirectories in the target location</i>
+    </step>
+
+    <step n="2" title="Group Content">
+      <i>Organize files by type, purpose, or subdirectory</i>
+    </step>
+
+    <step n="3" title="Generate Descriptions">
+      <i>Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename</i>
+    </step>
+
+    <step n="4" title="Create/Update Index">
+      <i>Write or update index.md with organized file listings</i>
+    </step>
+  </flow>
+
+  <output-format>
+    <example>
+      # Directory Index
+
+      ## Files
+
+      - **[filename.ext](./filename.ext)** - Brief description
+      - **[another-file.ext](./another-file.ext)** - Brief description
+
+      ## Subdirectories
+
+      ### subfolder/
+
+      - **[file1.ext](./subfolder/file1.ext)** - Brief description
+      - **[file2.ext](./subfolder/file2.ext)** - Brief description
+
+      ### another-folder/
+
+      - **[file3.ext](./another-folder/file3.ext)** - Brief description
+    </example>
+  </output-format>
+
+  <halt-conditions critical="true">
+    <i>HALT if target directory does not exist or is inaccessible</i>
+    <i>HALT if user does not have write permissions to create index.md</i>
+  </halt-conditions>
+
+  <validation>
+    <i>Use relative paths starting with ./</i>
+    <i>Group similar files together</i>
+    <i>Read file contents to generate accurate descriptions - don't guess from filenames</i>
+    <i>Keep descriptions concise but informative (3-10 words)</i>
+    <i>Sort alphabetically within groups</i>
+    <i>Skip hidden files (starting with .) unless specified</i>
+  </validation>
+</task>
+```

package/src/core/tasks/shard-doc.md

@@ -0,0 +1,57 @@
+<!-- BMAD-CORE™ Document Sharding Task -->
+
+# Shard Doc v1.1
+
+```xml
+<task id="bmad/core/tasks/shard-doc.md" name="Shard Doc">
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each &lt;action&gt; within &lt;step&gt; is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+  </llm>
+
+  <flow>
+    <step n="1" title="Check for Tool">
+      <i>First check if md-tree command is available</i>
+    </step>
+
+    <step n="2" title="Install if Needed">
+      <i>If not available, ask user permission to install: npm install -g @kayvan/markdown-tree-parser</i>
+    </step>
+
+    <step n="3" title="Shard Document">
+      <i>Use the explode command to split the document</i>
+    </step>
+  </flow>
+
+  <usage>
+    <commands>
+      # Install the tool (if needed)
+      npm install -g @kayvan/markdown-tree-parser
+
+      # Shard a document
+      md-tree explode [source-document] [destination-folder]
+
+      # Examples
+      md-tree explode docs/prd.md docs/prd
+      md-tree explode docs/architecture.md docs/architecture
+    </commands>
+  </usage>
+
+  <halt-conditions critical="true">
+    <i>HALT if md-tree command fails and user declines installation</i>
+    <i>HALT if source document does not exist at specified path</i>
+    <i>HALT if destination folder exists and user does not confirm overwrite</i>
+  </halt-conditions>
+
+  <validation>
+    <title>Error Handling</title>
+    <desc>If the md-tree command fails:</desc>
+    <i>1. Check if the tool is installed globally</i>
+    <i>2. Ask user permission to install it</i>
+    <i>3. Retry the operation after installation</i>
+  </validation>
+</task>
+```

package/src/core/tasks/validate-workflow.md

@@ -0,0 +1,92 @@
+# Validate Workflow
+
+```xml
+<task id="bmad/core/tasks/validate-workflow.md" name="Validate Workflow Output">
+  <objective>Run a checklist against a document with thorough analysis and produce a validation report</objective>
+
+  <inputs>
+    <input name="workflow" desc="Workflow path containing checklist.md" />
+    <input name="checklist" desc="Checklist to validate against (defaults to workflow's checklist.md)" />
+    <input name="document" desc="Document to validate (ask user if not specified)" />
+  </inputs>
+
+  <flow>
+    <step n="1" title="Setup">
+      <action>If checklist not provided, load checklist.md from workflow location</action>
+      <action>If document not provided, ask user: "Which document should I validate?"</action>
+      <action>Load both the checklist and document</action>
+    </step>
+
+    <step n="2" title="Validate" critical="true">
+      <mandate>For EVERY checklist item, WITHOUT SKIPPING ANY:</mandate>
+
+      <for-each-item>
+        <action>Read requirement carefully</action>
+        <action>Search document for evidence along with any ancillary loaded documents or artifacts (quotes with line numbers)</action>
+        <action>Analyze deeply - look for explicit AND implied coverage</action>
+
+        <mark-as>
+          ✓ PASS - Requirement fully met (provide evidence)
+          ⚠ PARTIAL - Some coverage but incomplete (explain gaps)
+          ✗ FAIL - Not met or severely deficient (explain why)
+          ➖ N/A - Not applicable (explain reason)
+        </mark-as>
+      </for-each-item>
+
+      <critical>DO NOT SKIP ANY SECTIONS OR ITEMS</critical>
+    </step>
+
+    <step n="3" title="Generate Report">
+      <action>Create validation-report-{timestamp}.md in document's folder</action>
+
+      <report-format>
+        # Validation Report
+
+        **Document:** {document-path}
+        **Checklist:** {checklist-path}
+        **Date:** {timestamp}
+
+        ## Summary
+        - Overall: X/Y passed (Z%)
+        - Critical Issues: {count}
+
+        ## Section Results
+
+        ### {Section Name}
+        Pass Rate: X/Y (Z%)
+
+        {For each item:}
+        [MARK] {Item description}
+        Evidence: {Quote with line# or explanation}
+        {If FAIL/PARTIAL: Impact: {why this matters}}
+
+        ## Failed Items
+        {All ✗ items with recommendations}
+
+        ## Partial Items
+        {All ⚠ items with what's missing}
+
+        ## Recommendations
+        1. Must Fix: {critical failures}
+        2. Should Improve: {important gaps}
+        3. Consider: {minor improvements}
+      </report-format>
+    </step>
+
+    <step n="4" title="Summary for User">
+      <action>Present section-by-section summary</action>
+      <action>Highlight all critical issues</action>
+      <action>Provide path to saved report</action>
+      <action>HALT - do not continue unless user asks</action>
+    </step>
+  </flow>
+
+  <critical-rules>
+    <rule>NEVER skip sections - validate EVERYTHING</rule>
+    <rule>ALWAYS provide evidence (quotes + line numbers) for marks</rule>
+    <rule>Think deeply about each requirement - don't rush</rule>
+    <rule>Save report to document's folder automatically</rule>
+    <rule>HALT after presenting summary - wait for user</rule>
+  </critical-rules>
+</task>
+```

package/src/core/tasks/workflow.md

@@ -0,0 +1,141 @@
+<!-- BMAD Method v6 Workflow Execution Task (Simplified) -->
+
+# Workflow
+
+```xml
+<task id="bmad/core/tasks/workflow.md" name="Execute Workflow">
+  <objective>Execute given workflow by loading its configuration, following instructions, and producing output</objective>
+
+  <llm critical="true">
+    <mandate>Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files</mandate>
+    <mandate>Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown</mandate>
+    <mandate>Execute ALL steps in instructions IN EXACT ORDER</mandate>
+    <mandate>Save to template output file after EVERY "template-output" tag</mandate>
+    <mandate>NEVER delegate a step - YOU are responsible for every steps execution</mandate>
+  </llm>
+
+  <WORKFLOW-RULES critical="true">
+    <rule n="1">Steps execute in exact numerical order (1, 2, 3...)</rule>
+    <rule n="2">Optional steps: Ask user unless #yolo mode active</rule>
+    <rule n="3">Template-output tags: Save content → Show user → Get approval before continuing</rule>
+    <rule n="4">Elicit tags: Execute immediately unless #yolo mode (which skips ALL elicitation)</rule>
+    <rule n="5">User must approve each major section before continuing UNLESS #yolo mode active</rule>
+  </WORKFLOW-RULES>
+
+  <flow>
+    <step n="1" title="Load and Initialize Workflow">
+      <substep n="1a" title="Load Configuration and Resolve Variables">
+        <action>Read workflow.yaml from provided path</action>
+        <mandate>Load config_source (REQUIRED for all modules)</mandate>
+        <phase n="1">Load external config from config_source path</phase>
+        <phase n="2">Resolve all {config_source}: references with values from config</phase>
+        <phase n="3">Resolve system variables (date:system-generated) and paths ({project-root}, {installed_path})</phase>
+        <phase n="4">Ask user for input of any variables that are still unknown</phase>
+      </substep>
+
+      <substep n="1b" title="Load Required Components">
+        <mandate>Instructions: Read COMPLETE file from path OR embedded list (REQUIRED)</mandate>
+        <check>If template path → Read COMPLETE template file</check>
+        <check>If validation path → Note path for later loading when needed</check>
+        <check>If template: false → Mark as action-workflow (else template-workflow)</check>
+        <note>Data files (csv, json) → Store paths only, load on-demand when instructions reference them</note>
+      </substep>
+
+      <substep n="1c" title="Initialize Output" if="template-workflow">
+        <action>Resolve default_output_file path with all variables and {{date}}</action>
+        <action>Create output directory if doesn't exist</action>
+        <action>If template-workflow → Write template to output file with placeholders</action>
+        <action>If action-workflow → Skip file creation</action>
+      </substep>
+    </step>
+
+    <step n="2" title="Process Each Instruction Step">
+      <iterate>For each step in instructions:</iterate>
+
+      <substep n="2a" title="Handle Step Attributes">
+        <check>If optional="true" and NOT #yolo → Ask user to include</check>
+        <check>If if="condition" → Evaluate condition</check>
+        <check>If for-each="item" → Repeat step for each item</check>
+        <check>If repeat="n" → Repeat step n times</check>
+      </substep>
+
+      <substep n="2b" title="Execute Step Content">
+        <action>Process step instructions (markdown or XML tags)</action>
+        <action>Replace {{variables}} with values (ask user if unknown)</action>
+        <execute-tags>
+          <tag><action> → Perform the action</tag>
+          <tag><check> → Evaluate condition</tag>
+          <tag><ask> → Prompt user and WAIT for response</tag>
+          <tag><invoke-workflow> → Execute another workflow with given inputs</tag>
+          <tag><invoke-task> → Execute specified task</tag>
+          <tag><goto step="x"> → Jump to specified step</tag>
+        </execute-tags>
+      </substep>
+
+      <substep n="2c" title="Handle Special Output Tags">
+        <if tag="template-output">
+          <mandate>Generate content for this section</mandate>
+          <mandate>Save to file (Write first time, Edit subsequent)</mandate>
+          <action>Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━</action>
+          <action>Display generated content</action>
+          <ask>Continue [c] or Edit [e]? WAIT for response</ask>
+        </if>
+
+        <if tag="elicit-required">
+          <mandate critical="true">YOU MUST READ the file at {project-root}/bmad/core/tasks/adv-elicit.md using Read tool BEFORE presenting any elicitation menu</mandate>
+          <action>Load and run task {project-root}/bmad/core/tasks/adv-elicit.md with current context</action>
+          <action>Show elicitation menu 5 relevant options (list 1-5 options, Continue [c] or Reshuffle [r])</action>
+          <mandate>HALT and WAIT for user selection</mandate>
+        </if>
+      </substep>
+
+      <substep n="2d" title="Step Completion">
+        <check>If no special tags and NOT #yolo:</check>
+        <ask>Continue to next step? (y/n/edit)</ask>
+      </substep>
+    </step>
+
+    <step n="3" title="Completion">
+      <check>If checklist exists → Run validation</check>
+      <check>If template: false → Confirm actions completed</check>
+      <check>Else → Confirm document saved to output path</check>
+      <action>Report workflow completion</action>
+    </step>
+  </flow>
+
+  <execution-modes>
+    <mode name="normal">Full user interaction at all decision points</mode>
+    <mode name="#yolo">Skip optional sections, skip all elicitation, minimize prompts</mode>
+  </execution-modes>
+
+  <supported-tags desc="Instructions can use these tags">
+    <structural>
+      <tag>step n="X" goal="..." - Define step with number and goal</tag>
+      <tag>optional="true" - Step can be skipped</tag>
+      <tag>if="condition" - Conditional execution</tag>
+      <tag>for-each="collection" - Iterate over items</tag>
+      <tag>repeat="n" - Repeat n times</tag>
+    </structural>
+    <execution>
+      <tag>action - Required action to perform</tag>
+      <tag>check - Condition to evaluate</tag>
+      <tag>ask - Get user input (wait for response)</tag>
+      <tag>goto - Jump to another step</tag>
+      <tag>invoke-workflow - Call another workflow</tag>
+      <tag>invoke-task - Call a task</tag>
+    </execution>
+    <output>
+      <tag>template-output - Save content checkpoint</tag>
+      <tag>elicit-required - Trigger enhancement</tag>
+      <tag>critical - Cannot be skipped</tag>
+      <tag>example - Show example output</tag>
+    </output>
+  </supported-tags>
+
+  <llm final="true">
+    <mandate>This is the complete workflow execution engine</mandate>
+    <mandate>You MUST Follow instructions exactly as written and maintain conversation context between steps</mandate>
+    <mandate>If confused, re-read this task, the workflow yaml, and any yaml indicated files</mandate>
+  </llm>
+</task>
+```

package/src/core/workflows/bmad-init/instructions.md

@@ -0,0 +1,79 @@
+# BMAD Init - System Initialization Instructions
+
+<workflow>
+
+<step n="1" goal="Welcome and Status Check">
+  <action>Display welcome banner with BMAD branding</action>
+  <action>Check for BMAD installation at {project-root}/bmad</action>
+  <check>If installation found:</check>
+    <action>Display current version from {project-root}/bmad/_cfg/manifest.yaml</action>
+    <action>Show installation date and status</action>
+  <check>If not found:</check>
+    <action>Display warning that BMAD is not installed</action>
+    <action>Suggest running the installer first</action>
+    <action>Exit workflow</action>
+  <action>Display formatted status summary:
+    ╔════════════════════════════════════════╗
+    ║         BMAD INITIALIZATION            ║
+    ╚════════════════════════════════════════╝
+
+    Status: [Installed/Not Found]
+    Location: {project-root}/bmad
+    Version: [from manifest]
+    Installed: [date from manifest]
+
+  </action>
+</step>
+
+<step n="2" goal="Present Initialization Options">
+  <action>Display available initialization and maintenance tasks</action>
+  <ask>Select an initialization task:
+
+    1. Customize Installed Agents and Agent Party (Coming Soon)
+       - Assign new names and personas to agents
+       - Create runtime agent variants
+       - NOTE: This can all be done manually, but doing it through here will be easier and also update the party-mode manifest
+
+    2. Verify Installation (Coming Soon)
+       - Check all files are properly installed
+       - Validate configurations
+
+    3. Exit
+
+    Please select an option (1-3).
+
+  </ask>
+</step>
+
+<step n="3" goal="Process User Selection">
+  <check>If user selected "1":</check>
+    <action>Display message: ⚠️ Installed Agent Auto Customization is coming soon.</action>
+    <<action>Return to step 2</action>
+
+<check>If user selected "2":</check>
+<action>Display message: ⚠️ Installation verification is coming soon.</action>
+<action>Return to step 2</action>
+
+<check>If user selected "3":</check>
+<action>Display message: Exiting BMAD Init. Thank you!</action>
+<goto step="5">Exit workflow</goto>
+</step>
+
+<step n="4" goal="Post-Task Options">
+  <action>Display completion status of the executed task</action>
+  <ask>Task completed successfully!
+
+Would you like to perform another initialization task? (y/n):</ask>
+<check>If user responds "y":</check>
+<goto step="2">Return to menu</goto>
+<check>If user responds "n":</check>
+<goto step="5">Exit workflow</goto>
+</step>
+
+<step n="5" goal="Exit Workflow">
+  <action>Display farewell message</action>
+  <action>Suggest user start a new context or clear context if needed</action>
+  <action>Exit workflow</action>
+</step>
+
+</workflow>

package/src/core/workflows/bmad-init/workflow.yaml

@@ -0,0 +1,24 @@
+# BMAD Init - System Initialization Workflow
+name: "bmad-init"
+description: "BMAD system initialization and maintenance workflow for agent manifest generation and system configuration"
+author: "BMad"
+
+# Critical variables
+config_source: "{project-root}/bmad/_cfg/manifest.yaml"
+date: system-generated
+
+# This is an action workflow - no template output
+template: false
+instructions: "{project-root}/src/core/workflows/bmad-init/instructions.md"
+
+# Sub-components
+party_update_instructions: "{project-root}/src/core/workflows/bmad-init/party-update/instructions.md"
+
+# No specific output file - this workflow performs various system actions
+default_output_file: null
+
+# Required tools for execution
+required_tools:
+  - file_operations
+  - llm_analysis
+  - xml_generation