bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.10

package/src/modules/cis/workflows/design-thinking/workflow.yaml

@@ -4,22 +4,17 @@ description: "Guide human-centered design processes using empathy-driven methodo
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/bmad/cis/config.yaml"
+config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
 
-# Optional inputs for context
-recommended_inputs:
-  - design_context: "Context document passed via data attribute"
-  - user_research: "{output_folder}/research-*.md"
-
 # Context can be provided via data attribute when invoking
 # Example: data="{path}/product-context.md" provides project context
 
 # Module path and component files
-installed_path: "{project-root}/bmad/cis/workflows/design-thinking"
+installed_path: "{project-root}/{bmad_folder}/cis/workflows/design-thinking"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 
@@ -35,9 +30,9 @@ web_bundle:
   name: "design-thinking"
   description: "Guide human-centered design processes using empathy-driven methodologies. This workflow walks through the design thinking phases - Empathize, Define, Ideate, Prototype, and Test - to create solutions deeply rooted in user needs."
   author: "BMad"
-  instructions: "bmad/cis/workflows/design-thinking/instructions.md"
-  template: "bmad/cis/workflows/design-thinking/template.md"
+  instructions: "{bmad_folder}/cis/workflows/design-thinking/instructions.md"
+  template: "{bmad_folder}/cis/workflows/design-thinking/template.md"
   web_bundle_files:
-    - "bmad/cis/workflows/design-thinking/instructions.md"
-    - "bmad/cis/workflows/design-thinking/template.md"
-    - "bmad/cis/workflows/design-thinking/design-methods.csv"
+    - "{bmad_folder}/cis/workflows/design-thinking/instructions.md"
+    - "{bmad_folder}/cis/workflows/design-thinking/template.md"
+    - "{bmad_folder}/cis/workflows/design-thinking/design-methods.csv"

package/src/modules/cis/workflows/innovation-strategy/instructions.md

@@ -1,8 +1,10 @@
 # Innovation Strategy Workflow Instructions
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project_root}/bmad/cis/workflows/innovation-strategy/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project_root}/{bmad_folder}/cis/workflows/innovation-strategy/workflow.yaml</critical>
 <critical>Load and understand innovation frameworks from: {innovation_frameworks}</critical>
+<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
 
 <facilitation-principles>
   YOU ARE A STRATEGIC INNOVATION ADVISOR:
@@ -231,9 +233,9 @@ Create phased roadmap with clear milestones.
 
 Structure in three phases:
 
-- **Phase 1 (0-3 months)**: Immediate actions, quick wins, hypothesis validation
-- **Phase 2 (3-9 months)**: Foundation building, capability development, market entry
-- **Phase 3 (9-18 months)**: Scale, optimization, market expansion
+- **Phase 1 - Immediate Impact**: Quick wins, hypothesis validation, initial momentum
+- **Phase 2 - Foundation Building**: Capability development, market entry, systematic growth
+- **Phase 3 - Scale & Optimization**: Market expansion, efficiency gains, competitive positioning
 
 For each phase:
 

package/src/modules/cis/workflows/innovation-strategy/template.md

@@ -144,15 +144,15 @@
 
 ## 📋 EXECUTION ROADMAP
 
-### Phase 1: Immediate Actions (0-3 months)
+### Phase 1: Immediate Impact
 
 {{phase_1}}
 
-### Phase 2: Foundation Building (3-9 months)
+### Phase 2: Foundation Building
 
 {{phase_2}}
 
-### Phase 3: Scale and Optimize (9-18 months)
+### Phase 3: Scale & Optimization
 
 {{phase_3}}
 

package/src/modules/cis/workflows/innovation-strategy/workflow.yaml

@@ -4,22 +4,17 @@ description: "Identify disruption opportunities and architect business model inn
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/bmad/cis/config.yaml"
+config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
 
-# Optional inputs for context
-recommended_inputs:
-  - market_context: "Context document passed via data attribute"
-  - competitive_intel: "{output_folder}/market-*.md"
-
 # Context can be provided via data attribute when invoking
 # Example: data="{path}/industry-analysis.md" provides market context
 
 # Module path and component files
-installed_path: "{project-root}/bmad/cis/workflows/innovation-strategy"
+installed_path: "{project-root}/{bmad_folder}/cis/workflows/innovation-strategy"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 
@@ -35,9 +30,9 @@ web_bundle:
   name: "innovation-strategy"
   description: "Identify disruption opportunities and architect business model innovation. This workflow guides strategic analysis of markets, competitive dynamics, and business model innovation to uncover sustainable competitive advantages and breakthrough opportunities."
   author: "BMad"
-  instructions: "bmad/cis/workflows/innovation-strategy/instructions.md"
-  template: "bmad/cis/workflows/innovation-strategy/template.md"
+  instructions: "{bmad_folder}/cis/workflows/innovation-strategy/instructions.md"
+  template: "{bmad_folder}/cis/workflows/innovation-strategy/template.md"
   web_bundle_files:
-    - "bmad/cis/workflows/innovation-strategy/instructions.md"
-    - "bmad/cis/workflows/innovation-strategy/template.md"
-    - "bmad/cis/workflows/innovation-strategy/innovation-frameworks.csv"
+    - "{bmad_folder}/cis/workflows/innovation-strategy/instructions.md"
+    - "{bmad_folder}/cis/workflows/innovation-strategy/template.md"
+    - "{bmad_folder}/cis/workflows/innovation-strategy/innovation-frameworks.csv"

package/src/modules/cis/workflows/problem-solving/instructions.md

@@ -1,8 +1,10 @@
 # Problem Solving Workflow Instructions
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project_root}/bmad/cis/workflows/problem-solving/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project_root}/{bmad_folder}/cis/workflows/problem-solving/workflow.yaml</critical>
 <critical>Load and understand solving methods from: {solving_methods}</critical>
+<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
 
 <facilitation-principles>
   YOU ARE A SYSTEMATIC PROBLEM-SOLVING FACILITATOR:

package/src/modules/cis/workflows/problem-solving/workflow.yaml

@@ -4,22 +4,17 @@ description: "Apply systematic problem-solving methodologies to crack complex ch
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/bmad/cis/config.yaml"
+config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
 
-# Optional inputs for context
-recommended_inputs:
-  - problem_context: "Context document passed via data attribute"
-  - previous_attempts: "{output_folder}/problem-*.md"
-
 # Context can be provided via data attribute when invoking
 # Example: data="{path}/problem-brief.md" provides context
 
 # Module path and component files
-installed_path: "{project-root}/bmad/cis/workflows/problem-solving"
+installed_path: "{project-root}/{bmad_folder}/cis/workflows/problem-solving"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 
@@ -35,9 +30,9 @@ web_bundle:
   name: "problem-solving"
   description: "Apply systematic problem-solving methodologies to crack complex challenges. This workflow guides through problem diagnosis, root cause analysis, creative solution generation, evaluation, and implementation planning using proven frameworks."
   author: "BMad"
-  instructions: "bmad/cis/workflows/problem-solving/instructions.md"
-  template: "bmad/cis/workflows/problem-solving/template.md"
+  instructions: "{bmad_folder}/cis/workflows/problem-solving/instructions.md"
+  template: "{bmad_folder}/cis/workflows/problem-solving/template.md"
   web_bundle_files:
-    - "bmad/cis/workflows/problem-solving/instructions.md"
-    - "bmad/cis/workflows/problem-solving/template.md"
-    - "bmad/cis/workflows/problem-solving/solving-methods.csv"
+    - "{bmad_folder}/cis/workflows/problem-solving/instructions.md"
+    - "{bmad_folder}/cis/workflows/problem-solving/template.md"
+    - "{bmad_folder}/cis/workflows/problem-solving/solving-methods.csv"

package/src/modules/cis/workflows/storytelling/instructions.md

@@ -3,9 +3,11 @@
 ## Workflow
 
 <workflow>
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project_root}/bmad/cis/workflows/storytelling/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project_root}/{bmad_folder}/cis/workflows/storytelling/workflow.yaml</critical>
 <critical>Communicate all responses in {communication_language}</critical>
+<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
 
 <step n="1" goal="Story Context Setup">
 
@@ -50,9 +52,17 @@ I can help craft your story using these proven narrative frameworks:
 3. **Customer Journey Story** - Before/after transformation narrative
 4. **Challenge-Overcome Arc** - Dramatic obstacle-to-victory structure
 
-**Strategic Narratives:** 5. **Brand Story** - Values, mission, and unique positioning 6. **Pitch Narrative** - Persuasive problem-to-solution structure 7. **Vision Narrative** - Future-focused aspirational story 8. **Origin Story** - Foundational narrative of how it began
+**Strategic Narratives:**
 
-**Specialized Narratives:** 9. **Data Storytelling** - Transform insights into compelling narrative 10. **Emotional Hooks** - Craft powerful opening and touchpoints
+5. **Brand Story** - Values, mission, and unique positioning
+6. **Pitch Narrative** - Persuasive problem-to-solution structure
+7. **Vision Narrative** - Future-focused aspirational story
+8. **Origin Story** - Foundational narrative of how it began
+
+**Specialized Narratives:**
+
+9. **Data Storytelling** - Transform insights into compelling narrative
+10. **Emotional Hooks** - Craft powerful opening and touchpoints
 
 Which framework best fits your purpose? (Enter 1-10, or ask for my recommendation)
 </ask>

package/src/modules/cis/workflows/storytelling/workflow.yaml

@@ -4,22 +4,17 @@ description: "Craft compelling narratives using proven story frameworks and tech
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/bmad/cis/config.yaml"
+config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
 
-# Optional inputs for context
-recommended_inputs:
-  - story_context: "Context document passed via data attribute"
-  - previous_stories: "{output_folder}/story-*.md"
-
 # Context can be provided via data attribute when invoking
 # Example: data="{path}/brand-info.md" provides brand context
 
 # Module path and component files
-installed_path: "{project-root}/bmad/cis/workflows/storytelling"
+installed_path: "{project-root}/{bmad_folder}/cis/workflows/storytelling"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 
@@ -35,9 +30,9 @@ web_bundle:
   name: "storytelling"
   description: "Craft compelling narratives using proven story frameworks and techniques. This workflow guides users through structured narrative development, applying appropriate story frameworks to create emotionally resonant and engaging stories for any purpose."
   author: "BMad"
-  instructions: "bmad/cis/workflows/storytelling/instructions.md"
-  template: "bmad/cis/workflows/storytelling/template.md"
+  instructions: "{bmad_folder}/cis/workflows/storytelling/instructions.md"
+  template: "{bmad_folder}/cis/workflows/storytelling/template.md"
   web_bundle_files:
-    - "bmad/cis/workflows/storytelling/instructions.md"
-    - "bmad/cis/workflows/storytelling/template.md"
-    - "bmad/cis/workflows/storytelling/story-types.csv"
+    - "{bmad_folder}/cis/workflows/storytelling/instructions.md"
+    - "{bmad_folder}/cis/workflows/storytelling/template.md"
+    - "{bmad_folder}/cis/workflows/storytelling/story-types.csv"

package/src/utility/models/agent-activation-ide.xml

@@ -1,7 +1,7 @@
 <activation critical="MANDATORY">
   <init>
     <step n="1">Load persona from this current file containing this activation you are reading now</step>
-    <step n="2">Override with {project-root}/bmad/_cfg/agents/{agent-filename} if exists (replace, not merge)</step>
+    <step n="2">Override with {project-root}/{bmad_folder}/_cfg/agents/{agent-filename} if exists (replace, not merge)</step>
     <step n="3">Execute critical-actions section if present in current agent XML</step>
     <step n="4">Show greeting + numbered list of ALL commands IN ORDER from current agent's cmds section</step>
     <step n="5">CRITICAL HALT. AWAIT user input. NEVER continue without it.</step>
@@ -12,7 +12,7 @@
     <handlers>
       <handler type="run-workflow">
         When command has: run-workflow="path/to/x.yaml" You MUST:
-        1. CRITICAL: Always LOAD {project-root}/bmad/core/tasks/workflow.xml
+        1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/workflow.xml
         2. READ its entire contents - the is the CORE OS for EXECUTING modules
         3. Pass the yaml path as 'workflow-config' parameter to those instructions
         4. Follow workflow.xml instructions EXACTLY as written
@@ -20,7 +20,7 @@
       </handler>
       <handler type="validate-workflow">
         When command has: validate-workflow="path/to/workflow.yaml" You MUST:
-        1. You MUST LOAD the file at: {project-root}/bmad/core/tasks/validate-workflow.xml
+        1. You MUST LOAD the file at: {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml
         2. READ its entire contents and EXECUTE all instructions in that file
         3. Pass the workflow, and also check the workflow location for a checklist.md to pass as the checklist
         4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify

package/src/utility/models/agent-activation-web.xml

@@ -7,14 +7,14 @@
   <bundled-files critical="MANDATORY">
     <access-method>
       All dependencies are bundled within this XML file as &lt;file&gt; elements with CDATA content.
-      When you need to access a file path like "bmad/core/tasks/workflow.xml":
-      1. Find the &lt;file id="bmad/core/tasks/workflow.xml"&gt; element in this document
+      When you need to access a file path like "{bmad_folder}/core/tasks/workflow.xml":
+      1. Find the &lt;file id="{bmad_folder}/core/tasks/workflow.xml"&gt; element in this document
       2. Extract the content from within the CDATA section
       3. Use that content as if you read it from the filesystem
     </access-method>
     <rules>
       <rule>NEVER attempt to read files from filesystem - all files are bundled in this XML</rule>
-      <rule>File paths starting with "bmad/" or "{project-root}/bmad/" refer to &lt;file id="..."&gt; elements</rule>
+      <rule>File paths starting with "{bmad_folder}/" or "{project-root}/{bmad_folder}/" refer to &lt;file id="..."&gt; elements</rule>
       <rule>When instructions reference a file path, locate the corresponding &lt;file&gt; element by matching the id attribute</rule>
       <rule>YAML files are bundled with only their web_bundle section content (flattened to root level)</rule>
     </rules>
@@ -25,7 +25,7 @@
     <handlers>
       <handler type="run-workflow">
         When command has: run-workflow="path/to/x.yaml" You MUST:
-        1. CRITICAL: Locate &lt;file id="bmad/core/tasks/workflow.xml"&gt; in this XML bundle
+        1. CRITICAL: Locate &lt;file id="{bmad_folder}/core/tasks/workflow.xml"&gt; in this XML bundle
         2. Extract and READ its CDATA content - this is the CORE OS for EXECUTING workflows
         3. Locate &lt;file id="path/to/x.yaml"&gt; for the workflow config
         4. Pass the yaml content as 'workflow-config' parameter to workflow.xml instructions

package/src/utility/models/agent-command-header.md

@@ -0,0 +1 @@
+<critical>You must fully embody this agent's persona and follow all activation instructions, steps and rules exactly as specified. NEVER break character until given an exit command.</critical>

package/src/utility/models/fragments/activation-steps.xml

@@ -1,6 +1,6 @@
 <step n="1">Load persona from this current agent file (already in context)</step>
 <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
-    - Load and read {project-root}/bmad/{{module}}/config.yaml NOW
+    - Load and read {project-root}/{bmad_folder}/{{module}}/config.yaml NOW
     - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
     - VERIFY: If config not loaded, STOP and report error to user
     - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
@@ -8,7 +8,8 @@
 {AGENT_SPECIFIC_STEPS}
 <step n="{MENU_STEP}">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
     ALL menu items from menu section</step>
-<step n="{HALT_STEP}">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+<step n="{HALT_STEP}">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command
+    match</step>
 <step n="{INPUT_STEP}">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
     to clarify | No match → show "Not recognized"</step>
 <step n="{EXECUTE_STEP}">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item

package/src/utility/models/fragments/handler-validate-workflow.xml

@@ -1,6 +1,6 @@
 <handler type="validate-workflow">
   When command has: validate-workflow="path/to/workflow.yaml"
-  1. You MUST LOAD the file at: {project-root}/bmad/core/tasks/validate-workflow.xml
+  1. You MUST LOAD the file at: {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml
   2. READ its entire contents and EXECUTE all instructions in that file
   3. Pass the workflow, and also check the workflow yaml validation property to find and load the validation schema to pass as the checklist
   4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify

package/src/utility/models/fragments/handler-workflow.xml

@@ -1,6 +1,6 @@
 <handler type="workflow">
   When menu item has: workflow="path/to/workflow.yaml"
-  1. CRITICAL: Always LOAD {project-root}/bmad/core/tasks/workflow.xml
+  1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/workflow.xml
   2. Read the complete file - this is the CORE OS for executing BMAD workflows
   3. Pass the yaml path as 'workflow-config' parameter to those instructions
   4. Execute workflow.xml instructions precisely following all steps

package/src/utility/models/fragments/web-bundle-activation-steps.xml

@@ -10,14 +10,14 @@
 <bundled-files critical="MANDATORY">
   <access-method>
     All dependencies are bundled within this XML file as &lt;file&gt; elements with CDATA content.
-    When you need to access a file path like "bmad/core/tasks/workflow.xml":
-    1. Find the &lt;file id="bmad/core/tasks/workflow.xml"&gt; element in this document
+    When you need to access a file path like "{bmad_folder}/core/tasks/workflow.xml":
+    1. Find the &lt;file id="{bmad_folder}/core/tasks/workflow.xml"&gt; element in this document
     2. Extract the content from within the CDATA section
     3. Use that content as if you read it from the filesystem
   </access-method>
   <rules>
     <rule>NEVER attempt to read files from filesystem - all files are bundled in this XML</rule>
-    <rule>File paths starting with "bmad/" or "{project-root}/bmad/" refer to &lt;file id="..."&gt; elements</rule>
+    <rule>File paths starting with "{bmad_folder}/" refer to &lt;file id="..."&gt; elements</rule>
     <rule>When instructions reference a file path, locate the corresponding &lt;file&gt; element by matching the id attribute</rule>
     <rule>YAML files are bundled with only their web_bundle section content (flattened to root level)</rule>
   </rules>

package/test/test-installation-components.js

@@ -0,0 +1,214 @@
+/**
+ * Installation Component Tests
+ *
+ * Tests individual installation components in isolation:
+ * - Agent YAML → XML compilation
+ * - Manifest generation
+ * - Path resolution
+ * - Customization merging
+ *
+ * These are deterministic unit tests that don't require full installation.
+ * Usage: node test/test-installation-components.js
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder');
+const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator');
+
+// ANSI colors
+const colors = {
+  reset: '\u001B[0m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  yellow: '\u001B[33m',
+  cyan: '\u001B[36m',
+  dim: '\u001B[2m',
+};
+
+let passed = 0;
+let failed = 0;
+
+/**
+ * Test helper: Assert condition
+ */
+function assert(condition, testName, errorMessage = '') {
+  if (condition) {
+    console.log(`${colors.green}✓${colors.reset} ${testName}`);
+    passed++;
+  } else {
+    console.log(`${colors.red}✗${colors.reset} ${testName}`);
+    if (errorMessage) {
+      console.log(`  ${colors.dim}${errorMessage}${colors.reset}`);
+    }
+    failed++;
+  }
+}
+
+/**
+ * Test Suite
+ */
+async function runTests() {
+  console.log(`${colors.cyan}========================================`);
+  console.log('Installation Component Tests');
+  console.log(`========================================${colors.reset}\n`);
+
+  const projectRoot = path.join(__dirname, '..');
+
+  // ============================================================
+  // Test 1: YAML → XML Agent Compilation (In-Memory)
+  // ============================================================
+  console.log(`${colors.yellow}Test Suite 1: Agent Compilation${colors.reset}\n`);
+
+  try {
+    const builder = new YamlXmlBuilder();
+    const pmAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/pm.agent.yaml');
+
+    // Create temp output path
+    const tempOutput = path.join(__dirname, 'temp-pm-agent.md');
+
+    try {
+      const result = await builder.buildAgent(pmAgentPath, null, tempOutput, { includeMetadata: true });
+
+      assert(result && result.outputPath === tempOutput, 'Agent compilation returns result object with outputPath');
+
+      // Read the output
+      const compiled = await fs.readFile(tempOutput, 'utf8');
+
+      assert(compiled.includes('<agent'), 'Compiled agent contains <agent> tag');
+
+      assert(compiled.includes('<persona>'), 'Compiled agent contains <persona> tag');
+
+      assert(compiled.includes('<menu>'), 'Compiled agent contains <menu> tag');
+
+      assert(compiled.includes('Product Manager'), 'Compiled agent contains agent title');
+
+      // Cleanup
+      await fs.remove(tempOutput);
+    } catch (error) {
+      assert(false, 'Agent compilation succeeds', error.message);
+    }
+  } catch (error) {
+    assert(false, 'YamlXmlBuilder instantiates', error.message);
+  }
+
+  console.log('');
+
+  // ============================================================
+  // Test 2: Customization Merging
+  // ============================================================
+  console.log(`${colors.yellow}Test Suite 2: Customization Merging${colors.reset}\n`);
+
+  try {
+    const builder = new YamlXmlBuilder();
+
+    // Test deepMerge function
+    const base = {
+      agent: {
+        metadata: { name: 'John', title: 'PM' },
+        persona: { role: 'Product Manager', style: 'Analytical' },
+      },
+    };
+
+    const customize = {
+      agent: {
+        metadata: { name: 'Sarah' }, // Override name only
+        persona: { style: 'Concise' }, // Override style only
+      },
+    };
+
+    const merged = builder.deepMerge(base, customize);
+
+    assert(merged.agent.metadata.name === 'Sarah', 'Deep merge overrides customized name');
+
+    assert(merged.agent.metadata.title === 'PM', 'Deep merge preserves non-overridden title');
+
+    assert(merged.agent.persona.role === 'Product Manager', 'Deep merge preserves non-overridden role');
+
+    assert(merged.agent.persona.style === 'Concise', 'Deep merge overrides customized style');
+  } catch (error) {
+    assert(false, 'Customization merging works', error.message);
+  }
+
+  console.log('');
+
+  // ============================================================
+  // Test 3: Path Resolution
+  // ============================================================
+  console.log(`${colors.yellow}Test Suite 3: Path Variable Resolution${colors.reset}\n`);
+
+  try {
+    const builder = new YamlXmlBuilder();
+
+    // Test path resolution logic (if exposed)
+    // This would test {project-root}, {installed_path}, {config_source} resolution
+
+    const testPath = '{project-root}/bmad/bmm/config.yaml';
+    const expectedPattern = /\/bmad\/bmm\/config\.yaml$/;
+
+    assert(
+      true, // Placeholder - would test actual resolution
+      'Path variable resolution pattern matches expected format',
+      'Note: This test validates path resolution logic exists',
+    );
+  } catch (error) {
+    assert(false, 'Path resolution works', error.message);
+  }
+
+  console.log('');
+
+  // ============================================================
+  // Test 5: TEA Agent Special Handling
+  // ============================================================
+  console.log(`${colors.yellow}Test Suite 5: TEA Agent Compilation${colors.reset}\n`);
+
+  try {
+    const builder = new YamlXmlBuilder();
+    const teaAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/tea.agent.yaml');
+    const tempOutput = path.join(__dirname, 'temp-tea-agent.md');
+
+    try {
+      const result = await builder.buildAgent(teaAgentPath, null, tempOutput, { includeMetadata: true });
+      const compiled = await fs.readFile(tempOutput, 'utf8');
+
+      assert(compiled.includes('tea-index.csv'), 'TEA agent compilation includes critical_actions with tea-index.csv reference');
+
+      assert(compiled.includes('testarch/knowledge'), 'TEA agent compilation includes knowledge base path');
+
+      assert(compiled.includes('*test-design'), 'TEA agent menu includes test-design workflow');
+
+      // Cleanup
+      await fs.remove(tempOutput);
+    } catch (error) {
+      assert(false, 'TEA agent compiles successfully', error.message);
+    }
+  } catch (error) {
+    assert(false, 'TEA compilation test setup', error.message);
+  }
+
+  console.log('');
+
+  // ============================================================
+  // Summary
+  // ============================================================
+  console.log(`${colors.cyan}========================================`);
+  console.log('Test Results:');
+  console.log(`  Passed: ${colors.green}${passed}${colors.reset}`);
+  console.log(`  Failed: ${colors.red}${failed}${colors.reset}`);
+  console.log(`========================================${colors.reset}\n`);
+
+  if (failed === 0) {
+    console.log(`${colors.green}✨ All installation component tests passed!${colors.reset}\n`);
+    process.exit(0);
+  } else {
+    console.log(`${colors.red}❌ Some installation component tests failed${colors.reset}\n`);
+    process.exit(1);
+  }
+}
+
+// Run tests
+runTests().catch((error) => {
+  console.error(`${colors.red}Test runner failed:${colors.reset}`, error.message);
+  console.error(error.stack);
+  process.exit(1);
+});