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

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

@@ -4,7 +4,7 @@ description: "Apply systematic problem-solving methodologies to crack complex ch
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
+config_source: "{project-root}/.bmad/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
@@ -14,7 +14,7 @@ date: system-generated
 # Example: data="{path}/problem-brief.md" provides context
 
 # Module path and component files
-installed_path: "{project-root}/{bmad_folder}/cis/workflows/problem-solving"
+installed_path: "{project-root}/.bmad/cis/workflows/problem-solving"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 
@@ -30,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_folder}/cis/workflows/problem-solving/instructions.md"
-  template: "{bmad_folder}/cis/workflows/problem-solving/template.md"
+  instructions: ".bmad/cis/workflows/problem-solving/instructions.md"
+  template: ".bmad/cis/workflows/problem-solving/template.md"
   web_bundle_files:
-    - "{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"
+    - ".bmad/cis/workflows/problem-solving/instructions.md"
+    - ".bmad/cis/workflows/problem-solving/template.md"
+    - ".bmad/cis/workflows/problem-solving/solving-methods.csv"

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

@@ -3,8 +3,8 @@
 ## Workflow
 
 <workflow>
-<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>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>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>

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

@@ -4,7 +4,7 @@ description: "Craft compelling narratives using proven story frameworks and tech
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
+config_source: "{project-root}/.bmad/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
@@ -14,7 +14,7 @@ date: system-generated
 # Example: data="{path}/brand-info.md" provides brand context
 
 # Module path and component files
-installed_path: "{project-root}/{bmad_folder}/cis/workflows/storytelling"
+installed_path: "{project-root}/.bmad/cis/workflows/storytelling"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 
@@ -30,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_folder}/cis/workflows/storytelling/instructions.md"
-  template: "{bmad_folder}/cis/workflows/storytelling/template.md"
+  instructions: ".bmad/cis/workflows/storytelling/instructions.md"
+  template: ".bmad/cis/workflows/storytelling/template.md"
   web_bundle_files:
-    - "{bmad_folder}/cis/workflows/storytelling/instructions.md"
-    - "{bmad_folder}/cis/workflows/storytelling/template.md"
-    - "{bmad_folder}/cis/workflows/storytelling/story-types.csv"
+    - ".bmad/cis/workflows/storytelling/instructions.md"
+    - ".bmad/cis/workflows/storytelling/template.md"
+    - ".bmad/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_folder}/_cfg/agents/{agent-filename} if exists (replace, not merge)</step>
+    <step n="2">Override with {project-root}/.bmad/_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="progressive-workflow">
         When command has: run-progressive-workflow="path/to/x.yaml" You MUST:
-        1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/workflow.xml
+        1. CRITICAL: Always LOAD {project-root}/.bmad/core/tasks/workflow.xml
         2. READ its entire contents - the is the CORE OS for EXECUTING workflows
         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_folder}/core/tasks/validate-workflow.xml
+        1. You MUST LOAD the file at: {project-root}/.bmad/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_folder}/core/tasks/workflow.xml":
-      1. Find the &lt;file id="{bmad_folder}/core/tasks/workflow.xml"&gt; element in this document
+      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
       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_folder}/" or "{project-root}/{bmad_folder}/" refer to &lt;file id="..."&gt; elements</rule>
+      <rule>File paths starting with ".bmad/" or "{project-root}/.bmad/" 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/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_folder}/{{module}}/config.yaml NOW
+    - Load and read {project-root}/.bmad/{{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>

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_folder}/core/tasks/validate-workflow.xml
+  1. You MUST LOAD the file at: {project-root}/.bmad/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_folder}/core/tasks/workflow.xml
+  1. CRITICAL: Always LOAD {project-root}/.bmad/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_folder}/core/tasks/workflow.xml":
-    1. Find the &lt;file id="{bmad_folder}/core/tasks/workflow.xml"&gt; element in this document
+    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
     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_folder}/" refer to &lt;file id="..."&gt; elements</rule>
+    <rule>File paths starting with ".bmad/" 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/tools/cli/README.md

@@ -105,7 +105,7 @@ The installer is a multi-stage system that handles agent compilation, IDE integr
    - Resolve module dependencies (4-pass system)
 
 3. Install Core + Modules
-   - Copy files to {target}/{bmad_folder}/
+   - Copy files to {target}/.bmad/
    - Compile agents: YAML → Markdown/XML (forWebBundle: false)
    - Merge customize.yaml files if they exist
    - Inject activation blocks based on agent capabilities
@@ -131,7 +131,7 @@ The installer is a multi-stage system that handles agent compilation, IDE integr
 
 ```
 {target}/
-├── {bmad_folder}/
+├── .bmad/
 │   ├── core/              # Always installed
 │   ├── {module}/          # Selected modules
 │   │   ├── agents/        # Compiled .md files
@@ -239,7 +239,7 @@ Platform specifics are **IDE+module combination hooks** that execute custom logi
 
 ### Manifest System
 
-The installer generates **5 manifest files** in `{target}/{bmad_folder}/_cfg/`:
+The installer generates **5 manifest files** in `{target}/.bmad/_cfg/`:
 
 **1. Installation Manifest** (`manifest.yaml`)
 
@@ -428,7 +428,7 @@ agent:
     identity: 'You are an experienced PM...'
   menu:
     - trigger: '*create-brief'
-      workflow: '{project-root}/{bmad_folder}/bmm/workflows/.../workflow.yaml'
+      workflow: '{project-root}/.bmad/bmm/workflows/.../workflow.yaml'
 ```
 
 ### Output: IDE (Markdown with XML)
@@ -441,7 +441,7 @@ agent:
 ```xml
 <agent id="..." name="PM">
   <activation critical="MANDATORY">
-    <step n="2">Load {project-root}/{bmad_folder}/bmm/config.yaml at runtime</step>
+    <step n="2">Load {project-root}/.bmad/bmm/config.yaml at runtime</step>
     ...
   </activation>
   <persona>...</persona>
@@ -533,20 +533,20 @@ src/utility/models/fragments/
 
 ## Key Differences: Installation vs Bundling
 
-| Aspect                  | Installation (IDE)                   | Bundling (Web)                    |
-| ----------------------- | ------------------------------------ | --------------------------------- |
-| **Trigger**             | `npm run install:bmad`               | `npm run bundle`                  |
-| **Entry Point**         | `commands/install.js`                | `bundlers/bundle-web.js`          |
-| **Compiler Flag**       | `forWebBundle: false`                | `forWebBundle: true`              |
-| **Output Format**       | Markdown `.md`                       | Standalone XML `.xml`             |
-| **Output Location**     | `{target}/{bmad_folder}/` + IDE dirs | `web-bundles/`                    |
-| **Customization**       | Merges `customize.yaml`              | Base agents only                  |
-| **Dependencies**        | Referenced by path                   | Bundled inline (CDATA)            |
-| **Activation Fragment** | `activation-steps.xml`               | `web-bundle-activation-steps.xml` |
-| **Filesystem Access**   | Required                             | Not needed                        |
-| **Build Metadata**      | Included (hash)                      | Excluded                          |
-| **Path Format**         | `{project-root}` placeholders        | Stripped, wrapped as `<file>`     |
-| **Use Case**            | Local IDE development                | Web deployment                    |
+| Aspect                  | Installation (IDE)            | Bundling (Web)                    |
+| ----------------------- | ----------------------------- | --------------------------------- |
+| **Trigger**             | `npm run install:bmad`        | `npm run bundle`                  |
+| **Entry Point**         | `commands/install.js`         | `bundlers/bundle-web.js`          |
+| **Compiler Flag**       | `forWebBundle: false`         | `forWebBundle: true`              |
+| **Output Format**       | Markdown `.md`                | Standalone XML `.xml`             |
+| **Output Location**     | `{target}/.bmad/` + IDE dirs  | `web-bundles/`                    |
+| **Customization**       | Merges `customize.yaml`       | Base agents only                  |
+| **Dependencies**        | Referenced by path            | Bundled inline (CDATA)            |
+| **Activation Fragment** | `activation-steps.xml`        | `web-bundle-activation-steps.xml` |
+| **Filesystem Access**   | Required                      | Not needed                        |
+| **Build Metadata**      | Included (hash)               | Excluded                          |
+| **Path Format**         | `{project-root}` placeholders | Stripped, wrapped as `<file>`     |
+| **Use Case**            | Local IDE development         | Web deployment                    |
 
 **Activation Differences**:
 

package/tools/cli/bundlers/web-bundler.js

@@ -29,7 +29,7 @@ class WebBundler {
 
     // Temporary directory for generated manifests
     this.tempDir = path.join(process.cwd(), '.bundler-temp');
-    this.tempManifestDir = path.join(this.tempDir, 'bmad', '_cfg');
+    this.tempManifestDir = path.join(this.tempDir, '.bmad', '_cfg');
 
     // Bundle statistics
     this.stats = {
@@ -531,9 +531,9 @@ class WebBundler {
         }
 
         // Parse paths to extract module and workflow location
-        // Support both {project-root}/bmad/... and {project-root}/{bmad_folder}/... patterns
-        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
-        const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
+        // Support both {project-root}/bmad/... and {project-root}/.bmad/... patterns
+        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:\.?bmad)\/([^/]+)\/workflows\/(.+)/);
+        const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:\.?bmad)\/([^/]+)\/workflows\/(.+)/);
 
         if (!sourceMatch || !installMatch) {
           continue;
@@ -584,9 +584,9 @@ class WebBundler {
     let yamlContent = await fs.readFile(workflowYamlPath, 'utf8');
 
     // Replace config_source with new module reference
-    // Support both old format (bmad) and new format ({bmad_folder})
-    const configSourcePattern = /config_source:\s*["']?\{project-root\}\/(?:\{bmad_folder\}|bmad)\/[^/]+\/config\.yaml["']?/g;
-    const newConfigSource = `config_source: "{project-root}/{bmad_folder}/${newModuleName}/config.yaml"`;
+    // Support both old format (bmad) and new format (.bmad)
+    const configSourcePattern = /config_source:\s*["']?\{project-root\}\/(?:\.?bmad)\/[^/]+\/config\.yaml["']?/g;
+    const newConfigSource = `config_source: "{project-root}/.bmad/${newModuleName}/config.yaml"`;
 
     const updatedYaml = yamlContent.replaceAll(configSourcePattern, newConfigSource);
     await fs.writeFile(workflowYamlPath, updatedYaml, 'utf8');
@@ -723,7 +723,7 @@ class WebBundler {
       /tools="([^"]+)"/g,
       /knowledge="([^"]+)"/g,
       /{project-root}\/([^"'\s<>]+)/g, // Legacy {project-root} paths
-      /\bbmad\/([^"'\s<>]+)/g, // Direct bmad/ paths (after {bmad_folder} replacement)
+      /\bbmad\/([^"'\s<>]+)/g, // Direct bmad/ paths (after .bmad replacement)
     ];
 
     for (const pattern of patterns) {
@@ -733,8 +733,8 @@ class WebBundler {
         let filePath = match[1];
         // Remove {project-root} prefix if present
         filePath = filePath.replace(/^{project-root}\//, '');
-        // Remove {bmad_folder} prefix if present (should be rare, mostly replaced already)
-        filePath = filePath.replace(/^{bmad_folder}\//, 'bmad/');
+        // Remove .bmad prefix if present (should be rare, mostly replaced already)
+        filePath = filePath.replace(/^.bmad\//, 'bmad/');
 
         // For bmad/ pattern, prepend 'bmad/' since it was captured without it
         if (pattern.source.includes(String.raw`\bbmad\/`)) {
@@ -760,8 +760,8 @@ class WebBundler {
       while ((match = pattern.exec(xml)) !== null) {
         let workflowPath = match[1];
         workflowPath = workflowPath.replace(/^{project-root}\//, '');
-        // Remove {bmad_folder} prefix if present and replace with bmad
-        workflowPath = workflowPath.replace(/^{bmad_folder}\//, 'bmad/');
+        // Remove .bmad prefix if present and replace with bmad
+        workflowPath = workflowPath.replace(/^.bmad\//, 'bmad/');
 
         // Skip obvious placeholder/example paths
         if (workflowPath && workflowPath.endsWith('.yaml') && !workflowPath.includes('path/to/') && !workflowPath.includes('example')) {
@@ -851,7 +851,7 @@ class WebBundler {
         if (deps) {
           for (const dep of deps) {
             let depPath = dep.replaceAll(/['"]/g, '').replace(/^{project-root}\//, '');
-            depPath = depPath.replace(/^{bmad_folder}\//, 'bmad/');
+            depPath = depPath.replace(/^.bmad\//, 'bmad/');
             if (depPath && !processed.has(depPath)) {
               await this.processFileDependency(depPath, dependencies, processed, moduleName, warnings);
             }
@@ -865,7 +865,7 @@ class WebBundler {
         if (templates) {
           for (const template of templates) {
             let templatePath = template.replaceAll(/['"]/g, '').replace(/^{project-root}\//, '');
-            templatePath = templatePath.replace(/^{bmad_folder}\//, 'bmad/');
+            templatePath = templatePath.replace(/^.bmad\//, 'bmad/');
             if (templatePath && !processed.has(templatePath)) {
               await this.processFileDependency(templatePath, dependencies, processed, moduleName, warnings);
             }
@@ -1053,13 +1053,13 @@ class WebBundler {
       bundleYamlContent = yamlContent;
     }
 
-    // Process {project-root} and {bmad_folder} references in the YAML content
+    // Process {project-root} and .bmad references in the YAML content
     bundleYamlContent = this.processProjectRootReferences(bundleYamlContent);
 
     // Include the YAML file with only web_bundle content, wrapped in XML
     // Process the workflow path to create a clean ID
     let yamlId = workflowPath.replace(/^{project-root}\//, '');
-    yamlId = yamlId.replace(/^{bmad_folder}\//, 'bmad/');
+    yamlId = yamlId.replace(/^.bmad\//, 'bmad/');
     const wrappedYaml = this.wrapContentInXml(bundleYamlContent, yamlId, 'yaml');
     dependencies.set(yamlId, wrappedYaml);
 
@@ -1078,7 +1078,7 @@ class WebBundler {
       for (const bundleFilePath of bundleFiles) {
         // Process the file path to create a clean ID for checking if already processed
         let cleanFilePath = bundleFilePath.replace(/^{project-root}\//, '');
-        cleanFilePath = cleanFilePath.replace(/^{bmad_folder}\//, 'bmad/');
+        cleanFilePath = cleanFilePath.replace(/^.bmad\//, 'bmad/');
 
         if (processed.has(cleanFilePath)) {
           continue;
@@ -1087,7 +1087,7 @@ class WebBundler {
         const bundleActualPath = this.resolveFilePath(bundleFilePath, moduleName);
 
         if (!bundleActualPath || !(await fs.pathExists(bundleActualPath))) {
-          // Use the cleaned path in warnings (with {bmad_folder} replaced)
+          // Use the cleaned path in warnings (with .bmad replaced)
           warnings.push(cleanFilePath);
           continue;
         }
@@ -1136,7 +1136,7 @@ class WebBundler {
     }
 
     let fileContent = await fs.readFile(actualPath, 'utf8');
-    // Process {project-root} and {bmad_folder} references
+    // Process {project-root} and .bmad references
     fileContent = this.processProjectRootReferences(fileContent);
     const wrappedContent = this.wrapContentInXml(fileContent, coreWorkflowPath, 'xml');
     dependencies.set(coreWorkflowPath, wrappedContent);
@@ -1162,7 +1162,7 @@ class WebBundler {
       }
 
       let fileContent = await fs.readFile(actualPath, 'utf8');
-      // Process {project-root} and {bmad_folder} references
+      // Process {project-root} and .bmad references
       fileContent = this.processProjectRootReferences(fileContent);
       const fileExt = path.extname(actualPath).toLowerCase().replace('.', '');
       const wrappedContent = this.wrapContentInXml(fileContent, filePath, fileExt);
@@ -1196,8 +1196,8 @@ class WebBundler {
   async processWildcardDependency(pattern, dependencies, processed, moduleName, warnings = []) {
     // Remove {project-root} prefix
     pattern = pattern.replace(/^{project-root}\//, '');
-    // Replace {bmad_folder} with bmad
-    pattern = pattern.replace(/^{bmad_folder}\//, 'bmad/');
+    // Replace .bmad with bmad
+    pattern = pattern.replace(/^.bmad\//, 'bmad/');
 
     // Get directory and file pattern
     const lastSlash = pattern.lastIndexOf('/');
@@ -1265,9 +1265,6 @@ class WebBundler {
   resolveFilePath(filePath, moduleName) {
     // Remove {project-root} prefix
     filePath = filePath.replace(/^{project-root}\//, '');
-    // Replace {bmad_folder} with bmad
-    filePath = filePath.replace(/^{bmad_folder}\//, 'bmad/');
-    filePath = filePath.replace(/^{bmad_folder}$/, 'bmad');
 
     // Check temp directory first for _cfg files
     if (filePath.startsWith('bmad/_cfg/')) {
@@ -1278,11 +1275,6 @@ class WebBundler {
       }
     }
 
-    // Handle different path patterns for bmad files
-    // bmad/cis/tasks/brain-session.md -> src/modules/cis/tasks/brain-session.md
-    // bmad/core/tasks/create-doc.md -> src/core/tasks/create-doc.md
-    // bmad/bmm/templates/brief.md -> src/modules/bmm/templates/brief.md
-
     let actualPath = filePath;
 
     if (filePath.startsWith('bmad/')) {
@@ -1334,15 +1326,13 @@ class WebBundler {
   }
 
   /**
-   * Process and remove {project-root} references and replace {bmad_folder} with bmad
+   * Process and remove {project-root} references
    */
   processProjectRootReferences(content) {
     // Remove {project-root}/ prefix (with slash)
     content = content.replaceAll('{project-root}/', '');
     // Also remove {project-root} without slash
     content = content.replaceAll('{project-root}', '');
-    // Replace {bmad_folder} with bmad
-    content = content.replaceAll('{bmad_folder}', 'bmad');
     return content;
   }
 

package/tools/cli/commands/build.js

@@ -80,7 +80,7 @@ module.exports = {
  */
 async function buildAgent(projectDir, agentName) {
   // First check standalone agents in bmad/agents/{agentname}/
-  const standaloneAgentDir = path.join(projectDir, 'bmad', 'agents', agentName);
+  const standaloneAgentDir = path.join(projectDir, '.bmad', 'agents', agentName);
   let standaloneYamlPath = path.join(standaloneAgentDir, `${agentName}.agent.yaml`);
 
   // If exact match doesn't exist, look for any .agent.yaml file in the directory
@@ -99,7 +99,7 @@ async function buildAgent(projectDir, agentName) {
     // Build the standalone agent
     console.log(chalk.cyan(`  Building standalone agent ${agentName}...`));
 
-    const customizePath = path.join(projectDir, 'bmad', '_cfg', 'agents', `${agentName}.customize.yaml`);
+    const customizePath = path.join(projectDir, '.bmad', '_cfg', 'agents', `${agentName}.customize.yaml`);
     const customizeExists = await fs.pathExists(customizePath);
 
     await builder.buildAgent(standaloneYamlPath, customizeExists ? customizePath : null, outputPath, { includeMetadata: true });
@@ -109,7 +109,7 @@ async function buildAgent(projectDir, agentName) {
   }
 
   // Find the agent YAML file in .claude/commands/bmad/
-  const bmadCommandsDir = path.join(projectDir, '.claude', 'commands', 'bmad');
+  const bmadCommandsDir = path.join(projectDir, '.claude', 'commands', '.bmad');
 
   // Search all module directories for the agent
   const modules = await fs.readdir(bmadCommandsDir);
@@ -149,7 +149,7 @@ async function buildAllAgents(projectDir) {
   let builtCount = 0;
 
   // First, build standalone agents in bmad/agents/
-  const standaloneAgentsDir = path.join(projectDir, 'bmad', 'agents');
+  const standaloneAgentsDir = path.join(projectDir, '.bmad', 'agents');
   if (await fs.pathExists(standaloneAgentsDir)) {
     console.log(chalk.cyan('\nBuilding standalone agents...'));
     const agentDirs = await fs.readdir(standaloneAgentsDir);
@@ -177,7 +177,7 @@ async function buildAllAgents(projectDir) {
 
       console.log(chalk.cyan(`  Building standalone agent ${agentName}...`));
 
-      const customizePath = path.join(projectDir, 'bmad', '_cfg', 'agents', `${agentName}.customize.yaml`);
+      const customizePath = path.join(projectDir, '.bmad', '_cfg', 'agents', `${agentName}.customize.yaml`);
       const customizeExists = await fs.pathExists(customizePath);
 
       await builder.buildAgent(agentYamlPath, customizeExists ? customizePath : null, outputPath, { includeMetadata: true });

package/tools/cli/installers/lib/core/config-collector.js

@@ -132,8 +132,12 @@ class ConfigCollector {
    * Collect configuration for all modules
    * @param {Array} modules - List of modules to configure (including 'core')
    * @param {string} projectDir - Target project directory
+   * @param {Object} options - Additional options
+   * @param {Map} options.customModulePaths - Map of module ID to source path for custom modules
    */
-  async collectAllConfigurations(modules, projectDir) {
+  async collectAllConfigurations(modules, projectDir, options = {}) {
+    // Store custom module paths for use in collectModuleConfig
+    this.customModulePaths = options.customModulePaths || new Map();
     await this.loadExistingConfig(projectDir);
 
     // Check if core was already collected (e.g., in early collection phase)
@@ -451,11 +455,21 @@ class ConfigCollector {
       this.allAnswers = {};
     }
     // Load module's config
-    // First, try the standard src/modules location
-    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'module.yaml');
-    let moduleConfigPath = path.join(getModulePath(moduleName), 'module.yaml');
+    // First, check if we have a custom module path for this module
+    let installerConfigPath = null;
+    let moduleConfigPath = null;
+
+    if (this.customModulePaths && this.customModulePaths.has(moduleName)) {
+      const customPath = this.customModulePaths.get(moduleName);
+      installerConfigPath = path.join(customPath, '_module-installer', 'module.yaml');
+      moduleConfigPath = path.join(customPath, 'module.yaml');
+    } else {
+      // Try the standard src/modules location
+      installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'module.yaml');
+      moduleConfigPath = path.join(getModulePath(moduleName), 'module.yaml');
+    }
 
-    // If not found in src/modules, we need to find it by searching the project
+    // If not found in src/modules or custom paths, search the project
     if (!(await fs.pathExists(installerConfigPath)) && !(await fs.pathExists(moduleConfigPath))) {
       // Use the module manager to find the module source
       const { ModuleManager } = require('../modules/manager');
@@ -682,15 +696,6 @@ class ConfigCollector {
       }
     }
 
-    // Special handling for bmad_folder: detect existing folder name
-    if (moduleName === 'core' && key === 'bmad_folder' && !existingValue && this.currentProjectDir) {
-      // Try to detect the existing BMAD folder name
-      const detectedFolder = await this.detectExistingBmadFolder(this.currentProjectDir);
-      if (detectedFolder) {
-        existingValue = detectedFolder;
-      }
-    }
-
     // Special handling for user_name: default to system user
     if (moduleName === 'core' && key === 'user_name' && !existingValue) {
       item.default = this.getDefaultUsername();

package/tools/cli/installers/lib/core/custom-module-cache.js

@@ -51,7 +51,19 @@ class CustomModuleCache {
   }
 
   /**
-   * Calculate hash of a file or directory
+   * Stream a file into the hash to avoid loading entire file into memory
+   */
+  async hashFileStream(filePath, hash) {
+    return new Promise((resolve, reject) => {
+      const stream = require('node:fs').createReadStream(filePath);
+      stream.on('data', (chunk) => hash.update(chunk));
+      stream.on('end', resolve);
+      stream.on('error', reject);
+    });
+  }
+
+  /**
+   * Calculate hash of a file or directory using streaming to minimize memory usage
    */
   async calculateHash(sourcePath) {
     const hash = crypto.createHash('sha256');
@@ -76,14 +88,14 @@ class CustomModuleCache {
       files.sort(); // Ensure consistent order
 
       for (const file of files) {
-        const content = await fs.readFile(file);
         const relativePath = path.relative(sourcePath, file);
-        hash.update(relativePath + '|' + content.toString('base64'));
+        // Hash the path first, then stream file contents
+        hash.update(relativePath + '|');
+        await this.hashFileStream(file, hash);
       }
     } else {
-      // For single files
-      const content = await fs.readFile(sourcePath);
-      hash.update(content);
+      // For single files, stream directly into hash
+      await this.hashFileStream(sourcePath, hash);
     }
 
     return hash.digest('hex');