bmad-method 6.2.3-next.30 → 6.2.3-next.32

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.2.3-next.30",
+  "version": "6.2.3-next.32",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md

@@ -0,0 +1,62 @@
+# Compile Epic Context
+
+**Task**
+Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`).
+
+**Steps**
+
+1. Read the epics file and extract the target epic's title, goal, and list of stories.
+2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief).
+3. Pull only the information relevant to this epic.
+4. Write the compiled context to the exact output path using the format below.
+
+## Exact Output Format
+
+Use these headings:
+
+```markdown
+# Epic {N} Context: {Epic Title}
+
+<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
+
+## Goal
+
+{One clear paragraph: what this epic achieves and why it matters.}
+
+## Stories
+
+- Story X.Y: Brief title only
+- ...
+
+## Requirements & Constraints
+
+{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}
+
+## Technical Decisions
+
+{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}
+
+## UX & Interaction Patterns
+
+{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}
+
+## Cross-Story Dependencies
+
+{Dependencies between stories in this epic or with other epics/systems (omit if none).}
+```
+
+## Rules
+
+- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc.
+- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't.
+- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
+- **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
+- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
+- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material.
+- **Never hallucinate content.** If source material doesn't say something, don't invent it.
+- **Omit empty sections entirely**, except Goal and Stories, which are always required.
+
+## Error handling
+
+- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file.
+- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -41,19 +41,32 @@ Never ask extra questions if you already understand what the user intends.
 1. Load context.
    - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
    - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
-   - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
-     - **PRD** (`*prd*`) — product requirements and success criteria
-     - **Architecture** (`*architecture*`) — technical design decisions and constraints
-     - **UX/Design** (`*ux*`) — user experience and interaction design
-     - **Epics** (`*epic*`) — feature breakdown into implementable stories
-     - **Product Brief** (`*brief*`) — project vision and scope
-   - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
-   - **Previous story continuity.** Using the intent and loaded context (especially any epics file), infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the artifact listing, and epics content together. If the intent is an epic story:
-     1. Identify the epic and story number.
-     2. Scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number.
-     3. Load the most recent one (highest story number below current).
-     4. Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning.
-     If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it. If the intent is not an epic story, or no previous spec exists, skip this silently.
+   - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
+
+     **A) Epic story path** — if the intent is clearly an epic story:
+
+     1. Identify the epic number and (if present) the story number. If you can't identify an epic number, use path B.
+
+     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+        - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
+        - **If missing, empty, or invalid:** continue to step 3.
+
+     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
+        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+        - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+
+     4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
+
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+
+     **B) Freeform path** — if the intent is not an epic story:
+     - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
+       - **PRD** (`*prd*`) — product requirements and success criteria
+       - **Architecture** (`*architecture*`) — technical design decisions and constraints
+       - **UX/Design** (`*ux*`) — user experience and interaction design
+       - **Epics** (`*epic*`) — feature breakdown into implementable stories
+       - **Product Brief** (`*brief*`) — project vision and scope
+     - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
 2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
 3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
 4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:

package/tools/installer/commands/install.js

@@ -22,6 +22,7 @@ module.exports = {
     ['--communication-language <lang>', 'Language for agent communication (default: English)'],
     ['--document-output-language <lang>', 'Language for document output (default: English)'],
     ['--output-folder <path>', 'Output folder path relative to project root (default: _bmad-output)'],
+    ['--custom-source <sources>', 'Comma-separated Git URLs or local paths to install custom modules from'],
     ['-y, --yes', 'Accept all defaults and skip prompts where possible'],
   ],
   action: async (options) => {

package/tools/installer/core/installer.js

@@ -569,6 +569,7 @@ class Installer {
    */
   async _installOfficialModules(config, paths, officialModuleIds, addResult, isQuickUpdate, officialModules, ctx) {
     const { message, installedModuleNames } = ctx;
+    const { CustomModuleManager } = require('../modules/custom-module-manager');
 
     for (const moduleName of officialModuleIds) {
       if (installedModuleNames.has(moduleName)) continue;
@@ -591,11 +592,15 @@ class Installer {
         },
       );
 
-      // Get display name from source module.yaml; version from marketplace.json
+      // Get display name from source module.yaml; version from resolution cache or marketplace.json
       const sourcePath = await officialModules.findModuleSource(moduleName, { silent: true });
       const moduleInfo = sourcePath ? await officialModules.getModuleInfo(sourcePath, moduleName, '') : null;
       const displayName = moduleInfo?.name || moduleName;
-      const version = sourcePath ? await this._getMarketplaceVersion(sourcePath) : '';
+
+      // Prefer version from resolution cache (accurate for custom/local modules),
+      // fall back to marketplace.json walk-up for official modules
+      const cachedResolution = CustomModuleManager._resolutionCache.get(moduleName);
+      const version = cachedResolution?.version || (sourcePath ? await this._getMarketplaceVersion(sourcePath) : '');
       addResult(displayName, 'ok', '', { moduleCode: moduleName, newVersion: version });
     }
   }
@@ -1189,7 +1194,7 @@ class Installer {
     const customMgr = new CustomModuleManager();
     for (const moduleId of installedModules) {
       if (!availableModules.some((m) => m.id === moduleId)) {
-        const customSource = await customMgr.findModuleSourceByCode(moduleId);
+        const customSource = await customMgr.findModuleSourceByCode(moduleId, { bmadDir });
         if (customSource) {
           availableModules.push({
             id: moduleId,

package/tools/installer/core/manifest-generator.js

@@ -412,7 +412,7 @@ class ManifestGenerator {
       // Get existing install date if available
       const existing = existingModulesMap.get(moduleName);
 
-      updatedModules.push({
+      const moduleEntry = {
         name: moduleName,
         version: versionInfo.version,
         installDate: existing?.installDate || new Date().toISOString(),
@@ -420,7 +420,9 @@ class ManifestGenerator {
         source: versionInfo.source,
         npmPackage: versionInfo.npmPackage,
         repoUrl: versionInfo.repoUrl,
-      });
+      };
+      if (versionInfo.localPath) moduleEntry.localPath = versionInfo.localPath;
+      updatedModules.push(moduleEntry);
     }
 
     const manifest = {

package/tools/installer/core/manifest.js

@@ -181,10 +181,10 @@ class Manifest {
 
     // Handle adding a new module with version info
     if (updates.addModule) {
-      const { name, version, source, npmPackage, repoUrl } = updates.addModule;
+      const { name, version, source, npmPackage, repoUrl, localPath } = updates.addModule;
       const existing = manifest.modules.find((m) => m.name === name);
       if (!existing) {
-        manifest.modules.push({
+        const entry = {
           name,
           version: version || null,
           installDate: new Date().toISOString(),
@@ -192,7 +192,9 @@ class Manifest {
           source: source || 'external',
           npmPackage: npmPackage || null,
           repoUrl: repoUrl || null,
-        });
+        };
+        if (localPath) entry.localPath = localPath;
+        manifest.modules.push(entry);
       }
     }
 
@@ -280,7 +282,7 @@ class Manifest {
 
     if (existingIndex === -1) {
       // Module doesn't exist, add it
-      manifest.modules.push({
+      const entry = {
         name: moduleName,
         version: options.version || null,
         installDate: new Date().toISOString(),
@@ -288,7 +290,9 @@ class Manifest {
         source: options.source || 'unknown',
         npmPackage: options.npmPackage || null,
         repoUrl: options.repoUrl || null,
-      });
+      };
+      if (options.localPath) entry.localPath = options.localPath;
+      manifest.modules.push(entry);
     } else {
       // Module exists, update its version info
       const existing = manifest.modules[existingIndex];
@@ -298,6 +302,7 @@ class Manifest {
         source: options.source || existing.source,
         npmPackage: options.npmPackage === undefined ? existing.npmPackage : options.npmPackage,
         repoUrl: options.repoUrl === undefined ? existing.repoUrl : options.repoUrl,
+        localPath: options.localPath === undefined ? existing.localPath : options.localPath,
         lastUpdated: new Date().toISOString(),
       };
     }
@@ -832,17 +837,19 @@ class Manifest {
       };
     }
 
-    // Check if this is a custom module (from user-provided URL)
+    // Check if this is a custom module (from user-provided URL or local path)
     const { CustomModuleManager } = require('../modules/custom-module-manager');
     const customMgr = new CustomModuleManager();
-    const customSource = await customMgr.findModuleSourceByCode(moduleName);
-    if (customSource) {
-      const customVersion = await this._readMarketplaceVersion(moduleName, moduleSourcePath);
+    const resolved = customMgr.getResolution(moduleName);
+    const customSource = await customMgr.findModuleSourceByCode(moduleName, { bmadDir });
+    if (customSource || resolved) {
+      const customVersion = resolved?.version || (await this._readMarketplaceVersion(moduleName, moduleSourcePath));
       return {
         version: customVersion,
         source: 'custom',
         npmPackage: null,
-        repoUrl: null,
+        repoUrl: resolved?.repoUrl || null,
+        localPath: resolved?.localPath || null,
       };
     }