bmad-method 5.1.3 → 6.0.0-alpha.1

package/docs/v4-to-v6-upgrade.md

@@ -0,0 +1,225 @@
+# BMad v4 to v6 Upgrade Guide
+
+## Overview
+
+BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
+
+---
+
+## Automatic V4 Detection
+
+When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects:
+
+- **Legacy folders**: Any folders starting with `.bmad`, `bmad` (lowercase), or `Bmad`
+- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
+
+### What Happens During Detection
+
+1. **Automatic Backup of v4 Modules**: All `.bmad-*` folders are moved to `v4-backup/` in your project root
+   - If a backup already exists, a timestamp is added to avoid conflicts
+   - Example: `.bmad-core` → `v4-backup/.bmad-core`
+   - Your project files and data are NOT affected
+
+2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
+   - Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc.
+   - These old commands would still reference v4 folder structure if left in place
+   - The installer provides copy/paste terminal commands for your platform
+   - You can proceed without cleanup, but removing them prevents confusion with old v4 commands
+
+---
+
+## Module Migration
+
+### Deprecated Modules
+
+| v4 Module                     | v6 Status                                        |
+| ----------------------------- | ------------------------------------------------ |
+| `.bmad-2d-phaser-game-dev`    | Integrated into BMM                              |
+| `.bmad-2d-unity-game-dev`     | Integrated into BMM                              |
+| `.bmad-godot-game-dev`        | Integrated into BMM                              |
+| `.bmad-*-game-dev` (any)      | Integrated into BMM                              |
+| `.bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
+| `.bmad-creative-writing`      | Not adapted - New module releasing soon          |
+
+**Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.
+
+---
+
+## Architecture Changes
+
+### Folder Structure
+
+**v4 "Expansion Packs" Structure:**
+
+```
+your-project/
+├── .bmad-core/           # Was actually the BMad Method
+├── .bmad-game-dev/       # Separate expansion packs
+├── .bmad-creative-writing/
+└── .bmad-infrastructure-devops/
+```
+
+**v6 Unified Structure:**
+
+```
+your-project/
+└── bmad/                 # Single installation folder
+    ├── core/            # Real core framework (applies to all modules)
+    ├── bmm/             # BMad Method (software/game dev)
+    ├── bmb/             # BMad Builder (create agents/workflows)
+    ├── cis/             # Creative Intelligence Suite
+    └── _cfg/            # Your customizations
+        └── agents/      # Agent customization files
+```
+
+### Key Concept Changes
+
+- **v4 `.bmad-core`**: Was actually the BMad Method
+- **v6 `bmad/core/`**: Is the real universal core framework
+- **v6 `bmad/bmm/`**: Is the BMad Method module
+- **Module identification**: All modules now have a `config.yaml` file
+
+---
+
+## Project Progress Migration
+
+### If You've Completed Planning Phase (PRD/Architecture) with the BMad Method:
+
+After running the v6 installer:
+
+1. **Run `workflow-init`** workflow to set up the guided workflow system
+2. **Specify your project level** when prompted:
+   - If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4**
+   - This tells v6 you've already completed planning and solutioning phases
+3. **Document paths**: Keep your existing paths during installation
+   - Default PRD/Architecture location: `docs/`
+   - Default stories location: `docs/stories/`
+   - **Accept these defaults** if you're already using them in v4
+
+> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
+
+### If You're Mid-Development (Stories Created/Implemented)
+
+1. Complete the v6 installation as above
+2. Run `workflow-init` and specify Level 3 or 4
+3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4)
+
+---
+
+## Agent Customization Migration
+
+### v4 Agent Customization
+
+In v4, you may have modified agent files directly in `.bmad-*` folders.
+
+### v6 Agent Customization
+
+**All customizations** now go in `bmad/_cfg/agents/` using customize files:
+
+**Example: Renaming an agent and changing communication style**
+
+File: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+
+```yaml
+# Customize the PM agent
+persona:
+  name: 'Captain Jack' # Override agent name
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors for software concepts
+    - Always upbeat and adventurous
+```
+
+**How it works:**
+
+- Base agent: `bmad/bmm/agents/pm.md`
+- Customization: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+- Result: Agent uses your custom name and style, but updates don't overwrite your changes
+
+---
+
+## Document Compatibility
+
+### Sharded vs Unsharded Documents
+
+**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
+
+- ✅ Sharded documents (split into multiple files)
+- ✅ Unsharded documents (single file per section)
+- ✅ Custom sections for your project type
+- ✅ Mixed approaches
+
+All workflow files are scanned automatically. No manual configuration needed.
+
+---
+
+## Installation Steps
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/bmad-code-org/BMAD-METHOD
+cd BMAD-METHOD
+npm install
+```
+
+### 2. Run Installer on Your v4 Project
+
+```bash
+npx bmad-method install
+```
+
+**Enter the full path to your v4 project** when prompted.
+
+### 3. Follow Interactive Prompts
+
+The installer will:
+
+1. Detect v4 installation and offer to backup `.bmad-*` folders
+2. Prompt for recommended cleanup (you can skip)
+3. Let you select modules (recommend: BMM for software and or game development)
+4. Configure core settings (name, language, etc.)
+5. Configure module-specific options
+6. Configure IDE integrations
+
+### 4. Accept Default Paths
+
+If you're using:
+
+- `docs/` for PRD and architecture
+- `docs/stories/` for story files
+
+**Accept these defaults** during installation.
+
+### 5. Initialize Workflow
+
+After installation:
+
+```bash
+# In your project have the agent mode run workflow-init, in Claude Code:
+/workflow-init
+# or run the analyst and tell the analyst after it loads
+*workflow-init
+```
+
+Select **Level 3 or 4** if you've already completed PRD/architecture in v4.
+
+---
+
+## Post-Migration Checklist
+
+- [ ] v4 folders backed up to `v4-backup/`
+- [ ] v6 installed to `bmad/` folder
+- [ ] `workflow-init` run with correct project level selected
+- [ ] Agent customizations migrated to `bmad/_cfg/agents/` if needed
+- [ ] IDE integration working (test by listing agents)
+- [ ] For active development: `sprint-planning` workflow executed
+
+---
+
+## Getting Help
+
+- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
+- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- **Docs**: Check `bmad/docs/` in your installation for IDE-specific instructions

package/eslint.config.mjs

@@ -7,7 +7,16 @@ import yml from 'eslint-plugin-yml';
 export default [
   // Global ignores for files/folders that should not be linted
   {
-    ignores: ['dist/**', 'coverage/**', '**/*.min.js'],
+    ignores: [
+      'dist/**',
+      'coverage/**',
+      '**/*.min.js',
+      'test/template-test-generator/**',
+      'test/template-test-generator/**/*.js',
+      'test/template-test-generator/**/*.md',
+      'test/fixtures/**',
+      'test/fixtures/**/*.yaml',
+    ],
   },
 
   // Base JavaScript recommended rules
@@ -52,9 +61,9 @@ export default [
     },
   },
 
-  // CLI/CommonJS scripts under tools/**
+  // CLI/CommonJS scripts under tools/** and test/**
   {
-    files: ['tools/**/*.js'],
+    files: ['tools/**/*.js', 'test/**/*.js'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',
@@ -84,19 +93,22 @@ export default [
     },
   },
 
-  // ESLint config file should not be checked for publish-related Node rules
+  // Module installer scripts use CommonJS for compatibility
   {
-    files: ['eslint.config.mjs'],
+    files: ['**/_module-installer/**/*.js'],
     rules: {
-      'n/no-unpublished-import': 'off',
+      // Allow CommonJS patterns for installer scripts
+      'unicorn/prefer-module': 'off',
+      'n/no-missing-require': 'off',
+      'n/no-unpublished-require': 'off',
     },
   },
 
-  // YAML workflow templates allow empty mapping values intentionally
+  // ESLint config file should not be checked for publish-related Node rules
   {
-    files: ['bmad-core/workflows/**/*.yaml'],
+    files: ['eslint.config.mjs'],
     rules: {
-      'yml/no-empty-mapping-value': 'off',
+      'n/no-unpublished-import': 'off',
     },
   },
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "5.1.3",
+  "version": "6.0.0-alpha.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -14,75 +14,70 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bmadcode/BMAD-METHOD.git"
+    "url": "git+https://github.com/bmad-code-org/BMAD-METHOD.git"
   },
   "license": "MIT",
   "author": "Brian (BMad) Madison",
-  "main": "tools/cli.js",
+  "main": "tools/cli/bmad-cli.js",
   "bin": {
     "bmad": "tools/bmad-npx-wrapper.js",
     "bmad-method": "tools/bmad-npx-wrapper.js"
   },
   "scripts": {
-    "build": "node tools/cli.js build",
-    "build:agents": "node tools/cli.js build --agents-only",
-    "build:teams": "node tools/cli.js build --teams-only",
+    "bmad:install": "node tools/cli/bmad-cli.js install",
+    "bmad:status": "node tools/cli/bmad-cli.js status",
+    "bundle": "node tools/cli/bundlers/bundle-web.js all",
     "flatten": "node tools/flattener/main.js",
-    "format": "prettier --write \"**/*.{js,cjs,mjs,json,md,yaml}\"",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,md,yaml}\"",
-    "install:bmad": "node tools/installer/bin/bmad.js install",
+    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,md,yaml}\"",
+    "install:bmad": "node tools/cli/bmad-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
-    "list:agents": "node tools/cli.js list:agents",
     "prepare": "husky",
-    "preview:release": "node tools/preview-release-notes.js",
+    "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
     "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
     "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
     "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
     "release:watch": "gh run watch",
-    "validate": "node tools/cli.js validate",
-    "version:all": "node tools/bump-all-versions.js",
-    "version:all:major": "node tools/bump-all-versions.js major",
-    "version:all:minor": "node tools/bump-all-versions.js minor",
-    "version:all:patch": "node tools/bump-all-versions.js patch",
-    "version:expansion": "node tools/bump-expansion-version.js",
-    "version:expansion:all": "node tools/bump-all-versions.js",
-    "version:expansion:all:major": "node tools/bump-all-versions.js major",
-    "version:expansion:all:minor": "node tools/bump-all-versions.js minor",
-    "version:expansion:all:patch": "node tools/bump-all-versions.js patch",
-    "version:expansion:set": "node tools/update-expansion-version.js",
-    "version:major": "node tools/version-bump.js major",
-    "version:minor": "node tools/version-bump.js minor",
-    "version:patch": "node tools/version-bump.js patch"
+    "test": "node test/test-agent-schema.js",
+    "test:coverage": "c8 --reporter=text --reporter=html node test/test-agent-schema.js",
+    "validate:bundles": "node tools/validate-bundles.js",
+    "validate:schemas": "node tools/validate-agent-schema.js"
   },
   "lint-staged": {
-    "**/*.{js,cjs,mjs}": [
-      "eslint --fix --max-warnings=0",
-      "prettier --write"
+    "*.{js,cjs,mjs}": [
+      "npm run lint:fix",
+      "npm run format:fix"
     ],
-    "**/*.yaml": [
+    "*.yaml": [
       "eslint --fix",
-      "prettier --write"
+      "npm run format:fix"
     ],
-    "**/*.{json,md}": [
-      "prettier --write"
+    "*.{json,md}": [
+      "npm run format:fix"
     ]
   },
   "dependencies": {
-    "@kayvan/markdown-tree-parser": "^1.5.0",
-    "bmad-method": "^4.30.3",
+    "@kayvan/markdown-tree-parser": "^1.6.1",
+    "boxen": "^5.1.2",
     "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
     "commander": "^14.0.0",
+    "csv-parse": "^6.1.0",
+    "figlet": "^1.8.0",
     "fs-extra": "^11.3.0",
     "glob": "^11.0.3",
     "ignore": "^7.0.5",
     "inquirer": "^8.2.6",
     "js-yaml": "^4.1.0",
     "ora": "^5.4.1",
-    "semver": "^7.6.3"
+    "semver": "^7.6.3",
+    "wrap-ansi": "^7.0.0",
+    "xml2js": "^0.6.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
+    "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^17.21.3",
@@ -94,10 +89,11 @@
     "prettier": "^3.5.3",
     "prettier-plugin-packagejson": "^2.5.19",
     "yaml-eslint-parser": "^1.2.3",
-    "yaml-lint": "^1.7.0"
+    "yaml-lint": "^1.7.0",
+    "zod": "^4.1.12"
   },
   "engines": {
-    "node": ">=20.10.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"

package/prettier.config.mjs

@@ -1,6 +1,6 @@
 export default {
   $schema: 'https://json.schemastore.org/prettierrc',
-  printWidth: 100,
+  printWidth: 140,
   tabWidth: 2,
   useTabs: false,
   semi: true,

package/src/core/_module-installer/install-config.yaml

@@ -0,0 +1,28 @@
+# BMAD™ Core Configuration
+
+prompt:
+  - "Welcome and thank you for choosing BMAD™! This is the Core Configuration."
+  - "This will impact all selected modules, either additions or upgrades."
+
+# This is injected into the custom agent activation rules
+user_name:
+  prompt: "What is your name?"
+  default: "BMad"
+  result: "{value}"
+
+# This is injected into the custom agent activation rules and most workflows
+communication_language:
+  prompt: "Preferred Chat Language?"
+  default: "English"
+  result: "{value}"
+
+document_output_language:
+  prompt: "Preferred Document Output Language?"
+  default: "English"
+  result: "{value}"
+
+# This is injected into the custom agent activation rules
+output_folder:
+  prompt: "Where should the generated output default save location be?"
+  default: "docs"
+  result: "{project-root}/{value}"

package/src/core/_module-installer/installer.js

@@ -0,0 +1,68 @@
+const chalk = require('chalk');
+
+/**
+ * Core Module Installer
+ * Standard module installer function that executes after IDE installations
+ *
+ * @param {Object} options - Installation options
+ * @param {string} options.projectRoot - The root directory of the target project
+ * @param {Object} options.config - Module configuration from install-config.yaml
+ * @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
+ */
+async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+
+  try {
+    logger.log(chalk.blue('🏗️  Installing Core Module...'));
+
+    // Core agent configs are created by the main installer's createAgentConfigs method
+    // No need to create them here - they'll be handled along with all other agents
+
+    // Handle IDE-specific configurations if needed
+    if (installedIDEs && installedIDEs.length > 0) {
+      logger.log(chalk.cyan(`Configuring Core for IDEs: ${installedIDEs.join(', ')}`));
+
+      // Add any IDE-specific Core configurations here
+      for (const ide of installedIDEs) {
+        await configureForIDE(ide, projectRoot, config, logger);
+      }
+    }
+
+    logger.log(chalk.green('✓ Core Module installation complete'));
+    return true;
+  } catch (error) {
+    logger.error(chalk.red(`Error installing Core module: ${error.message}`));
+    return false;
+  }
+}
+
+/**
+ * Configure Core module for specific IDE
+ * @private
+ */
+async function configureForIDE(ide) {
+  // Add IDE-specific configurations here
+  switch (ide) {
+    case 'claude-code': {
+      // Claude Code specific Core configurations
+      break;
+    }
+    case 'cursor': {
+      // Cursor specific Core configurations
+      break;
+    }
+    case 'windsurf': {
+      // Windsurf specific Core configurations
+      break;
+    }
+    // Add more IDEs as needed
+    default: {
+      // No specific configuration needed
+      break;
+    }
+  }
+}
+
+module.exports = { install };

package/src/core/agents/bmad-master.agent.yaml

@@ -0,0 +1,39 @@
+# BMad Master Task Executor Agent
+# Core system agent for task execution and resource management
+
+agent:
+  metadata:
+    id: "bmad/core/agents/bmad-master.md"
+    name: "BMad Master"
+    title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
+    icon: "🧙"
+
+  persona:
+    role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
+    identity: "Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations."
+    communication_style: "Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability."
+    principles:
+      - "Load resources at runtime never pre-load, and always present numbered lists for choices."
+
+  # Agent-specific critical actions
+  critical_actions:
+    - "Load into memory {project-root}/bmad/core/config.yaml and set variable project_name, output_folder, user_name, communication_language"
+    - "Remember the users name is {user_name}"
+    - "ALWAYS communicate in {communication_language}"
+
+  # Agent menu items
+  menu:
+    - trigger: "list-tasks"
+      action: "list all tasks from {project-root}/bmad/_cfg/task-manifest.csv"
+      description: "List Available Tasks"
+
+    - trigger: "list-workflows"
+      action: "list all workflows from {project-root}/bmad/_cfg/workflow-manifest.csv"
+      description: "List Workflows"
+
+    - trigger: "party-mode"
+      workflow: "{project-root}/bmad/core/workflows/party-mode/workflow.yaml"
+      description: "Group chat with all agents"
+
+  # Empty prompts section (no custom prompts for this agent)
+  prompts: []