bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/src/modules/bmb/workflows/module/data/module-installer-standards.md

@@ -0,0 +1,348 @@
+# Module Installer Standards
+
+**Purpose:** How the `_module-installer` folder works, including installer.js patterns and platform-specific configuration.
+
+---
+
+## Overview
+
+The `_module-installer` folder contains optional installation logic for your module. It runs AFTER the IDE installations and can:
+- Create directories specified in module.yaml
+- Copy assets or templates
+- Configure IDE-specific settings
+- Set up platform-specific integrations
+
+---
+
+## When Do You Need an Installer?
+
+### Use an Installer When:
+
+- Creating directories based on user configuration
+- Copying template files to the user's project
+- IDE-specific setup (Claude Code, Windsurf, Cursor, etc.)
+- Platform-specific integrations
+
+### Skip the Installer When:
+
+- Module only provides agents and workflows
+- No file operations needed
+- No IDE-specific configuration
+
+---
+
+## Folder Structure
+
+```
+_module-installer/
+├── installer.js                 # Main installer (REQUIRED if folder exists)
+└── platform-specifics/          # IDE-specific handlers (optional)
+    ├── claude-code.js
+    ├── windsurf.js
+    ├── cursor.js
+    └── ...
+```
+
+---
+
+## installer.js Pattern
+
+### Function Signature
+
+```javascript
+/**
+ * Module Installer
+ *
+ * @param {Object} options - Installation options
+ * @param {string} options.projectRoot - The root directory of the target project
+ * @param {Object} options.config - Module configuration from module.yaml (resolved variables)
+ * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
+ * @param {Object} options.logger - Logger instance for output
+ * @returns {Promise<boolean>} - Success status (true = success, false = failure)
+ */
+async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+
+  try {
+    // Installation logic here
+    logger.log(chalk.blue('Installing {Module Name}...'));
+
+    // ... your logic ...
+
+    logger.log(chalk.green('✓ {Module Name} installation complete'));
+    return true;
+  } catch (error) {
+    logger.error(chalk.red(`Error installing module: ${error.message}`));
+    return false;
+  }
+}
+
+module.exports = { install };
+```
+
+---
+
+### What You Receive
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `projectRoot` | string | Absolute path to the user's project root |
+| `config` | object | Resolved module.yaml variables |
+| `installedIDEs` | array | List of IDE codes installed (e.g., `['claude-code', 'windsurf']`) |
+| `logger` | object | Logger with `.log()`, `.warn()`, `.error()` methods |
+
+The `config` object contains your module.yaml variables **after** user input:
+
+```javascript
+// If module.yaml defined:
+// project_name:
+//   prompt: "What is your project name?"
+//   result: "{value}"
+
+config.project_name  // = user's input
+config.planning_artifacts  // = resolved path
+```
+
+---
+
+## Common Installation Tasks
+
+### 1. Create Directories
+
+```javascript
+const fs = require('fs-extra');
+const path = require('node:path');
+
+// Create directory from config
+if (config['planning_artifacts']) {
+  const dirConfig = config['planning_artifacts'].replace('{project-root}/', '');
+  const dirPath = path.join(projectRoot, dirConfig);
+
+  if (!(await fs.pathExists(dirPath))) {
+    logger.log(chalk.yellow(`Creating directory: ${dirConfig}`));
+    await fs.ensureDir(dirPath);
+  }
+}
+```
+
+### 2. Copy Assets
+
+```javascript
+const assetsSource = path.join(__dirname, 'assets');
+const assetsDest = path.join(projectRoot, 'docs');
+
+if (await fs.pathExists(assetsSource)) {
+  await fs.copy(assetsSource, assetsDest);
+  logger.log(chalk.green('✓ Copied assets to docs/'));
+}
+```
+
+### 3. IDE-Specific Configuration
+
+```javascript
+// Handle IDE-specific configurations
+if (installedIDEs && installedIDEs.length > 0) {
+  logger.log(chalk.cyan(`Configuring for IDEs: ${installedIDEs.join(', ')}`));
+
+  for (const ide of installedIDEs) {
+    await configureForIDE(ide, projectRoot, config, logger);
+  }
+}
+```
+
+---
+
+## Platform-Specific Handlers
+
+### Pattern
+
+Create files in `platform-specifics/{ide-code}.js`:
+
+```javascript
+// platform-specifics/claude-code.js
+
+/**
+ * Configure module for Claude Code
+ */
+async function install(options) {
+  const { projectRoot, config, logger, platformInfo } = options;
+
+  try {
+    // Claude Code specific configuration
+    logger.log(chalk.dim('  Configuring Claude Code integration...'));
+
+    // Your logic here
+
+    return true;
+  } catch (error) {
+    logger.warn(chalk.yellow(`  Warning: ${error.message}`));
+    return false;
+  }
+}
+
+module.exports = { install };
+```
+
+### Load from Main Installer
+
+```javascript
+// installer.js
+const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/platform-codes'));
+
+async function configureForIDE(ide, projectRoot, config, logger) {
+  // Validate platform code
+  if (!platformCodes.isValidPlatform(ide)) {
+    logger.warn(chalk.yellow(`  Unknown platform: '${ide}'. Skipping.`));
+    return;
+  }
+
+  const platformName = platformCodes.getDisplayName(ide);
+  const platformSpecificPath = path.join(__dirname, 'platform-specifics', `${ide}.js`);
+
+  try {
+    if (await fs.pathExists(platformSpecificPath)) {
+      const platformHandler = require(platformSpecificPath);
+
+      if (typeof platformHandler.install === 'function') {
+        await platformHandler.install({ projectRoot, config, logger });
+        logger.log(chalk.green(`  ✓ Configured for ${platformName}`));
+      }
+    }
+  } catch (error) {
+    logger.warn(chalk.yellow(`  Warning: Could not configure ${platformName}: ${error.message}`));
+  }
+}
+```
+
+---
+
+## Complete Example: BMM Installer
+
+```javascript
+const fs = require('fs-extra');
+const path = require('node:path');
+const chalk = require('chalk');
+const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/platform-codes'));
+
+/**
+ * BMM Module Installer
+ */
+async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+
+  try {
+    logger.log(chalk.blue('🚀 Installing BMM Module...'));
+
+    // Create output directory
+    if (config['output_folder']) {
+      const outputConfig = config['output_folder'].replace('{project-root}/', '');
+      const outputPath = path.join(projectRoot, outputConfig);
+      if (!(await fs.pathExists(outputPath))) {
+        logger.log(chalk.yellow(`Creating output directory: ${outputConfig}`));
+        await fs.ensureDir(outputPath);
+      }
+    }
+
+    // Create implementation artifacts directory
+    if (config['implementation_artifacts']) {
+      const storyConfig = config['implementation_artifacts'].replace('{project-root}/', '');
+      const storyPath = path.join(projectRoot, storyConfig);
+      if (!(await fs.pathExists(storyPath))) {
+        logger.log(chalk.yellow(`Creating story directory: ${storyConfig}`));
+        await fs.ensureDir(storyPath);
+      }
+    }
+
+    // IDE-specific configuration
+    if (installedIDEs && installedIDEs.length > 0) {
+      logger.log(chalk.cyan(`Configuring BMM for IDEs: ${installedIDEs.join(', ')}`));
+
+      for (const ide of installedIDEs) {
+        await configureForIDE(ide, projectRoot, config, logger);
+      }
+    }
+
+    logger.log(chalk.green('✓ BMM Module installation complete'));
+    return true;
+  } catch (error) {
+    logger.error(chalk.red(`Error installing BMM: ${error.message}`));
+    return false;
+  }
+}
+
+async function configureForIDE(ide, projectRoot, config, logger) {
+  if (!platformCodes.isValidPlatform(ide)) {
+    logger.warn(chalk.yellow(`  Warning: Unknown platform '${ide}'. Skipping.`));
+    return;
+  }
+
+  const platformSpecificPath = path.join(__dirname, 'platform-specifics', `${ide}.js`);
+
+  try {
+    if (await fs.pathExists(platformSpecificPath)) {
+      const platformHandler = require(platformSpecificPath);
+
+      if (typeof platformHandler.install === 'function') {
+        await platformHandler.install({ projectRoot, config, logger });
+      }
+    }
+  } catch (error) {
+    logger.warn(chalk.yellow(`  Warning: Could not load handler for ${ide}: ${error.message}`));
+  }
+}
+
+module.exports = { install };
+```
+
+---
+
+## Best Practices
+
+### DO:
+- Return `true` for success, `false` for failure
+- Use chalk for colored output
+- Log what you're doing (create, copy, configure)
+- Handle errors gracefully with try/catch
+- Validate paths before creating directories
+
+### DON'T:
+- Assume paths exist — check with `fs.pathExists()`
+- Overwrite user files without asking
+- Fail silently — log errors
+- Use absolute paths — build from `projectRoot`
+
+---
+
+## Available Platform Codes
+
+Common IDE codes:
+- `claude-code` — Anthropic's Claude Code
+- `windsurf` — Windsurf IDE
+- `cursor` — Cursor AI IDE
+- `vscode` — Visual Studio Code
+
+Use `platformCodes.isValidPlatform(ide)` to validate.
+
+---
+
+## Testing Your Installer
+
+1. Create a test project
+2. Run `bmad install {your-module}`
+3. Verify directories are created
+4. Check that config variables are resolved correctly
+5. Test platform-specific handlers
+
+---
+
+## Quick Reference
+
+| Task | Code Pattern |
+|------|--------------|
+| Create directory | `await fs.ensureDir(path)` |
+| Check if exists | `await fs.pathExists(path)` |
+| Copy files | `await fs.copy(src, dest)` |
+| Log info | `logger.log(chalk.blue('message'))` |
+| Log success | `logger.log(chalk.green('✓ message'))` |
+| Log warning | `logger.warn(chalk.yellow('warning'))` |
+| Log error | `logger.error(chalk.red('error'))` |

package/src/modules/bmb/workflows/module/data/module-standards.md

@@ -0,0 +1,280 @@
+# Module Standards
+
+**Purpose:** Defines what a BMAD module is, its structure, and the three types of modules.
+
+---
+
+## What is a BMAD Module?
+
+A **BMAD module** is a self-contained package of functionality that extends the BMAD framework. Modules provide:
+- **Agents** — AI personas with specialized expertise and menu-driven commands
+- **Workflows** — Structured processes for accomplishing complex tasks
+- **Configuration** — module.yaml for user customization
+- **Installation** — Optional installer.js for setup logic
+
+---
+
+## Module Types
+
+### 1. Standalone Module
+
+A new, independent module focused on a specific domain.
+
+**Characteristics:**
+- Own module code (e.g., `healthcare-ai`, `legal-assist`)
+- Independent of other modules
+- Can be installed alongside any other modules
+- Has its own agents, workflows, configuration
+
+**Location:** `src/modules/{module-code}/`
+
+**Example:** CIS (Creative Innovation Suite) — a standalone module for innovation workflows
+
+---
+
+### 2. Extension Module
+
+Extends an existing BMAD module with additional functionality.
+
+**Characteristics:**
+- Builds upon an existing module's agents and workflows
+- May add new agents or workflows that complement the base module
+- Shares configuration context with the extended module
+- Typically installed alongside the module it extends
+
+**Location:** `src/modules/{base-module}/extensions/{extension-code}/`
+
+**Example:** An extension to BMM that adds specialized security review workflows
+
+---
+
+### Extension Module: Override & Merge Pattern
+
+When an extension module is installed, its files merge with the base module following these rules:
+
+#### Code Matching
+
+The extension's `module.yaml` `code:` field matches the base module's code:
+
+```yaml
+# Base module: src/modules/bmm/module.yaml
+code: bmm
+
+# Extension: src/modules/bmm/extensions/security/module.yaml
+code: bmm  # SAME CODE — extends BMM
+```
+
+The **folder name** is unique (e.g., `bmm-security`) but the `code:` matches the base module.
+
+#### File Merge Rules
+
+| File Type | Same Name | Different Name |
+|-----------|-----------|----------------|
+| Agent file | **OVERRIDE** — replaces the base agent | **ADD** — new agent added |
+| Workflow folder | **OVERRIDE** — replaces the base workflow | **ADD** — new workflow added |
+| Other files | **OVERRIDE** — replaces base file | **ADD** — new file added |
+
+#### Examples
+
+**Override scenario:**
+```
+Base module (BMM):
+├── agents/
+│   └── pm.agent.yaml          # Original PM agent
+
+Extension (bmm-security):
+├── agents/
+│   └── pm.agent.yaml          # Security-focused PM — REPLACES original
+
+Result after installation:
+├── agents/
+│   └── pm.agent.yaml          # Now the security version
+```
+
+**Add scenario:**
+```
+Base module (BMM):
+├── agents/
+│   ├── pm.agent.yaml
+│   └── architect.agent.yaml
+
+Extension (bmm-security):
+├── agents/
+│   └── security-auditor.agent.yaml  # NEW agent
+
+Result after installation:
+├── agents/
+│   ├── pm.agent.yaml
+│   ├── architect.agent.yaml
+│   └── security-auditor.agent.yaml  # ADDED
+```
+
+**Mixed scenario:**
+```
+Extension contains both overrides and new files — applies rules per file
+```
+
+---
+
+### 3. Global Module
+
+Affects the entire BMAD framework and all modules.
+
+**Characteristics:**
+- Core functionality that impacts all modules
+- Often provides foundational services or utilities
+- Installed at the framework level
+- Use sparingly — only for truly global concerns
+
+**Location:** `src/modules/{module-code}/` with `global: true` in module.yaml
+
+**Example:** A module that provides universal logging or telemetry across BMAD
+
+---
+
+## Required Module Structure
+
+```
+{module-code}/
+├── module.yaml                 # Module configuration (REQUIRED)
+├── README.md                   # Module documentation (REQUIRED)
+├── agents/                     # Agent definitions (if any)
+│   └── {agent-name}.agent.yaml
+├── workflows/                  # Workflow definitions (if any)
+│   └── {workflow-name}/
+│       └── workflow.md
+├── _module-installer/          # Installation logic (optional)
+│   ├── installer.js
+│   └── platform-specifics/
+│       ├── claude-code.js
+│       ├── windsurf.js
+│       └── ...
+└── {other folders}             # Tasks, templates, data as needed
+```
+
+---
+
+## Required Files
+
+### module.yaml (REQUIRED)
+
+Every module MUST have a `module.yaml` file with at minimum:
+
+```yaml
+code: {module-code}
+name: "Module Display Name"
+header: "Brief module description"
+subheader: "Additional context"
+default_selected: false
+```
+
+See: `module-yaml-conventions.md` for full specification.
+
+---
+
+### README.md (REQUIRED)
+
+Every module MUST have a README.md with:
+- Module name and purpose
+- Installation instructions
+- Components section (agents, workflows)
+- Quick start guide
+- Module structure diagram
+- Configuration section
+- Usage examples
+- Author information
+
+---
+
+## Optional Components
+
+### Agents
+
+Agents are AI personas with:
+- Metadata (id, name, title, icon, module)
+- Persona (role, identity, communication_style, principles)
+- Menu (trigger → workflow/exec mappings)
+
+See: `agent-architecture.md` for design guidance.
+
+---
+
+### Workflows
+
+Workflows are structured processes with:
+- workflow.md (entry point)
+- steps/ folder with step files
+- data/ folder with shared reference
+- templates/ folder if needed
+
+---
+
+### _module-installer/
+
+Optional installation logic for:
+- Creating directories
+- Copying assets
+- IDE-specific configuration
+- Platform-specific setup
+
+See: `module-installer-standards.md` for patterns.
+
+---
+
+## Module Type Decision Tree
+
+```
+START: Creating a module
+│
+├─ Is this a brand new independent domain?
+│  └─ YES → Standalone Module
+│
+├─ Does this extend an existing module?
+│  └─ YES → Extension Module
+│
+└─ Does this affect all modules globally?
+   └─ YES → Global Module (use sparingly)
+```
+
+---
+
+## Naming Conventions
+
+### Module Code
+
+- **kebab-case** (e.g., `bmm`, `cis`, `bmgd`, `healthcare-ai`)
+- Short, memorable, descriptive
+- 2-20 characters
+- Lowercase letters, numbers, hyphens only
+
+### Agent Files
+
+- Format: `{role-name}.agent.yaml`
+- Example: `pm.agent.yaml`, `architect.agent.yaml`
+
+### Workflow Folders
+
+- Format: `{workflow-name}/`
+- Example: `prd/`, `create-architecture/`
+
+---
+
+## Module Dependencies
+
+Modules can depend on:
+- **Core BMAD** — Always available
+- **Other modules** — Specify in module.yaml as `dependencies:`
+- **External tools** — Document in README, handle in installer
+
+---
+
+## Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| What's a module? | Self-contained package of agents, workflows, config |
+| What are the types? | Standalone, Extension, Global |
+| What's required? | module.yaml, README.md |
+| Where do modules live? | `src/modules/{code}/` |
+| How do agents work? | Menu triggers → workflow/exec |
+| How does installation work? | module.yaml prompts + optional installer.js |