diff --git a/docs/how-to/install-bmad.md b/docs/how-to/install-bmad.md index 224704a478..97ab03a25f 100644 --- a/docs/how-to/install-bmad.md +++ b/docs/how-to/install-bmad.md @@ -31,13 +31,17 @@ npx bmad-method install The interactive flow asks you five things: 1. Installation directory (defaults to the current working directory) -2. Which modules to install (checkboxes for core, bmm, bmb, cis, gds, tea) +2. Which modules to install (checkboxes for core, bmm, bmb, cis, gds, tea, bma) 3. **"Ready to install (all stable)?"** — Yes accepts the latest released tag for every external module 4. Which AI tools/IDEs to integrate with (claude-code, cursor, and others) 5. Per-module config (name, language, output folder) Accept the defaults and you land on the latest stable release of every module, configured for your chosen tool. +:::caution[BMad Automator constraints] +`bma` installs runnable Automator skills only for the Claude Code entrypoint. Codex is supported as a worker target only, and worker sessions currently require `tmux` on macOS. +::: + :::tip[Just want the newest prerelease?] ```bash @@ -53,7 +57,7 @@ Two independent axes control what ends up on disk. ### Axis 1: external module channels -Every external module — bmb, cis, gds, tea, and any community module — installs on one of three channels: +Every external module — bmb, cis, gds, tea, bma, and any community module — installs on one of three channels: | Channel | What gets installed | Who picks this | | ------------------ | ---------------------------------------------------------------------------- | --------------------------------------- | diff --git a/docs/reference/modules.md b/docs/reference/modules.md index 6bdc641908..c26d02816c 100644 --- a/docs/reference/modules.md +++ b/docs/reference/modules.md @@ -71,6 +71,24 @@ Enterprise-grade test strategy, automation guidance, and release gate decisions - NFR assessment, CI setup, and framework scaffolding - P0-P3 prioritization with optional Playwright Utils and MCP integrations +## BMad Automator (Experimental) + +Automates the BMad story build loop with a pure skill bundle sourced from the separate Automator repository. + +- **Code:** `bma` +- **npm:** [`bmad-story-automator`](https://www.npmjs.com/package/bmad-story-automator) +- **GitHub:** [bmad-code-org/bmad-automator](https://github.com/bmad-code-org/bmad-automator) + +:::caution[Experimental Claude Code-only entrypoint] +BMad Automator only runs from Claude Code. It currently supports Claude Code and Codex worker sessions, and requires tmux on macOS. +::: + +**Provides:** + +- Story build-cycle automation across story creation, development, QA automation, review, and retrospective +- Resumable tmux orchestration state +- Claude Code entry skill plus Claude Code/Codex worker-session coordination + ## Community Modules Community modules and a module marketplace are coming. Check the [BMad GitHub organization](https://github.com/bmad-code-org) for updates. diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 4447f90102..cf1929eb52 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -18,6 +18,7 @@ const { Installer } = require('../tools/installer/core/installer'); const { ManifestGenerator } = require('../tools/installer/core/manifest-generator'); const { OfficialModules } = require('../tools/installer/modules/official-modules'); const { IdeManager } = require('../tools/installer/ide/manager'); +const { ExternalModuleManager } = require('../tools/installer/modules/external-manager'); const { clearCache, loadPlatformCodes } = require('../tools/installer/ide/platform-codes'); // ANSI colors @@ -85,6 +86,42 @@ async function createTestBmadFixture() { return fixtureDir; } +async function createAutomatorBmadFixture() { + const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-automator-fixture-')); + const fixtureDir = path.join(fixtureRoot, '_bmad'); + await fs.ensureDir(path.join(fixtureDir, '_config')); + + await fs.writeFile( + path.join(fixtureDir, '_config', 'skill-manifest.csv'), + [ + 'canonicalId,name,description,module,path', + '"bmad-master","bmad-master","Minimal core skill","core","_bmad/core/bmad-master/SKILL.md"', + '"bmad-story-automator","bmad-story-automator","Automator skill","bma","_bmad/bma/bmad-story-automator/SKILL.md"', + '"bmad-story-automator-review","bmad-story-automator-review","Automator review skill","bma","_bmad/bma/bmad-story-automator-review/SKILL.md"', + '', + ].join('\n'), + ); + + const coreSkillDir = path.join(fixtureDir, 'core', 'bmad-master'); + await fs.ensureDir(coreSkillDir); + await fs.writeFile( + path.join(coreSkillDir, 'SKILL.md'), + ['---', 'name: bmad-master', 'description: Minimal core skill', '---', '', 'Core skill body.'].join('\n'), + ); + + for (const skillName of ['bmad-story-automator', 'bmad-story-automator-review']) { + const skillDir = path.join(fixtureDir, 'bma', skillName); + await fs.ensureDir(skillDir); + await fs.writeFile( + path.join(skillDir, 'SKILL.md'), + ['---', `name: ${skillName}`, 'description: Automator skill', '---', '', 'Automator body.'].join('\n'), + ); + await fs.writeFile(path.join(skillDir, 'workflow.md'), `# ${skillName}\n\nAutomator workflow body.\n`); + } + + return fixtureDir; +} + async function createSkillCollisionFixture() { const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-skill-collision-')); const fixtureDir = path.join(fixtureRoot, '_bmad'); @@ -3237,6 +3274,116 @@ async function runTests() { console.log(''); + // ============================================================ + // Test Suite 45: Automator External Skill-Only Module + // ============================================================ + console.log(`${colors.yellow}Test Suite 45: Automator External Skill-Only Module${colors.reset}\n`); + + let tempProjectDir42; + let installedBmadDir42; + try { + const externalManager42 = new ExternalModuleManager(); + const automatorInfo42 = await externalManager42.getModuleByCode('bma'); + assert(automatorInfo42 !== null, 'BMad Automator is registered as an external module'); + assert(automatorInfo42.type === 'experimental', 'BMad Automator is marked experimental'); + assert(automatorInfo42.sourceRoot === 'payload/.claude/skills', 'BMad Automator uses source-root for pure skill payload'); + assert( + automatorInfo42.installTargets.length === 1 && automatorInfo42.installTargets.includes('claude-code'), + 'BMad Automator is limited to Claude Code skill installation', + ); + const normalizedInfo42 = externalManager42._normalizeModule({ + name: 'bad-shapes', + code: 'bad', + repository: 'https://example.com/bad.git', + install_targets: 'claude-code', + worker_targets: { bad: true }, + requirements: ['tmux', { bad: true }, false], + }); + assert( + Array.isArray(normalizedInfo42.installTargets) && normalizedInfo42.installTargets.includes('claude-code'), + 'External module install targets normalize scalar values to arrays', + ); + assert( + Array.isArray(normalizedInfo42.workerTargets) && normalizedInfo42.workerTargets.length === 0, + 'External module worker targets drop invalid shapes', + ); + assert( + normalizedInfo42.requirements.length === 2 && + normalizedInfo42.requirements.includes('tmux') && + normalizedInfo42.requirements.includes('false'), + 'External module requirements normalize scalar array entries', + ); + + tempProjectDir42 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-automator-target-')); + installedBmadDir42 = await createAutomatorBmadFixture(); + + const ideManager42 = new IdeManager(); + await ideManager42.ensureInitialized(); + + const codexResult42 = await ideManager42.setup('codex', tempProjectDir42, installedBmadDir42, { + silent: true, + selectedModules: ['core', 'bma'], + }); + assert(codexResult42.success === true, 'Codex setup succeeds with automator module selected'); + assert( + await fs.pathExists(path.join(tempProjectDir42, '.agents', 'skills', 'bmad-master', 'SKILL.md')), + 'Codex setup still installs supported core skills', + ); + assert( + !(await fs.pathExists(path.join(tempProjectDir42, '.agents', 'skills', 'bmad-story-automator', 'SKILL.md'))), + 'Codex setup skips Claude Code-only automator skill', + ); + assert( + !(await fs.pathExists(path.join(tempProjectDir42, '.agents', 'skills', 'bmad-story-automator-review', 'SKILL.md'))), + 'Codex setup skips Claude Code-only automator review skill', + ); + + const escapeRoot42 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-source-root-')); + const escapeRepo42 = path.join(escapeRoot42, 'repo'); + await fs.ensureDir(escapeRepo42); + const escapeManager42 = new ExternalModuleManager(); + escapeManager42.getModuleByCode = async () => ({ + code: 'escape', + builtIn: false, + sourceRoot: '../outside', + }); + escapeManager42.cloneExternalModule = async () => escapeRepo42; + let rejectedEscapingSourceRoot42 = false; + try { + await escapeManager42.findExternalModuleSource('escape'); + } catch (error) { + rejectedEscapingSourceRoot42 = error.message.includes('source-root escapes repository'); + } finally { + await fs.remove(escapeRoot42).catch(() => {}); + } + assert(rejectedEscapingSourceRoot42, 'External module source-root cannot escape cloned repository'); + + const claudeResult42 = await ideManager42.setup('claude-code', tempProjectDir42, installedBmadDir42, { + silent: true, + selectedModules: ['core', 'bma'], + }); + assert(claudeResult42.success === true, 'Claude Code setup succeeds with automator module selected'); + assert( + await fs.pathExists(path.join(tempProjectDir42, '.claude', 'skills', 'bmad-story-automator', 'SKILL.md')), + 'Claude Code setup installs automator skill', + ); + assert( + await fs.pathExists(path.join(tempProjectDir42, '.claude', 'skills', 'bmad-story-automator-review', 'SKILL.md')), + 'Claude Code setup installs automator review skill', + ); + assert( + await fs.pathExists(path.join(tempProjectDir42, '.claude', 'skills', 'bmad-story-automator-review', 'workflow.md')), + 'Claude Code setup copies automator workflow files', + ); + } catch (error) { + assert(false, `Automator external skill-only module test succeeds: ${error.message}`); + } finally { + if (tempProjectDir42) await fs.remove(tempProjectDir42).catch(() => {}); + if (installedBmadDir42) await fs.remove(path.dirname(installedBmadDir42)).catch(() => {}); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/installer/README.md b/tools/installer/README.md index 9e943d689d..951011c1d9 100644 --- a/tools/installer/README.md +++ b/tools/installer/README.md @@ -2,9 +2,15 @@ ## Installing external repo BMad official modules -For external official modules to be discoverable during install, ensure an entry for the external repo is added to external-official-modules.yaml. +For external official modules to be discoverable during install, ensure an entry for the external repo is added to the marketplace `registry/official.yaml` source of truth. Add the same entry to `modules/registry-fallback.yaml` only when BMAD-METHOD needs a bundled fallback or a staged registry supplement. -For community modules - this will be handled in a different way. This file is only for registration of modules under the bmad-code-org. +For community modules - this is handled through the marketplace community registry. + +Use `module-definition` for conventional module repos with `module.yaml`. +Use `source-root` for pure skill bundles that should be copied directly into `_bmad//`. +This keeps the external repo as the source of truth and avoids vendoring generated skill payloads into BMAD-METHOD. + +Experimental modules can set `type: experimental` and `install-targets` to limit which IDE integrations receive their skills. ## Post-Install Notes diff --git a/tools/installer/core/manifest-generator.js b/tools/installer/core/manifest-generator.js index f7b5d00842..1b081f35fe 100644 --- a/tools/installer/core/manifest-generator.js +++ b/tools/installer/core/manifest-generator.js @@ -246,6 +246,9 @@ class ManifestGenerator { for (const moduleName of this.updatedModules) { const moduleYamlPath = await resolveInstalledModuleYaml(moduleName); if (!moduleYamlPath) { + if (await this._isSkillOnlyModule(moduleName)) { + continue; + } // External modules live in ~/.bmad/cache/external-modules, not src/modules. // Warn rather than silently skip so missing agent rosters don't vanish // from config.toml without notice. @@ -441,6 +444,9 @@ class ManifestGenerator { for (const moduleName of this.updatedModules) { const moduleYamlPath = await resolveInstalledModuleYaml(moduleName); if (!moduleYamlPath) { + if (await this._isSkillOnlyModule(moduleName)) { + continue; + } console.warn( `[warn] writeCentralConfig: could not locate module.yaml for '${moduleName}'. ` + `Answers from this module will default to team scope — user-scoped keys may mis-file into config.toml.`, @@ -799,6 +805,27 @@ class ManifestGenerator { return false; } + + async _isSkillOnlyModule(moduleName) { + const modulePath = path.join(this.bmadDir, moduleName); + if (!(await fs.pathExists(modulePath))) return false; + if (await fs.pathExists(path.join(modulePath, 'module.yaml'))) return false; + if (!(await this._moduleUsesSourceRoot(moduleName))) return false; + return this._hasSkillMdRecursive(modulePath); + } + + async _moduleUsesSourceRoot(moduleName) { + if (!this.sourceRootModuleCodes) { + try { + const { ExternalModuleManager } = require('../modules/external-manager'); + const externalModules = await new ExternalModuleManager().listAvailable(); + this.sourceRootModuleCodes = new Set(externalModules.filter((mod) => mod.sourceRoot).map((mod) => mod.code)); + } catch { + this.sourceRootModuleCodes = new Set(); + } + } + return this.sourceRootModuleCodes.has(moduleName); + } } /** diff --git a/tools/installer/ide/_config-driven.js b/tools/installer/ide/_config-driven.js index 737e108629..08d0bafb36 100644 --- a/tools/installer/ide/_config-driven.js +++ b/tools/installer/ide/_config-driven.js @@ -26,6 +26,8 @@ class ConfigDrivenIdeSetup { this.platformConfig = platformConfig; this.installerConfig = platformConfig.installer || null; this.bmadFolderName = BMAD_FOLDER_NAME; + this.externalModuleManager = null; + this.moduleTargetCache = new Map(); // Set configDir from target_dir so detect() works this.configDir = this.installerConfig?.target_dir || null; @@ -123,13 +125,16 @@ class ConfigDrivenIdeSetup { await fs.ensureDir(targetPath); this.skillWriteTracker = new Set(); + this.skippedUnsupported = 0; const results = { skills: 0 }; results.skills = await this.installVerbatimSkills(projectDir, bmadDir, targetPath, config); + results.skippedUnsupported = this.skippedUnsupported || 0; results.skillDirectories = this.skillWriteTracker.size; await this.printSummary(results, target_dir, options); this.skillWriteTracker = null; + this.skippedUnsupported = 0; return { success: true, results }; } @@ -162,6 +167,11 @@ class ConfigDrivenIdeSetup { const canonicalId = record.canonicalId; if (!canonicalId) continue; + if (!(await this.shouldInstallSkillRecord(record))) { + this.skippedUnsupported = (this.skippedUnsupported || 0) + 1; + continue; + } + // Derive source directory from path column // path is like "_bmad/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md" // Strip bmadFolderName prefix and join with bmadDir, then get dirname @@ -196,6 +206,24 @@ class ConfigDrivenIdeSetup { return count; } + async shouldInstallSkillRecord(record) { + const moduleName = record.module; + if (!moduleName) return true; + + if (this.moduleTargetCache.has(moduleName)) { + const targets = this.moduleTargetCache.get(moduleName); + return !targets || targets.includes(this.name); + } + + const { ExternalModuleManager } = require('../modules/external-manager'); + this.externalModuleManager = this.externalModuleManager || new ExternalModuleManager(); + const moduleInfo = await this.externalModuleManager.getModuleByCode(moduleName); + const targets = moduleInfo?.installTargets?.length ? moduleInfo.installTargets : null; + this.moduleTargetCache.set(moduleName, targets); + + return !targets || targets.includes(this.name); + } + /** * Print installation summary * @param {Object} results - Installation results @@ -207,6 +235,9 @@ class ConfigDrivenIdeSetup { if (count > 0) { await prompts.log.success(`${this.name} configured: ${count} skills → ${targetDir}`); } + if (results.skippedUnsupported > 0) { + await prompts.log.warn(`${this.name}: skipped ${results.skippedUnsupported} skill(s) that do not support this IDE`); + } } /** diff --git a/tools/installer/modules/external-manager.js b/tools/installer/modules/external-manager.js index 7d2add4fbe..37f4045159 100644 --- a/tools/installer/modules/external-manager.js +++ b/tools/installer/modules/external-manager.js @@ -16,6 +16,15 @@ function normalizeChannelName(raw) { return VALID_CHANNELS.has(lower) ? lower : null; } +function normalizeStringList(raw) { + if (raw == null || raw === '') return []; + const values = Array.isArray(raw) ? raw : [raw]; + return values + .filter((value) => ['string', 'number', 'boolean'].includes(typeof value)) + .map((value) => String(value).trim()) + .filter(Boolean); +} + /** * Conservative quoting for tag names passed to git commands. Tags are * user-typed (--pin) or come from the GitHub API. Only allow the semver @@ -120,22 +129,41 @@ class ExternalModuleManager { * @returns {Object} Normalized module info */ _normalizeModule(mod, key) { + const installTargets = mod.install_targets ?? mod['install-targets'] ?? mod.installTargets; + const workerTargets = mod.worker_targets ?? mod['worker-targets'] ?? mod.workerTargets; + return { key: key || mod.name, url: mod.repository || mod.url, moduleDefinition: mod.module_definition || mod['module-definition'], + sourceRoot: mod.source_root || mod['source-root'] || mod.sourceRoot || null, code: mod.code, name: mod.display_name || mod.name, description: mod.description || '', defaultSelected: mod.default_selected === true || mod.defaultSelected === true, type: mod.type || 'bmad-org', npmPackage: mod.npm_package || mod.npmPackage || null, + installTargets: normalizeStringList(installTargets), + workerTargets: normalizeStringList(workerTargets), + requirements: normalizeStringList(mod.requirements), + installNote: mod.install_note || mod['install-note'] || mod.installNote || null, defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable', builtIn: mod.built_in === true, isExternal: mod.built_in !== true, }; } + async _loadFallbackModules() { + try { + const content = await fs.readFile(FALLBACK_CONFIG_PATH, 'utf8'); + const config = yaml.parse(content); + if (Array.isArray(config.modules)) return config.modules.map((mod) => this._normalizeModule(mod)); + return Object.entries(config.modules || {}).map(([key, mod]) => this._normalizeModule(mod, key)); + } catch { + return []; + } + } + /** * Get list of available modules from the registry * @returns {Array} Array of module info objects @@ -145,7 +173,14 @@ class ExternalModuleManager { // Remote format: modules is an array if (Array.isArray(config.modules)) { - return config.modules.map((mod) => this._normalizeModule(mod)); + const modules = config.modules.map((mod) => this._normalizeModule(mod)); + const seenCodes = new Set(modules.map((mod) => mod.code)); + for (const fallbackMod of await this._loadFallbackModules()) { + if (!seenCodes.has(fallbackMod.code)) { + modules.push(fallbackMod); + } + } + return modules; } // Legacy bundled format: modules is an object map @@ -489,6 +524,19 @@ class ExternalModuleManager { // Clone the external module repo const cloneDir = await this.cloneExternalModule(moduleCode, options); + if (moduleInfo.sourceRoot) { + const repoRoot = path.resolve(cloneDir); + const sourceRoot = path.resolve(repoRoot, moduleInfo.sourceRoot); + const relativeSourceRoot = path.relative(repoRoot, sourceRoot); + if (relativeSourceRoot === '..' || relativeSourceRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeSourceRoot)) { + throw new Error(`External module '${moduleCode}' source-root escapes repository: ${moduleInfo.sourceRoot}`); + } + if (!(await fs.pathExists(sourceRoot))) { + throw new Error(`External module '${moduleCode}' source-root not found: ${moduleInfo.sourceRoot}`); + } + return sourceRoot; + } + // The module-definition specifies the path to module.yaml relative to repo root // We need to return the directory containing module.yaml const moduleDefinitionPath = moduleInfo.moduleDefinition; // e.g., 'skills/module.yaml' diff --git a/tools/installer/modules/registry-fallback.yaml b/tools/installer/modules/registry-fallback.yaml index 52bc4b4fc0..f9ad2e5643 100644 --- a/tools/installer/modules/registry-fallback.yaml +++ b/tools/installer/modules/registry-fallback.yaml @@ -50,3 +50,25 @@ modules: type: bmad-org npmPackage: bmad-method-test-architecture-enterprise default_channel: stable + + bmad-automator: + url: https://github.com/bmad-code-org/bmad-automator + source-root: payload/.claude/skills + code: bma + name: "BMad Automator (Experimental)" + description: "Experimental pure-skill story automation. Runs only from Claude Code; supports Claude Code and Codex worker sessions; requires tmux on macOS." + defaultSelected: false + type: experimental + npmPackage: bmad-story-automator + default_channel: stable + install-targets: + - claude-code + worker-targets: + - claude-code + - codex + requirements: + - Claude Code entrypoint + - Claude Code or Codex worker sessions + - tmux + - macOS + install-note: "Experimental: BMad Automator only works from Claude Code. It currently supports Claude Code and Codex worker sessions, and requires tmux on macOS." diff --git a/tools/installer/ui.js b/tools/installer/ui.js index 5770206ef6..8dd6be3cb3 100644 --- a/tools/installer/ui.js +++ b/tools/installer/ui.js @@ -259,6 +259,7 @@ class UI { } else { selectedModules = await this.selectAllModules(installedModuleIds, installedModuleVersions, channelOptions); } + await this.showSelectedExternalModuleNotes(selectedModules); // Resolve custom sources from --custom-source flag if (options.customSource) { @@ -287,6 +288,7 @@ class UI { // Get tool selection const toolSelection = await this.promptToolSelection(confirmedDirectory, options); + await this.showSelectedModuleIdeWarnings(selectedModules, toolSelection.ides); const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, { ...options, @@ -343,6 +345,7 @@ class UI { } else { selectedModules = await this.selectAllModules(installedModuleIds, installedModuleVersions, channelOptions); } + await this.showSelectedExternalModuleNotes(selectedModules); // Resolve custom sources from --custom-source flag if (options.customSource) { @@ -366,6 +369,7 @@ class UI { await this._interactiveChannelGate({ options, channelOptions, selectedModules }); let toolSelection = await this.promptToolSelection(confirmedDirectory, options); + await this.showSelectedModuleIdeWarnings(selectedModules, toolSelection.ides); const { moduleConfigs, setOverrides } = await this.collectModuleConfigs(confirmedDirectory, selectedModules, { ...options, channelOptions, @@ -954,6 +958,41 @@ class UI { return result; } + async showSelectedExternalModuleNotes(selectedModuleIds, externalModules = null) { + if (!externalModules) { + const externalManager = new ExternalModuleManager(); + externalModules = await externalManager.listAvailable(); + } + + const notes = externalModules + .filter((mod) => selectedModuleIds.includes(mod.code) && mod.installNote) + .map((mod) => `${mod.name}: ${mod.installNote}`); + + for (const note of notes) { + await prompts.log.warn(note); + } + } + + async showSelectedModuleIdeWarnings(selectedModuleIds, selectedIdes = []) { + const externalManager = new ExternalModuleManager(); + const externalModules = await externalManager.listAvailable(); + + for (const mod of externalModules) { + if (!selectedModuleIds.includes(mod.code) || !mod.installTargets || mod.installTargets.length === 0) { + continue; + } + + const hasInstallTarget = mod.installTargets.some((target) => selectedIdes.includes(target)); + if (!hasInstallTarget) { + await prompts.log.warn( + `${mod.name}: runnable skills are installed only for ${mod.installTargets.join( + ', ', + )}. Add that tool selection to use this module.`, + ); + } + } + } + /** * Browse and select community modules using category drill-down. * Featured/promoted modules appear at the top.