From ece3eefd13e1f23349a85247c711226badb4d172 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 18 Nov 2025 23:16:23 -0600 Subject: [PATCH] docs: Update CHANGELOG and README for v6.0.0-alpha.11 release - Comprehensive alpha.11 changelog capturing all major features - Condensed earlier alpha releases (0-10) to 5 key bullets each - Reduced changelog from 1,744 to 609 lines for better readability - Updated README status badges and installation instructions --- CHANGELOG.md | 1380 +++++++++----------------------------------------- README.md | 500 +++++------------- 2 files changed, 372 insertions(+), 1508 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a8275f5..92d08900 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,1229 +2,335 @@ ## [Unreleased] -## [6.0.0-alpha.10] +## [6.0.0-alpha.11] -**Release: November 16, 2025** +**Release: November 18, 2025** -This alpha release introduces a new specialized agent for visual diagramming, major epic creation workflow improvements, platform-specific filtering capabilities, and critical time estimate prohibition guidance across all workflows. +This alpha release introduces a complete agent installation system with the new `bmad agent-install` command, vastly improves the BMB agent builder capabilities with comprehensive documentation and reference agents, and refines diagram distribution to better align with BMad Method's core principle: **BMad agents mirror real agile teams**. -### ๐ŸŽฏ MAJOR MILESTONE: Epics & Stories Now Generated AFTER Architecture +### ๐ŸŽจ Diagram Capabilities Refined and Distributed -**A Key v6 Goal Realized!** +**Excalidraw Integration Evolution:** -One of the most important goals for BMad Method v6 has been achieved: **epic and story generation now occurs AFTER architecture completion** in the full BMad Method flow. +Building on the excellent Excalidraw integration introduced with the Frame Expert agent, we've refined how diagram capabilities are distributed across the BMad Method ecosystem to better reflect real agile team dynamics. -**Why This Matters:** +**The Refinement:** -- Stories are now **technically informed** - they reference actual architectural decisions, patterns, and constraints -- No more architectural surprises mid-implementation - stories already account for the chosen tech stack -- Better story estimation (complexity-based, not time-based) because technical approach is known -- Acceptance criteria can reference specific architectural patterns and integration points -- Reduces story rewrites that previously occurred when architecture revealed new complexity +- The valuable Excalidraw diagramming capabilities have been distributed to the agents who naturally create these artifacts in real teams +- **Architect**: System architecture diagrams, data flow visualizations +- **Product Manager**: Process flowcharts and workflow diagrams +- **UX Designer**: Wireframe creation capabilities +- **Tech Writer**: All diagram types for documentation needs +- **New CIS Agent**: presentation-master for specialized visual communication -**Workflow Sequence (Full BMad Method):** +**Shared Infrastructure Enhancement:** + +- Excalidraw templates, component libraries, and validation patterns elevated to core resources +- Available to both BMM agents AND CIS presentation specialists +- Preserves all the excellent Excalidraw functionality while aligning with natural team roles + +### ๐Ÿš€ New Agent Installation System + +**Agent Installation Infrastructure (NEW in alpha.11):** + +- `bmad agent-install` CLI command with interactive persona customization +- **YAML โ†’ XML compilation engine** with smart handler injection +- Supports Simple (single file), Expert (with sidecars), and Module agents +- Handlebars-style template variable processing +- Automatic manifest tracking and IDE integration +- Source preservation in `_cfg/custom/agents/` for reinstallation + +**New Reference Agents Added:** + +- **commit-poet**: Poetic git commit message generator (Simple agent example) +- **journal-keeper**: Daily journaling agent with templates (Expert agent example) +- **security-engineer & trend-analyst**: Module agent examples with ecosystem integration + +**Critical Persona Field Guidance Added:** + +New documentation explaining how LLMs interpret persona fields for better agent quality: + +- **role** โ†’ "What knowledge, skills, and capabilities do I possess?" +- **identity** โ†’ "What background, experience, and context shape my responses?" +- **communication_style** โ†’ "What verbal patterns, word choice, and phrasing do I use?" +- **principles** โ†’ "What beliefs and operating philosophy drive my choices?" + +Key insight: `communication_style` should ONLY describe HOW the agent talks, not WHAT they do + +**BMM Agent Voice Enhancement:** + +All 9 existing BMM agents enhanced with distinct, memorable communication voices: + +- **Mary (analyst)**: "Treats analysis like a treasure hunt - excited by every clue" +- **John (PM)**: "Asks 'WHY?' relentlessly like a detective on a case" +- **Winston (architect)**: "Champions boring technology that actually works" +- **Amelia (dev)**: "Ultra-succinct. Speaks in file paths and AC IDs" +- **Sally (UX)**: "Paints pictures with words, telling user stories that make you FEEL" + +### ๐Ÿ”ง Edit-Agent Workflow Comprehensive Enhancement + +**Expert Agent Sidecar Support (NEW):** + +- Automatically detects and handles Expert agents with multiple files +- Loads and manages templates, data files, knowledge bases +- Smart sidecar analysis: maps references, finds orphans, validates paths +- 5 complete sidecar editing patterns with warm, educational feedback + +**7-Step Communication Style Refinement Pattern:** + +1. Diagnose current style with red flag word detection +2. Extract non-style content to working copy +3. Discover TRUE communication style through interview questions +4. Craft pure style using presets and reference agents +5. Show before/after transformation with full context +6. Validate against standards (zero red flags) +7. Confirm with user through dramatic reading + +**Unified Validation Checklist:** + +- Single source of truth: `agent-validation-checklist.md` (160 lines) +- Shared between create-agent and edit-agent workflows +- Comprehensive persona field separation validation +- Expert agent sidecar validation (9 specific checks) +- Common issues and fixes with real examples + +### ๐Ÿ“š BMB Agent Builder Enhancement + +**Vastly Improved Agent Creation & Editing Capabilities:** + +- Create-agent and edit-agent workflows now have accurate, comprehensive documentation +- All context references updated and validated for consistency +- Workflows can now properly guide users through complex agent design decisions + +**New Agent Documentation Suite:** + +- `understanding-agent-types.md` - Architecture vs capability distinction +- `simple-agent-architecture.md` - Self-contained agents guide +- `expert-agent-architecture.md` - Agents with sidecar files +- `module-agent-architecture.md` - Workflow-integrated agents +- `agent-compilation.md` - YAML โ†’ XML transformation process +- `agent-menu-patterns.md` - Menu design patterns +- `communication-presets.csv` - 60 pure communication styles for reference + +**New Reference Agents for Learning:** + +- Complete working examples of Simple, Expert, and Module agents +- Can be installed directly via the new `bmad agent-install` command +- Serve as both learning resources and ready-to-use agents + +### ๐ŸŽฏ Epic Creation Moved to Phase 3 (After Architecture) + +**Workflow Sequence Corrected:** ``` -PRD โ†’ UX Design โ†’ Architecture โ†’ Epics & Stories - โ†‘ - NOW HERE (informed by all prior context) +Phase 2: PRD โ†’ UX Design +Phase 3: Architecture โ†’ Epics & Stories โ† NOW HERE (technically informed) ``` -**Flexibility Preserved:** +**Why This Fundamental Change:** -You can still generate epics at earlier stages if your project requires it: +- Epics need architectural context: API contracts, data models, technical decisions +- Stories can reference actual architectural patterns and constraints +- Reduces rewrites when architecture reveals complexity +- Better complexity-based estimation (not time-based) -- After PRD (basic structure, feature-focused) -- After UX Design (with interaction context) -- After Architecture (RECOMMENDED - fully informed) +### ๐Ÿ–ฅ๏ธ New IDE Support -The workflow now supports progressive enhancement, allowing you to create basic epics early and enrich them as more context becomes available. However, for most projects, **waiting until after architecture completion** produces the highest quality, most actionable stories. +**Google Antigravity IDE Installer:** -This represents a fundamental shift from "plan everything upfront" to "plan informed by technical reality." +- Flattened file naming for proper slash commands (bmad-module-agents-name.md) +- Namespace isolation prevents module conflicts +- Subagent installation support (project or user level) +- Module-specific injection configuration -### ๐ŸŽจ New Agent Saif the Frame Expert (Excalidraw Specialist) +**Codex CLI Enhancement:** -Thank you Saif for the new initial addition of this new agent, that will soon be further integrated into other workflows for the BMad Method and the CIS. This works great also if you install the excalidraw VSCode plugin to view the files easily. +- Now supports both global and project-specific installation +- CODEX_HOME configuration for multi-project workflows +- OS-specific setup instructions (Unix/Mac/Windows) -**Visual Diagramming Specialist:** +### ๐Ÿ—๏ธ Reference Agents & Standards -- New frame-expert agent specialized in Excalidraw visual representations - use this agent or the workflows at any point to produce architcure visualizations, mock ups, visual ideas to share with the other agents and so much more. Many udpates will come to further integrate this powerful tool. -- **Four specialized workflows:** - - `create-flowchart` - Process flow visualization - - `create-diagram` - General architectural diagrams - - `create-dataflow` - Data flow and pipeline visualization - - `create-wireframe` - UI/UX wireframe creation -- Includes shared Excalidraw helpers, templates, and validation -- Integrated into default-party.csv and team-fullstack configurations -- Icon: ๐Ÿ“ with webskip flag for IDE-only functionality +**New Reference Agents Provide Clear Examples:** -### ๐Ÿš€ Epic Creation Workflow Revolution +- **commit-poet.agent.yaml**: Simple agent with pure communication style +- **journal-keeper.agent.yaml**: Expert agent with sidecar file structure +- **security-engineer.agent.yaml**: Module agent for ecosystem integration +- **trend-analyst.agent.yaml**: Module agent with cross-workflow capabilities -**User-Value Focused Epic Structure:** +**Agent Type Clarification:** -- Added comprehensive principles for user-value focused epic breakdown -- Explicit anti-pattern examples showing wrong vs right epic structure -- **NO technical layer breakdown** - epics must deliver user value -- Multi-mode detection: CONTINUE, REPLACE, or UPDATE existing epics -- Epics now created AFTER architecture for technically-informed story breakdown -- Added checkpoint protocol for interactive workflow progression +- Clear documentation that agent types (Simple/Expert/Module) describe architecture, not capability +- Module = designed for ecosystem integration, not limited in function -**Progressive Enhancement Pattern:** +### ๐Ÿ› Technical Improvements -- Intelligent UPDATE vs CREATE mode detection -- Detects available context (UX, Architecture, Domain brief, Product brief) -- Living document approach with continuous updates -- Creates basic epics, then enriches with UX/Architecture context +**Linting Compliance:** -### โฐ Time Estimate Prohibition (Critical Update) +- Fixed all ESLint warnings across agent tooling +- `'utf-8'` โ†’ `'utf8'` (unicorn/text-encoding-identifier-case) +- `hasOwnProperty` โ†’ `Object.hasOwn` (unicorn/prefer-object-has-own) +- `JSON.parse(JSON.stringify(...))` โ†’ `structuredClone(...)` -**AI-Age Development Reality:** +**Agent Compilation Engine:** -- Added **critical warnings** against providing ANY time estimates (hours/days/weeks/months) -- Applied across **33 workflow instruction files** in BMB, BMGD, BMM, and CIS modules -- Acknowledges AI has fundamentally changed development speed -- Updated workflow creation guide with prohibition guidelines -- Recognizes traditional estimation methods are obsolete in AI-augmented development - -**Rationale:** Time estimates based on pre-AI development patterns are actively harmful and misleading. AI-driven development exhibits non-linear productivity patterns that make traditional estimation unreliable. - -### ๐ŸŽฏ Platform-Specific Command Filtering - -**IDE-Only and Web-Only Support:** - -- New `ide-only` and `web-only` boolean fields in agent menu schema -- Menu items filtered based on build target (web bundle vs local IDE) -- Examples: - - `workflow-init` and `correct-course` marked as IDE-only - - `advanced-elicitation` marked as web-only -- Enables platform-appropriate functionality across different environments - -**Agent Updates:** - -- PM: workflow-init and correct-course as ide-only -- UX Designer: Renamed trigger to create-ux-design -- SM: Renamed triggers for consistency (story-context โ†’ create-story-context) -- Analyst: Added research workflow after brainstorm -- Architect: Removed document field from validate-architecture -- Dev: Updated persona and critical actions for clarity -- Tech-writer: Added party-mode workflow -- All agents: Standardized party-mode descriptions - -### ๐Ÿ”ง Agent Customization Enhancement - -**Prompts and Memories Merging:** - -- Added merging logic for `customizeYaml.prompts` and `customizeYaml.memories` in agent loading -- New `buildMemoriesXml()` method for XML output -- Updated `buildPromptsXml()` to use `` wrapper for better compatibility -- Memories output integrated between persona and prompts sections -- Users can now customize agents via `bmad/_cfg/agents/*.customize.yaml` with: - - `prompts`: Array of {id, content} objects for action handlers - - `memories`: Array of strings for persistent agent memories - -### ๐Ÿ“‹ Workflow Configuration Standardization - -**Input File Patterns Cleanup:** - -- Removed 32 `recommended_inputs:` sections (redundant with input_file_patterns) -- Added `description:` fields to all input_file_patterns (25 workflows) -- Added missing `load_strategy` fields (5 workflows) -- Fixed BMB workflows with proper reference doc variables -- Updated BMB instructions to use new variables - -**Workflow Path Enhancements:** - -- Updated all 4 workflow paths (enterprise/method ร— brownfield/greenfield) -- Added multiple optional epic creation steps at different phases: - - After PRD (basic structure) - - After UX Design (with interaction context) - - After Architecture (final with full context) -- Changed PRD output description from "with epics and stories" to "with FRs and NFRs" - -### ๐Ÿ—‚๏ธ Documentation & Architecture Updates - -**Solutioning Gate Check Removal:** - -- Deleted entire solutioning-gate-check workflow (682 lines) -- Replaced by new implementation-readiness pattern -- Cleaner separation of concerns in solutioning phase - -**PRD Template Simplification:** - -- Removed hardcoded "Implementation Planning", "References", and "Next Steps" sections -- PRD now focuses purely on requirements, not workflow orchestration -- Epics/stories created as separate step after architecture - -**Documentation Overhaul:** - -- 15+ documentation files updated across modules -- Updated quick-start guide with v6 workflow sequence -- Clarified that epics are created AFTER architecture, not during PRD -- Updated solutioning docs to reflect implementation-readiness pattern -- Improved agents-guide, brownfield-guide, enterprise docs -- Enhanced glossary, FAQ, and workflow reference documentation - -### ๐Ÿ› Bug Fixes & Installer Improvements - -**Critical Fixes:** - -- Fixed installer blocking issues when folder name is changed during install -- Updated file paths in agent and workflow configurations to use `{bmad_folder}` variable (#917) -- Fixed shard-doc to use proper command for markdown-tree-parser (#911) -- PRD workflow now properly uses project-types CSV -- Web bundler fixes and bundle link updates in documentation - -**Architecture Workflow:** - -- Made epics input optional (falls back to PRD FRs) -- Updated innovation strategy phases to remove time-based language -- Phases now: Immediate Impact โ†’ Foundation Building โ†’ Scale & Optimization +- Auto-injects frontmatter, activation, handlers, help/exit menu items +- Smart handler inclusion (only includes handlers actually used) +- Proper XML escaping and formatting +- Persona name customization support ### ๐Ÿ“Š Impact Summary -- **65+ files modified** across all modules -- **682 lines removed** from deprecated solutioning-gate-check workflow -- **33 instruction files** updated with time estimate prohibition -- **4 new workflows** added for frame-expert agent -- **32 recommended_inputs sections** cleaned up for standardization -- **Net reduction of ~500+ lines** through consolidation and cleanup +**New in alpha.11:** + +- **Agent installation system** with `bmad agent-install` CLI command +- **4 new reference agents** (commit-poet, journal-keeper, security-engineer, trend-analyst) +- **Complete agent documentation suite** with 7 new focused guides +- **Expert agent sidecar support** in edit-agent workflow +- **2 new IDE installers** (Google Antigravity, enhanced Codex) +- **Unified validation checklist** (160 lines) for consistent quality standards +- **60 pure communication style presets** for agent persona design + +**Enhanced from alpha.10:** + +- **BMB agent builder workflows** with accurate context and comprehensive guidance +- **All 9 BMM agents** enhanced with distinct, memorable communication voices +- **Excalidraw capabilities** refined and distributed to role-appropriate agents +- **Epic creation** moved to Phase 3 (after Architecture) for technical context ### โš ๏ธ Breaking Changes +**Agent Changes:** + +- Frame Expert agent retired - diagram capabilities now available through role-appropriate agents: + - Architecture diagrams โ†’ `/architect` + - Process flows โ†’ `/pm` + - Wireframes โ†’ `/ux-designer` + - Documentation visuals โ†’ `/tech-writer` + **Workflow Changes:** -- Solutioning-gate-check workflow removed (replaced by implementation-readiness) -- PRD no longer includes epic/story generation (separate workflow step) -- Some workflow triggers renamed for consistency +- Epic creation moved from Phase 2 to Phase 3 (after Architecture) +- Excalidraw workflows redistributed to appropriate agents -**Variable Updates:** +**Installation Changes:** -- Agent and workflow configurations now require `{bmad_folder}` variable support -- PRD output format changed (FRs and NFRs focus, not epics/stories) +- New `bmad agent-install` command replaces manual agent installation +- Agent YAML files must be compiled to XML for use ### ๐Ÿ”„ Migration Notes **For Existing Projects:** -1. **Epic Creation:** Epics are now created as a separate workflow step AFTER architecture - - Update any automation scripts that expected epics in PRD output - - Use `create-epics-and-stories` workflow explicitly +1. **Frame Expert Users:** + - Transition to role-appropriate agents for diagrams + - All Excalidraw functionality preserved and enhanced + - Shared templates now in core resources for wider access -2. **Time Estimates:** Focus on value delivery, not time predictions +2. **Agent Installation:** + - Use `bmad agent-install` for all agent installations + - Existing manual installations still work but won't have customization -3. **Agent Customization:** New customization options available - - Add memories via `*.customize.yaml` files - - Custom prompts can extend agent capabilities +3. **Epic Creation Timing:** + - Epics now created in Phase 3 after Architecture + - Update any automation expecting epics in Phase 2 -4. **Platform-Specific Commands:** Some commands now platform-restricted - - workflow-init only available in IDE environments +4. **Communication Styles:** + - Review agent communication_style fields + - Remove any role/identity/principle content + - Use communication-presets.csv for pure styles -5. **Frame Expert:** New agent available for visual diagramming - - Install/reinstall to get new workflows - - Four specialized Excalidraw workflows available +5. **Expert Agents:** + - Edit-agent workflow now fully supports sidecar files + - Organize templates and data files in agent folder + +## [6.0.0-alpha.10] + +**Release: November 16, 2025** + +- **๐ŸŽฏ Epics Generated AFTER Architecture**: Major milestone - epics/stories now created after architecture for technically-informed user stories with better acceptance criteria +- **๐ŸŽจ Frame Expert Agent**: New Excalidraw specialist with 4 diagram workflows (flowchart, diagram, dataflow, wireframe) for visual documentation +- **โฐ Time Estimate Prohibition**: Critical warnings added across 33 workflows - acknowledges AI has fundamentally changed development speed +- **๐ŸŽฏ Platform-Specific Commands**: New `ide-only`/`web-only` fields filter menu items based on environment (IDE vs web bundle) +- **๐Ÿ”ง Agent Customization**: Enhanced memory/prompts merging via `*.customize.yaml` files for persistent agent personalization ## [6.0.0-alpha.9] **Release: November 12, 2025** -This alpha release introduces major workflow engine enhancements, comprehensive documentation, and significant simplification of project structure and configuration. - -### ๐Ÿš€ Workflow Engine Revolution - -**Intelligent File Discovery Protocol:** - -- New reusable `discover_inputs` protocol for automatic file loading across all workflows -- Three intelligent loading strategies: - - FULL_LOAD: Loads all sharded documents for comprehensive context - - SELECTIVE_LOAD: Targets specific shards via template variables - - INDEX_GUIDED: Analyzes table of contents and intelligently loads relevant sections -- Auto-discovers whole vs sharded documents with automatic fallback -- Transparent reporting of loaded content with file counts -- Implemented across all BMM Phase 1-4 workflows and new BMGD Phase 4 workflows - -**Track-Based Project System:** - -- Replaced confusing "Level 0-4" terminology with intuitive track names: - - **quick-flow**: Bug fixes and small features (replaces Level 0-1) - - **bmad-method**: Full planning track (replaces Level 2-3) - - **enterprise-bmad-method**: Extended planning (replaces Level 4) -- Updated all workflows to be track-aware rather than level-dependent - -### ๐Ÿ“š Comprehensive Documentation - -**New Guides Added:** - -- **Agent Customization Guide:** Complete instructions for customizing agent names, personas, memories, and behaviors -- **Web Bundles & Platform Guide:** Comprehensive guide for using BMad agents in Gemini Gems and Custom GPTs - - Critical setup rules with exact configuration requirements - - Cost-saving strategies (60-80% savings via web planning โ†’ local implementation) - - Platform comparison and recommendations - -### ๐Ÿ—๏ธ Configuration & Structure Improvements - -**Unified Output Folder Structure:** - -- Single `output_folder` for ALL AI-generated artifacts (default: "docs") -- **REMOVED: `.ephemeral/` and `.bmad-ephemeral/` folders are completely eliminated** -- Phase 4 ephemeral content now organized within output folder as `sprint_artifacts`: - - Default path: `docs/sprint-artifacts/` (configurable during install) - - Contains: stories, epic context, story context, sprint plans, code reviews - - Can be set to `docs/stories/` for backward compatibility -- Eliminated confusing separate folder proliferation -- Clearer prompts during installation - -**Dynamic Path Configuration:** - -- Replaced hardcoded `.bmad` paths with `{bmad_folder}` placeholder throughout -- Users can now fully customize installation folder names -- Improved flexibility and reduced coupling to specific directory structures - -### ๐ŸŽฏ Tech-Spec Workflow Revolution - -**Intent-Based Intelligence:** - -- Removed 150+ lines of hardcoded stack detection examples -- Replaced prescriptive instructions with adaptive intelligent guidance -- Stack detection now automatically adapts to ANY project type -- Consolidated story generation into single unified workflow -- 50% fewer workflow files while maintaining full functionality - -### ๐ŸŽฎ BMGD Phase 4 Implementation - -**Complete Game Development Workflows:** - -- Added 10 Phase 4 production workflows for game development -- Includes: code-review, sprint-planning, story creation, retrospectives -- All workflows follow BMM patterns with game-specific adaptations -- Unified with BMM workflows to eliminate duplication - -### ๐ŸŒ Web Bundle Enhancements - -**GitHub Pages Support:** - -- Web bundles can now be hosted directly on GitHub Pages -- Automatic directory browsing and zip download functionality -- Improved distribution setup documentation - -**Testing Architecture:** - -- New test design workflow for Phase 3 architecture level -- Comprehensive testing strategy generation - -### ๐Ÿ”ง Code Quality & Maintenance - -**Major Cleanup:** - -- Removed 200+ files that shouldn't be version controlled -- Cleaned up 21 pre-generated XML bundles (users generate fresh) -- Fixed corrupted variable patterns throughout workflows -- Standardized variable naming conventions -- Removed duplicate BMGD workflows (now shares BMM Phase 4) - -**Bug Fixes:** - -- Fixed story status handling (accepts both "review" and "ready-for-review") -- Corrected sprint artifact paths and undefined variables -- Fixed installer quick install mode -- Removed injected bad formatting characters -- Enhanced shard document tool to prevent confusion with whole/sharded versions - -### ๐Ÿ’ก Developer Experience - -**Enhanced Workflow Management:** - -- Better error handling and user guidance -- Exit/continue options when prerequisites missing -- Improved validation checklists with modern formatting -- Clearer instructions and adaptive conversation goals - -**Variable Standardization:** - -- Consistent hyphenated format: `{output-folder}` -- Renamed unclear variables: `{dev_ephemeral_location}` โ†’ `{sprint_artifacts}` -- Fixed 40+ workflows with standardized variable patterns - -### ๐Ÿ“ˆ Impact Summary - -- **98 source files modified** (299 insertions, 6,567 deletions) -- **40+ workflows updated** with track system and standardization -- **12 duplicate workflows eliminated** through consolidation -- **3 installer configs simplified** with major folder improvements -- **2 comprehensive guides added** for customization and platform usage - -### โš ๏ธ Breaking Changes - -- Level-based terminology (Level 0-4) replaced with track names -- Folder structure changes may require reconfiguration for existing projects -- Variable name changes in workflows (backward compatibility maintained where possible) - -### ๐Ÿ”„ Migration Notes - -**Important Folder Structure Changes:** - -- **The `.ephemeral/` folder is completely gone** - Phase 4 ephemeral content no longer uses a separate folder -- Phase 4 artifacts (epic context, stories, story context, sprint plans, code reviews) now live in `{output_folder}/{sprint_artifacts}` -- New default location: `docs/sprint-artifacts/` (was previously `.bmad-ephemeral/` or similar) - -**Migration Options:** - -1. **If you have existing `docs/stories/` content:** - - Move all content from `docs/stories/` to `docs/sprint-artifacts/` - - Update any references or scripts pointing to the old location - -2. **To keep using `docs/stories/` location:** - - During the new version install, set sprint_artifacts to "stories" when prompted - - This maintains backward compatibility with your existing structure - -3. **Clean migration checklist:** - - Delete old `.ephemeral/` folder if it exists - - Delete old `.bmad-ephemeral/` folder if it exists - - Move Phase 4 artifacts to new location or configure installer to use existing path - - Update to new track terminology in configurations (quick-flow, bmad-method, enterprise-bmad-method) - - Regenerate web bundles using `npm run bundle` for latest changes - - Update any custom workflows to use new `discover_inputs` protocol +- **๐Ÿš€ Intelligent File Discovery Protocol**: New `discover_inputs` with FULL_LOAD, SELECTIVE_LOAD, and INDEX_GUIDED strategies for automatic context loading +- **๐Ÿ“š 3-Track System**: Simplified from 5 levels to 3 intuitive tracks: quick-flow, bmad-method, and enterprise-bmad-method +- **๐ŸŒ Web Bundles Guide**: Comprehensive documentation for Gemini Gems and Custom GPTs with 60-80% cost savings strategies +- **๐Ÿ—๏ธ Unified Output Structure**: Eliminated `.ephemeral/` folders - all artifacts now in single configurable output folder +- **๐ŸŽฎ BMGD Phase 4**: Added 10 game development workflows following BMM patterns with game-specific adaptations ## [6.0.0-alpha.8] **Release: November 9, 2025** -This alpha release focuses on installation flexibility, artifact organization, and comprehensive web bundle enhancements for better multi-agent collaboration. - -### ๐ŸŽฏ Installation Path Enhancements - -**Configurable Installation Directory:** - -- Users can now specify custom installation directories during setup -- Changed default installation to `.bmad` (hidden directory) for cleaner project organization -- Reduces visual clutter in project root by hiding BMAD infrastructure files -- VS Code settings updated to work with new `.bmad` directory structure - -**Ephemeral File Handling:** - -- Updated phase 4 implementation workflows to use ephemeral file locations -- Better separation between documentation and implementation artifacts -- Phase 4 items (stories, code review, sprint plan, context files) can now be stored outside docs folder -- Installer includes questions for artifact path selection - -### ๐Ÿš€ CLI & Agent Loading Improvements - -**Optimized Agent Loading:** - -- CLI commands now load from installed agent files instead of maintaining duplicates -- Eliminates duplication between source and installed agent definitions -- Reduces maintenance burden and ensures consistency - -**Installer UX Enhancements:** - -- Enhanced installer interface with version display -- Better visual feedback during installation process - -### ๐ŸŒ Web Bundle Enhancements - -**Party Mode Support:** - -- All web bundles (single agent and team) now include party mode for multi-agent collaboration -- Users can invoke multi-agent discussions from any bundled agent -- Added default-party.csv files to bmm, bmgd, and cis modules with customizable party configurations - -**Advanced Elicitation Integration:** - -- Integrated advanced elicitation capabilities into standalone agents -- All 39 elicitation methods now available in web bundles - -**Expanded Agent Bundles:** - -- New web bundle outputs for all agents: analyst, architect, dev, pm, sm, tea, tech-writer, ux-designer -- Game development agents: game-designer, game-dev, game-architect, game-scrum-master -- Creative Intelligence Suite agents fully bundled - -**Team Customization:** - -- Customizable party configurations per module -- Users can define which agents participate in party mode discussions - -### ๐Ÿ”ง Phase 4 Workflow Updates - -**Artifact Separation (In Progress):** - -- Initiated separation of phase 4 implementation artifacts from documentation -- Dedicated artifact path for stories, code review, sprint plan, context files -- Updated workflow.yaml files for: - - code-review workflow - - sprint-planning workflow - - story-context workflow - - epic-tech-context workflow - - retrospective workflow -- Configuration support added for artifact path selection during installation - -### ๐Ÿ› ๏ธ IDE Integration - -**Gemini TOML:** - -- Improved with clear loading instructions using @ commands -- Better documentation for Gemini CLI users - -**Agent Launcher Templates:** - -- Agent launcher markdown files now use centralized critical indication templates -- Improved consistency across IDE configurations - -**GitHub Copilot:** - -- Updated tool names to match official VS Code documentation (November 2025) -- Better integration with latest Copilot features - -### ๐Ÿ› Bug Fixes - -- Fixed duplicate manifest entries by deduplicating module lists using Set -- Cleaned up legacy `bmad/`, `bmd/`, and `web-bundles/` directories on installation -- Various improvements to phase 4 workflow artifact handling -- Better error handling in web bundler - -### ๐Ÿ“ฆ Infrastructure Changes - -- New agent and action command header models for standardization -- Enhanced web-bundle-activation-steps fragment -- Updated web-bundler.js to support new structure -- Improved party mode instructions and workflow orchestration - -### ๐Ÿ“Š Impact Summary - -This release brings significant improvements to installation flexibility and multi-agent collaboration: - -- **Flexibility:** Configurable installation paths for different project preferences -- **Organization:** Cleaner project structure with hidden `.bmad` directory -- **Collaboration:** Comprehensive party mode support in all web bundles -- **Consistency:** Optimized agent loading eliminates duplication -- **Artifact Management:** Better separation of documentation vs implementation artifacts - ---- +- **๐ŸŽฏ Configurable Installation**: Custom directories with `.bmad` hidden folder default for cleaner project structure +- **๐Ÿš€ Optimized Agent Loading**: CLI loads from installed files eliminating duplication and maintenance burden +- **๐ŸŒ Party Mode Everywhere**: All web bundles include multi-agent collaboration with customizable party configurations +- **๐Ÿ”ง Phase 4 Artifact Separation**: Stories, code reviews, sprint plans now configurable outside docs folder +- **๐Ÿ“ฆ Expanded Web Bundles**: All BMM, BMGD, and CIS agents bundled with advanced elicitation integration ## [6.0.0-alpha.7] **Release: November 7, 2025** -This alpha release focuses on web bundle improvements, module extraction, and enhanced workflow vendoring capabilities. - -### ๐ŸŒ Web Bundler Improvements - -**Workflow Vendoring:** - -- Web bundler now performs workflow vendoring before bundling agents -- Workflows referenced via `workflow-install` attributes are automatically copied from source to destination -- Similar to module installer behavior, ensuring consistency -- Config_source is updated in vendored workflows to reference target module -- Fixes missing dependency warnings for cross-module workflow references - -**Enhanced Dependency Resolution:** - -- Improved workflow dependency detection and bundling -- Better handling of workflows with `web_bundle: false` flag -- Menu items for non-web workflows are now properly excluded from bundles -- Shows positive "โœ“ No missing dependencies" message when all dependencies resolved - -**Advanced Elicitation Fix:** - -- Added missing `adv-elicit-methods.csv` to workflow bundles -- Includes CSV in all workflows using `adv-elicit.xml`: - - architecture workflow - - prd workflow - - tech-spec workflow -- Fixes runtime failures when advanced elicitation is invoked in bundled workflows - -### ๐ŸŽฎ BMGD Module Extraction - -**Game Development Module:** - -- Extracted game development functionality from BMM into standalone BMGD module -- Moved agents: game-designer, game-dev, game-architect from BMM to BMGD -- Moved team config: team-gamedev -- Created new Game Dev Scrum Master agent using workflow vendoring pattern - -**Reorganized Game Dev Workflows:** - -Industry-standard game development phases: - -- **Phase 1 (Preproduction):** brainstorm-game, game-brief -- **Phase 2 (Design):** gdd (Game Design Document), narrative -- **Phase 3 (Technical):** game-architecture -- **Phase 4 (Production):** Vendors BMM workflows (dev-story, code-review, sprint-planning, etc.) - -**Workflow Vendoring Implementation:** - -- Game Dev SM agent uses `workflow-install` to vendor BMM phase 4 workflows -- Enables module independence while sharing proven workflows -- Sets pattern for future module extractions and specializations - -### ๐Ÿ”ง IDE Installation Improvements - -**Claude Code Fix:** - -- Fixed regression preventing README file slash commands from installing -- Cleaned up bmad folders in tools directory on installation -- Better handling of IDE-specific configuration files - -### ๐Ÿ“š Documentation Updates - -**TEA Agent Documentation:** - -- Updated Test Architect documentation to align with BMad 4-phase methodology -- Better integration with overall workflow structure -- Clearer role definitions and responsibilities - -**Diagram Improvements:** - -- More visual documentation updates -- Enhanced Mermaid diagram drafts -- Better workflow visualization - -### ๐Ÿ› Bug Fixes - -- Fixed missing `adv-elicit-methods.csv` in workflow bundles -- Removed menu items for workflows with `web_bundle: false` -- Fixed IDE installation regression for Claude Code README commands -- Improved workflow vendoring dependency resolution - -### ๐Ÿ”„ Breaking Changes - -**Module Structure:** - -- Game development functionality moved from BMM to BMGD module -- Existing projects using game dev agents should reinstall to get new module structure -- No functional changes - agents work the same way in new location - -### ๐Ÿ“Š Impact Summary - -This release establishes better module organization and cross-module workflow sharing: - -- **Modularity:** BMGD extraction demonstrates clean module separation pattern -- **Reusability:** Workflow vendoring enables sharing proven workflows across modules -- **Reliability:** Advanced elicitation now works correctly in all web bundles -- **Flexibility:** Modules can be specialized while leveraging core workflows - ---- +- **๐ŸŒ Workflow Vendoring**: Web bundler performs automatic workflow vendoring for cross-module dependencies +- **๐ŸŽฎ BMGD Module Extraction**: Game development split into standalone module with 4-phase industry-standard structure +- **๐Ÿ”ง Enhanced Dependency Resolution**: Better handling of `web_bundle: false` workflows with positive resolution messages +- **๐Ÿ“š Advanced Elicitation Fix**: Added missing CSV files to workflow bundles fixing runtime failures +- **๐Ÿ› Claude Code Fix**: Resolved README slash command installation regression ## [6.0.0-alpha.6] **Release: November 4, 2025** -This alpha release focuses on installation flexibility, improved UX, and bug fixes for the installer system. - -### ๐Ÿ› Bug Fixes - -**Installer Fixes:** - -- Fixed manifestPath error in ide-config-manager causing installation failures -- Fixed installer option display to show full labels instead of just values for single/multi-select -- Better error handling during installation process - -**Documentation Installation:** - -- Add conditional documentation installation feature -- Users can now opt out of installing docs to reduce installation footprint -- New `install_user_docs` configuration option (defaults to true) -- Useful for production environments or users who prefer online documentation - -### ๐ŸŽจ User Experience Improvements - -**Installer UX:** - -- Improved config question display with descriptive labels -- Better formatting for single and multi-select options -- Clearer feedback during installation process -- More intuitive option selection - -### ๐Ÿ“– Documentation Updates - -**Contributing Guidelines:** - -- Updated CONTRIBUTING.md to remove references to non-existent 'next' branch -- Clearer contribution workflow instructions -- Better alignment with actual repository structure - -### ๐Ÿงน Maintenance - -**Issue Tracker Cleanup:** - -- Closed 54 legacy v4 issues (older than 1 month) -- Maintains clean issue tracker focused on v6 development -- Improved issue management and prioritization - -### ๐Ÿ“Š Impact Summary - -This release improves installation reliability and user experience: - -- **Reliability:** Fixed critical installer bugs preventing successful installations -- **Flexibility:** Optional documentation installation for different use cases -- **Clarity:** Better UX with descriptive labels and clearer feedback -- **Maintenance:** Clean issue tracker focused on current development - ---- +- **๐Ÿ› Critical Installer Fixes**: Fixed manifestPath error and option display issues blocking installation +- **๐Ÿ“– Conditional Docs Installation**: Optional documentation installation to reduce footprint in production +- **๐ŸŽจ Improved Installer UX**: Better formatting with descriptive labels and clearer feedback +- **๐Ÿงน Issue Tracker Cleanup**: Closed 54 legacy v4 issues for focused v6 development +- **๐Ÿ“ Contributing Updates**: Removed references to non-existent branches in documentation ## [6.0.0-alpha.5] **Release: November 4, 2025** -This alpha release represents a major refinement of BMM workflows, documentation accuracy, and the introduction of the revolutionary 3-track scale system. The focus is on workflow consistency, eliminating bloat, and providing accurate, reality-based guidance for modern AI-driven development. - -### ๐ŸŽฏ 3-Track Scale System - Revolutionary Simplification - -**From 5 Levels to 3 Clear Tracks:** - -The BMM scale system has been dramatically simplified from a confusing 5-level hierarchy (Levels 0-4) to 3 intuitive, preference-driven tracks: - -- **Quick Flow** - Fast, lightweight development for small changes and quick iterations -- **BMad Method** - Balanced approach for most development projects -- **Enterprise Method** - Comprehensive methodology for large-scale, mission-critical systems - -**Key Changes:** - -- Replaced `project_level` variable with `project_track` throughout all workflows -- Updated 8 workflow path YAML files to reflect new track naming (removed level-based paths) -- Simplified workflow-init to guide users based on preference, not artificial "levels" -- Updated all documentation to reference tracks instead of levels -- Eliminated confusing "target_scale" variable (no longer needed) - -**Impact:** - -Users now choose development approach based on **project needs and team preference**, not arbitrary complexity levels. This aligns with how real teams actually work and removes decision paralysis. - -**Documentation Updated:** - -- `scale-adaptive-system.md` - Complete rewrite around 3-track methodology (756 line overhaul) -- `quick-start.md` - Updated to reference tracks -- `brownfield-guide.md` - Track-based guidance instead of level-based -- `glossary.md` - New track definitions, removed level references -- `workflow-status/init/instructions.md` - Major rewrite for track-based initialization (865 lines) - -### โœจ Workflow Modernization & Standardization - -**1. Elicitation System Modernization:** - -- Removed legacy `` XML tag from core workflow.xml -- Replaced with explicit `advanced-elicitation.xml` pattern -- More self-documenting and eliminates confusing indirection layer -- Added strategic elicitation points across all planning workflows: - - **PRD:** After success criteria, scope, functional requirements, and final review - - **Create-Epics-And-Stories:** After epic proposals and each epic's stories - - **Architecture:** After decisions, structure, patterns, implementation patterns, and final doc -- Updated audit-workflow to remove obsolete elicit-required tag scanning - -**2. Input Document Discovery Streamlined:** - -- Replaced verbose 19-line "Input Document Discovery" sections with single critical tag -- New concise format: `Input documents specified in workflow.yaml input_file_patterns...` -- Eliminates duplication (workflow.yaml already defines patterns - why repeat them?) -- Updated across 6 workflows: PRD, create-epics-and-stories, architecture, tech-spec, UX, gate-check -- **Saved ~114 lines of repeated bloat** - -**3. Epic/Story Template Standardization:** - -- Replaced hardcoded 8-epic templates with clean repeating patterns using N/M variables -- Added BDD-style acceptance criteria (Given/When/Then/And) for better clarity -- Removed instructional bloat from templates (moved to instructions.md where it belongs) -- **Principle:** Templates show OUTPUT structure, instructions show PROCESS -- Applied to both create-epics-and-stories and tech-spec workflows -- Templates now use HTML comments to clearly indicate repeating sections - -**4. Workflow.yaml Pattern Consistency:** - -- Standardized `input_file_patterns` across all workflows -- Separated `recommended_inputs` (semantic WHAT) from `input_file_patterns` (file discovery WHERE) -- Removed duplication between recommended_inputs file paths and input_file_patterns -- Create-epics-and-stories now uses proper whole/sharded pattern like architecture workflow -- Solutioning-gate-check cleaned up to use semantic descriptions not file paths - -**Files Changed:** 18 files across core, planning, and solutioning workflows - -### ๐Ÿ“š Documentation Accuracy Overhaul - -**Agent YAML as Source of Truth:** - -Fixed critical documentation inaccuracies by treating agent YAML files as the authoritative source: - -**agents-guide.md Corrections:** - -- Fixed Game Developer workflow names (dev-story โ†’ develop-story, added story-done) -- Added agent name "Paige" to Technical Writer (matches naming pattern) -- Corrected epic-tech-context ownership (Architect โ†’ SM agent across all docs) -- Updated agent reference tables to reflect actual capabilities from YAML configs - -**workflows-implementation.md Corrections:** - -- Fixed epic-tech-context agent attribution in 3 locations (Architect โ†’ SM) -- Updated multi-agent workflow ownership table -- Aligned all workflow descriptions with actual agent YAML definitions - -**Impact:** Zero hallucination risk - documentation now accurately reflects what agents can actually do. - -### ๐Ÿ—๏ธ Brownfield Development Reality Check - -**Rewrote brownfield-guide.md Phase 0 Section:** - -Replaced oversimplified 3-scenario model with **real-world guidance** for messy brownfield projects: - -**New Scenarios (4 instead of 3):** - -- **Scenario A:** No documentation โ†’ `document-project` workflow (existing) -- **Scenario B:** Docs exist but massive/outdated/incomplete โ†’ **document-project** (NEW - very common case) -- **Scenario C:** Good docs but massive files โ†’ **shard-doc โ†’ index-docs** (NEW - handles >500 line files) -- **Scenario D:** Confirmed AI-optimized docs โ†’ Skip Phase 0 (correctly marked as RARE) - -**Key Additions:** - -- Default recommendation: "Run document-project unless you have confirmed, trusted, AI-optimized docs" -- Quality assessment checklist (current, AI-optimized, comprehensive, trusted) -- Massive document handling guidance (>500 lines, 10+ sections triggers shard-doc) -- Explicit explanation of why regenerating is better than indexing bad docs -- Impact explanation: how outdated docs break AI workflows (token limits, wrong assumptions, broken integrations) - -**Principle:** "When in doubt, run document-project" - Better to spend 10-30 minutes generating fresh docs than waste hours debugging AI agents with bad documentation. - -### ๐Ÿš€ PM/UX Evolution for Enterprise Agentic Development - -**New Section: The Evolving Role of Product Managers & UX Designers** - -Added comprehensive forward-looking guidance based on **November 2025 industry research**: - -**Industry Trends:** - -- 56% of product professionals cite AI/ML as top strategic focus -- PRD-to-Code automation: build and deploy apps in 10-15 minutes (current state) -- By 2026: Roles converging into "Full-Stack Product Lead" (PM + Design + Engineering) -- Very high salaries for AI Agent PMs who orchestrate autonomous development systems - -**Role Transformation:** - -- PMs evolving from spec writers โ†’ code orchestrators -- Writing AI-optimized PRDs that **feed agentic pipelines directly** -- UX designers generating production code with Figma-to-code tools -- Technical fluency becoming **table stakes**, not optional -- Reviewing PRs from AI agents alongside human developers - -**How BMad Method Enables This Future (10 Ways):** - -1. AI-Executable PRD Generation - PRDs become work packages for cloud agents -2. Automated Epic/Story Breakdown - No more manual story refinement sessions -3. Human-in-the-Loop Architecture - PMs learn while validating technical decisions -4. Cloud Agentic Pipeline Vision - Current (2025) + Future (2026) roadmap with diagrams -5. UX Design Integration - Designs validated through working prototypes -6. PM Technical Skills Development - Learn by doing through conversational workflows -7. Organizational Leverage - 1 PM โ†’ 20-50 AI agents (5-10ร— productivity multiplier) -8. Quality Consistency - What gets built matches what was specified -9. Rapid Prototyping - Hours to validate ideas vs months -10. Career Path Evolution - Positions PMs for emerging AI Agent PM, Full-Stack Product Lead roles - -**Cloud Agentic Pipeline Vision:** - -``` -Current (2025): PM PRD โ†’ Stories โ†’ Human devs + BMad agents โ†’ PRs โ†’ Review โ†’ Deploy -Future (2026): PM PRD โ†’ Stories โ†’ Cloud AI agents โ†’ Auto PRs โ†’ Review โ†’ Auto-merge โ†’ Deploy -Time savings: 6-8 weeks โ†’ 2-5 days -``` - -**What Remains Human:** - -- Product vision, empathy, creativity, judgment, ethics -- PMs spend MORE time on human elements (AI handles execution) -- Product leaders become "builder-thinkers" not just spec writers - -### ๐Ÿ“– Document Tightening - -**enterprise-agentic-development.md Overhaul:** - -- Reduced from 1207 โ†’ 640 lines (47% reduction) -- 10ร— more BMad-centric - every section ties back to how BMad enables the future -- Removed redundant examples, consolidated sections, kept actionable insights -- Stronger value propositions for PMs, UX, enterprise teams throughout - -**Key Message:** "The future isn't AI replacing PMsโ€”it's AI-augmented PMs becoming 10ร— more powerful through BMad Method." - -### ๐Ÿ› ๏ธ Infrastructure & Quality - -**Agent Naming Consistency:** - -- Renamed `paige.agent.yaml` โ†’ `tech-writer.agent.yaml` (matches agent naming pattern) -- Updated all references across documentation and workflow files - -**README Updates:** - -- Updated local installation instructions -- Better hierarchy and clearer CTAs in root README - -### ๐Ÿ”„ Breaking Changes - -**Variable Renames:** - -- `project_level` โ†’ `project_track` in PRD and all planning workflows -- Removed `target_scale` variable (no longer needed with 3-track system) - -**Workflow Path Files:** - -- Removed 9 level-based workflow paths (brownfield-level-0, greenfield-level-3, etc.) -- Added 6 new track-based workflow paths (quick-flow-greenfield, method-brownfield, enterprise-greenfield, etc.) - -**Workflow Triggers:** - -- Tech-spec workflow descriptions updated to reference tracks not levels - -### ๐Ÿ“Š Impact Summary - -These changes bring BMM from alpha.4's solid foundation to alpha.5's **production-ready professionalism**: - -- **Accuracy:** Documentation matches YAML source of truth (zero hallucination risk) -- **Simplicity:** 3-track system eliminates decision paralysis and artificial complexity -- **Reality:** Brownfield guidance handles messy real-world scenarios, not idealized ones -- **Forward-looking:** PM/UX evolution section positions BMad as essential framework for emerging roles -- **Consistency:** Standardized elicitation, input discovery, and template patterns across all workflows -- **Maintainability:** 47% documentation reduction + ~114 lines of bloat removed from workflows -- **Actionable:** Concrete workflows, commands, examples throughout all guidance - -Users now have **trustworthy, reality-based, future-oriented guidance** for using BMad Method in both current workflows and emerging agentic development patterns. - -### ๐Ÿ“ฆ Files Changed - -**Core & Infrastructure (3 files):** - -- `bmad/core/tasks/workflow.xml` - Removed elicit-required tag -- `src/core/tasks/workflow.xml` - Removed elicit-required tag -- `package.json` - Version bump - -**Documentation (8 files):** - -- `src/modules/bmm/docs/README.md` - Track references -- `src/modules/bmm/docs/agents-guide.md` - Accuracy fixes, agent ownership corrections -- `src/modules/bmm/docs/brownfield-guide.md` - Phase 0 reality check, track migration -- `src/modules/bmm/docs/enterprise-agentic-development.md` - PM/UX evolution, 47% reduction -- `src/modules/bmm/docs/faq.md` - Track references -- `src/modules/bmm/docs/glossary.md` - Track definitions, removed levels -- `src/modules/bmm/docs/quick-spec-flow.md` - Track references -- `src/modules/bmm/docs/scale-adaptive-system.md` - Complete 3-track rewrite - -**Workflow Paths (14 files):** - -- Removed: 9 level-based paths (brownfield-level-0 through greenfield-level-4) -- Added: 6 track-based paths (quick-flow/method/enterprise ร— greenfield/brownfield) - -**Planning Workflows (11 files):** - -- PRD workflow: Elicitation, track migration, input discovery, checklist updates -- Create-epics-and-stories: Template rebuild, BDD format, elicitation, input patterns -- Tech-spec: Template rebuild, BDD format, input discovery -- Architecture: Elicitation points, input discovery - -**Solutioning Workflows (2 files):** - -- UX Design: Input discovery streamlined -- Gate-check: Input pattern cleanup, semantic descriptions - -**Build & Utilities (2 files):** - -- Audit workflow: Updated tag scanner (removed elicit-required) -- Workflow status init: Track-based initialization logic - -**Total: 40+ files changed** - ---- - -### Installation - -```bash -npx bmad-method@6.0.0-alpha.5 install -``` - -For upgrading from alpha.4: - -```bash -# Backup your customizations first -npx bmad-method@6.0.0-alpha.5 install -``` - -### Migration Notes - -If upgrading from v6.0.0-alpha.4: - -1. **Scale System Change:** The 5-level system (Levels 0-4) is now 3 tracks (Quick Flow, BMad Method, Enterprise Method) - - Existing projects continue to work - workflows auto-detect track from context - - New projects will use track-based initialization - - Review `docs/scale-adaptive-system.md` for the new mental model - -2. **Workflow Improvements:** - - Better elicitation at strategic decision points (you'll be asked for input more frequently) - - Cleaner templates with BDD acceptance criteria - - More consistent input document discovery - -3. **Documentation Accuracy:** - - Agent capabilities now match YAML definitions exactly - - Brownfield guidance handles real-world messy scenarios - - PM/UX evolution section shows future of AI-driven development - -4. **Agent Naming:** Technical Writer agent file renamed (paige.agent.yaml โ†’ tech-writer.agent.yaml) - - No functional impact - just internal naming consistency - -5. **No Breaking Changes:** Existing project structures, workflow outputs, and customizations remain compatible - ---- +- **๐ŸŽฏ 3-Track Scale System**: Revolutionary simplification from 5 confusing levels to 3 intuitive preference-driven tracks +- **โœจ Elicitation Modernization**: Replaced legacy XML tags with explicit `invoke-task` pattern at strategic decision points +- **๐Ÿ“š PM/UX Evolution Section**: Added November 2025 industry research on AI Agent PMs and Full-Stack Product Leads +- **๐Ÿ—๏ธ Brownfield Reality Check**: Rewrote Phase 0 with 4 real-world scenarios for messy existing codebases +- **๐Ÿ“– Documentation Accuracy**: All agent capabilities now match YAML source of truth with zero hallucination risk ## [6.0.0-alpha.4] **Release: November 2, 2025** -This alpha release represents a major leap forward in documentation, workflow intelligence, and usability. The BMM module now features professional documentation, context-aware planning workflows, and universal document management capabilities. - -### ๐Ÿ“š Complete Documentation Overhaul - -**New Documentation Hub** (`src/modules/bmm/docs/`) - -- Created centralized documentation system with 18 comprehensive guides (7000+ lines) -- Clear learning paths for greenfield, brownfield, and quick spec flows -- Professional technical writing standards throughout all documentation -- Reading time estimates and cross-referenced navigation - -**New Documentation Files:** - -- `README.md` - Complete documentation hub with topic navigation -- `quick-start.md` - 15-minute getting started guide -- `agents-guide.md` - Comprehensive 12-agent reference (45 min read) -- `party-mode.md` - Multi-agent collaboration guide (20 min read) -- `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) -- `brownfield-guide.md` - Existing codebase development (53 min read) -- `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) -- `workflows-analysis.md` - Phase 1 workflows deep-dive (12 min read) -- `workflows-planning.md` - Phase 2 workflows deep-dive (19 min read) -- `workflows-solutioning.md` - Phase 3 workflows deep-dive (13 min read) -- `workflows-implementation.md` - Phase 4 workflows deep-dive (33 min read) -- `workflows-testing.md` - Testing & QA workflows (29 min read) -- `workflow-architecture-reference.md` - Architecture workflow technical reference -- `workflow-document-project-reference.md` - Document-project workflow technical reference -- `enterprise-agentic-development.md` - Team collaboration patterns -- `faq.md` - Comprehensive Q&A covering all common questions -- `glossary.md` - Complete BMM terminology reference -- `troubleshooting.md` - Common issues and solutions guide - -**Documentation Improvements:** - -- Removed version/date footers (git handles versioning automatically) -- Agent customization docs now include full rebuild process -- Consistent professional formatting and structure across all docs -- Better separation of user documentation vs developer reference - -### ๐Ÿค– New Agent: Paige (Documentation Guide) - -Introduced Paige, a specialized technical documentation agent: - -- **Expertise:** Professional technical writing, information architecture, documentation structure -- **Integration:** Available across all BMM phases for continuous documentation support -- **Customizable:** Like all BMM agents, can be customized via sidecar files -- **Status:** Work in progress - will evolve as documentation needs grow - -### ๐Ÿš€ Quick Spec Flow - Intelligent Level 0-1 Planning - -**Major Tech-Spec Workflow Transformation:** - -- Transformed from template-filling into context-aware intelligent planning system -- Ideal for bug fixes, single endpoint additions, and small isolated changes -- Auto-detects project stack (package.json, requirements.txt, etc.) -- Analyzes brownfield codebases for conventions and patterns -- Integrates WebSearch for current framework versions and best practices - -**Context-Aware Intelligence:** - -- Interactive level detection (Level 0 vs Level 1) -- Brownfield convention detection with user confirmation -- Comprehensive context discovery (stack, patterns, dependencies, test frameworks) -- Auto-validation with quality scoring (no manual checklist needed) -- UX/UI considerations capture for user-facing changes - -**Enhanced Tech-Spec Template:** - -- Expanded from 8 to 23 sections for complete planning context -- New sections: Development Context, UX/UI Considerations, Integration Points -- Developer Resources section with file paths and testing guidance -- All sections populated via template-output tags during workflow - -**Story Generation Improvements:** - -- Level 0: Extract single story from comprehensive tech-spec -- Level 1: Story sequence validation with acceptance criteria quality checks -- User Story Template includes Dev Agent Record sections for implementation tracking -- Complete epic template rewrite with proper variable structure - -**Phase 4 Integration:** - -- Story Context and Create Story workflows now recognize tech-spec as authoritative source -- Seamless integration between Quick Spec Flow and traditional BMM workflows -- Tech-spec provides brownfield analysis, framework details, and existing patterns - -### ๐Ÿ“ฆ Universal Document Sharding - -**New Capability: Shard-Doc Workflow** - -- Split large markdown documents into organized, smaller files based on sections -- Dual-strategy loading: include individual shards OR single large document -- Configurable section level (default: level 2 headings) -- Automatic index.md generation with navigation links -- Ideal for large guides, API documentation, and knowledge bases - -**Use Cases:** - -- Breaking down massive planning documents for better context management -- Creating navigable documentation hierarchies -- Managing agent knowledge bases efficiently -- Optimizing context window usage during development - -**Integration:** - -- Available as BMad Core workflow: `/bmad:core:tools:shard-doc` -- Works with any markdown document in your project -- Preserves original file with automatic backups -- Generated shards maintain formatting and structure - -### ๐Ÿ”ง Planning Workflow Enhancements - -**Intent-Driven Discovery (Product Brief & PRD):** - -- Transformed from rigid template-filling to natural conversational discovery -- Adaptive questioning based on project context (hobby/startup/enterprise) -- Real-time document building instead of end-of-session generation -- Skill-level aware facilitation (expert/intermediate/beginner) -- Context detection from user responses to guide exploration depth - -**Product Brief Workflow (96% BMAD v6 compliance):** - -- Intent-driven facilitation with context-appropriate probing -- Living document approach with continuous template updates -- Enhanced discovery areas: problem exploration, solution vision, user understanding -- Ruthless MVP scope management with feature prioritization -- Template improvements with context-aware conditional sections - -**PRD Workflow (improved from 65% to 85%+ compliance):** - -- Fixed critical config issues (missing date variable, status file extension mismatch) -- Scale-adaptive intelligence with project type detection (API/Web App/Mobile/SaaS) -- Domain complexity mapping (14 domain types with specialized considerations) -- Enhanced requirements coverage: project-type specific sections, domain considerations -- Separated epic planning into dedicated create-epics-and-stories child workflow - -**Architecture Workflow:** - -- Better integration with PRD outputs -- Domain complexity context support -- Enhanced technical decision capture framework - -### ๐Ÿ› ๏ธ Research Workflow Improvements - -**Enhanced Research Capabilities:** - -- Updated to use web search more frequently for current information -- Better understanding of current date context for finding latest documentation -- Improved deep research prompt generation options -- More accurate and up-to-date research results - -### ๐ŸŽจ User Experience Improvements - -**Installer Updates:** - -- Improved installation notes and guidance -- Better command examples (shard-doc uses npx command pattern) - -**Workflow Cleanup:** - -- Removed unused voice hooks functionality -- Cleaned up backup and temporary files -- Better workflow naming consistency - -### ๐Ÿ“‹ Infrastructure & Quality - -**Agent & Workflow Manifests:** - -- Added Paige to agent manifest -- Updated workflow manifest with new and restructured workflows -- Better workflow-to-agent mappings across all documentation -- Updated files manifest with all new documentation - -**Module Organization:** - -- Streamlined BMM README to lean signpost format -- Polished root README with better hierarchy and clear CTAs -- Moved documentation from root `docs/` to module-specific locations -- Better separation of user docs vs developer reference - -**Data Infrastructure:** - -- New CSV data files for project types and domain complexity -- Enhanced workflow configuration with runtime variables -- Better template variable mapping and tracking - -### ๐Ÿ”„ Breaking Changes - -**File Removals:** - -- Removed `src/modules/bmm/workflows/2-plan-workflows/prd/epics-template.md` (replaced by create-epics-and-stories child workflow) - -**Workflow Trigger Changes:** - -- PM agent: `prd` โ†’ `create-prd` -- New workflow triggers: `create-epics-and-stories`, `validate-prd` -- Game Designer agent triggers renamed for consistency - -### ๐Ÿ“– What's Next (Beta Roadmap) - -- Knowledge base integration for enhanced context management -- Web bundle functionality completion -- Additional specialized agents based on community feedback -- Enhanced multi-agent collaboration patterns -- Performance optimizations for large projects - ---- - -### Installation - -```bash -npx bmad-method@6.0.0-alpha.4 install -``` - -For upgrading from alpha.3: - -```bash -# Backup your customizations first -npx bmad-method@6.0.0-alpha.4 install -``` - -### Migration Notes - -If upgrading from v6.0.0-alpha.3: - -1. New documentation is available in `bmad/bmm/docs/` - review the README.md for navigation -2. Tech-spec workflow now has enhanced capabilities - review `docs/quick-spec-flow.md` -3. Product Brief and PRD workflows have new conversational approaches -4. Paige agent is now available for documentation tasks -5. No breaking changes to existing project structures - ---- +- **๐Ÿ“š Documentation Hub**: Created 18 comprehensive guides (7000+ lines) with professional technical writing standards +- **๐Ÿค– Paige Agent**: New technical documentation specialist available across all BMM phases +- **๐Ÿš€ Quick Spec Flow**: Intelligent Level 0-1 planning with auto-stack detection and brownfield analysis +- **๐Ÿ“ฆ Universal Shard-Doc**: Split large markdown documents into organized sections with dual-strategy loading +- **๐Ÿ”ง Intent-Driven Planning**: PRD and Product Brief transformed from template-filling to natural conversation ## [6.0.0-alpha.3] -### Codex Installer +**Release: October 2025** -- Codex installer uses custom prompts in `.codex/prompts/`, instead of `AGENTS.md` +- **Codex Installer**: Custom prompts in `.codex/prompts/` directory structure +- **Bug Fixes**: Various installer and workflow improvements +- **Documentation**: Initial documentation structure established ## [6.0.0-alpha.0] **Release: September 28, 2025** -Initial alpha release of a major rewrite and overhaul improvement of past versions. - -### Major New Features - -- **Lean Core**: The core of BMad is very simple - common tasks that apply to any future module or agents, along with common agents that will be added to any modules - bmad-web-orchestrator and bmad-master. -- **BMad Method**: The new BMad Method (AKA bmm) is a complete overhaul of the v4 method, now a fully scale adaptive rewrite. The workflow now scales from small enhancements to massive undertakings across multiple services or architectures, supporting a new vast array of project type, including a full subclass of game development specifics. -- **BoMB**: The BMad Builder (AKA BoMB) now is able to fully automate creation and conversion of expansion packs from v6 to modules in v6 along with the net new ideation and brainstorming through implementation and testing of net new Modules, Workflows (were tasks and templates), Module Agents, and Standalone Personal Agents -- **CIS**: The Creative Intelligence Suite (AKA CIS) - -## [v6.0.0] - SKIPPED - -**Note**: Version 5.0.0 was skipped due to NPX registry issues that corrupted the version. Development continues with v6.0.0-alpha.0. +- **Lean Core**: Simple common tasks and agents (bmad-web-orchestrator, bmad-master) +- **BMad Method (BMM)**: Complete scale-adaptive rewrite supporting projects from small enhancements to massive undertakings +- **BoMB**: BMad Builder for creating and converting modules, workflows, and agents +- **CIS**: Creative Intelligence Suite for ideation and creative workflows +- **Game Development**: Full subclass of game-specific development patterns**Note**: Version 5.0.0 was skipped due to NPX registry issues that corrupted the version. Development continues with v6.0.0-alpha.0. ## [v4.43.0](https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v4.43.0) diff --git a/README.md b/README.md index 5ce98f86..071eaa56 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# BMad CORE + BMad Method +# BMad Method & BMad Core [![Stable Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=stable)](https://www.npmjs.com/package/bmad-method) [![Alpha Version](https://img.shields.io/npm/v/bmad-method/alpha?color=orange&label=alpha)](https://www.npmjs.com/package/bmad-method) @@ -6,449 +6,207 @@ [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) -> **๐Ÿšจ Alpha Version Notice** -> -> v6-alpha is near-beta qualityโ€”stable and vastly improved over v4, but documentation is still being refined. New videos coming soon to the [BMadCode YouTube channel](https://www.youtube.com/@BMadCode)โ€”subscribe for updates! (There is no v5). -> -> **Getting Started:** -> -> - **Install v6 Alpha:** `npx bmad-method install` -> - **Install stable v4:** `npx bmad-method@latest install` -> - **Not sure what to do?** Load any agent and run `*workflow-init` for guided setup -> - **v4 Users:** [View v4 documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4) or [upgrade guide](./docs/v4-to-v6-upgrade.md) +## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise -## Universal Human-AI Collaboration Platform +**Build More, Architect Dreams** (BMAD) with **19 specialized AI agents** and **50+ guided workflows** that adapt to your project's complexityโ€”from quick bug fixes to enterprise platforms. -**BMad-CORE** (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities. +> **๐Ÿš€ v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new โ†’](#whats-new-in-v6) -The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but you can also use **BMad Builder** to create custom agents, workflows, and modules for any domainโ€”software development, business strategy, creativity, learning, and more. +> **๐Ÿ“Œ v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode). -**๐ŸŽฏ Human Amplification** โ€ข **๐ŸŽจ Domain Agnostic** โ€ข **โšก Agent-Powered** +## ๐ŸŽฏ Why BMad Method? -## Table of Contents +Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertiseโ€”from product management to architecture to testingโ€”working together seamlessly. -- [BMad CORE + BMad Method](#bmad-core--bmad-method) - - [Universal Human-AI Collaboration Platform](#universal-human-ai-collaboration-platform) - - [Table of Contents](#table-of-contents) - - [What is BMad-CORE?](#what-is-bmad-core) - - [v6 Core Enhancements](#v6-core-enhancements) - - [C.O.R.E. Philosophy](#core-philosophy) - - [Modules](#modules) - - [BMad Method (BMM) - AI-Driven Agile Development](#bmad-method-bmm---ai-driven-agile-development) - - [v6 Highlights](#v6-highlights) - - [๐Ÿš€ Quick Start](#-quick-start) - - [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions) - - [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity) - - [Installation](#installation) - - [๐ŸŽฏ Working with Agents \& Commands](#-working-with-agents--commands) - - [Method 1: Agent Menu (Recommended for Beginners)](#method-1-agent-menu-recommended-for-beginners) - - [Method 2: Direct Slash Commands](#method-2-direct-slash-commands) - - [Method 3: Party Mode Execution](#method-3-party-mode-execution) - - [Key Features](#key-features) - - [๐ŸŽจ Update-Safe Customization](#-update-safe-customization) - - [๐Ÿš€ Intelligent Installation](#-intelligent-installation) - - [๐Ÿ“ Clean Architecture](#-clean-architecture) - - [๐Ÿ“„ Document Sharding (Advanced)](#-document-sharding-advanced) - - [Documentation](#documentation) - - [Community \& Support](#community--support) - - [Development \& Quality Checks](#development--quality-checks) - - [Testing \& Validation](#testing--validation) - - [Code Quality](#code-quality) - - [Build \& Development](#build--development) - - [Contributing](#contributing) - - [License](#license) +**โœจ Key Benefits:** ---- +- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems +- **Complete Development Lifecycle** - Analysis โ†’ Planning โ†’ Architecture โ†’ Implementation +- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.) +- **Proven Methodologies** - Built on agile best practices with AI amplification +- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code -## What is BMad-CORE? +## ๐Ÿ—๏ธ The Power of BMad Core -Foundation framework powering all BMad modules: +**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means: -- **Agent Orchestration** - Specialized AI personas with domain expertise -- **Workflow Engine** - Guided multi-step processes with built-in best practices -- **Modular Architecture** - Extend with domain-specific modules (BMM, BMB, CIS, custom) -- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code, and more -- **Update-Safe Customization** - Your configs persist through all updates +- **BMad Core** provides the universal framework for human-AI collaboration +- **BMad Method** leverages Core to deliver agile development workflows +- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself -### v6 Core Enhancements +With **BMad Builder**, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace**. Imagine building and sharing your own specialized AI team! -- **๐ŸŽจ Agent Customization** - Modify names, roles, personalities via `{bmad_folder}/_cfg/agents/` **[โ†’ Customization Guide](./docs/agent-customization-guide.md)** -- **๐ŸŒ Multi-Language** - Independent language settings for communication and output -- **๐Ÿ‘ค Personalization** - Agents adapt to your name, skill level, and preferences -- **๐Ÿ”„ Persistent Config** - Customizations survive module updates -- **โš™๏ธ Flexible Settings** - Configure per-module or globally -- **๐Ÿ“ฆ Web Bundles** - Share agents in Gemini Gems and Custom GPTs **[โ†’ Web Bundles Guide](./docs/web-bundles-gemini-gpt-guide.md)** +## ๐Ÿ“Š See It In Action -### C.O.R.E. Philosophy +

+ BMad Method Workflow +

-- **C**ollaboration: Human-AI partnership leveraging complementary strengths -- **O**ptimized: Battle-tested processes for maximum effectiveness -- **R**eflection: Strategic questioning that unlocks breakthrough solutions -- **E**ngine: Framework orchestrating 19+ specialized agents and 50+ workflows +

+ Complete BMad Method workflow showing all phases, agents, and decision points +

-BMad-CORE doesn't give you answersโ€”it helps you **discover better solutions** through guided reflection. +## ๐Ÿš€ Get Started in 3 Steps -## Modules - -### BMad Method (BMM) - AI-Driven Agile Development - -Revolutionary AI-driven agile framework for software and game development. Automatically adapts from single bug fixes to enterprise-scale systems. - -#### v6 Highlights - -**๐ŸŽฏ Scale-Adaptive Intelligence (3 Planning Tracks)** - -Automatically adjusts planning depth and documentation based on project needs: - -- **Quick Flow Track:** Fast implementation (tech-spec only) - bug fixes, small features, clear scope -- **BMad Method Track:** Full planning (PRD + Architecture + UX) - products, platforms, complex features -- **Enterprise Method Track:** Extended planning (BMad Method + Security/DevOps/Test) - enterprise requirements, compliance - -**๐Ÿ—๏ธ Four-Phase Methodology** - -1. **Phase 1: Analysis** (Optional) - Brainstorming, research, product briefs -2. **Phase 2: Planning** (Required) - Scale-adaptive PRD/tech-spec/GDD -3. **Phase 3: Solutioning** (Track-dependent) - Architecture, (Coming soon: security, DevOps, test strategy) -4. **Phase 4: Implementation** (Iterative) - Story-centric development with just-in-time context - -> **๐Ÿ“Š [View Complete Workflow Diagram](./src/modules/bmm/docs/images/workflow-method-greenfield.svg)** - Visual flowchart showing all phases, agents, and decision points for the BMad Method (Standard Greenfield track) - -**๐Ÿค– 12 Specialized Agents** - -PM โ€ข Analyst โ€ข Architect โ€ข Scrum Master โ€ข Developer โ€ข Test Architect (TEA) โ€ข UX Designer โ€ข Technical Writer โ€ข Game Designer โ€ข Game Developer โ€ข Game Architect โ€ข BMad Master (Orchestrator) - -**๐Ÿ“š Documentation** - -- **[Complete Documentation Hub](./src/modules/bmm/docs/README.md)** - Start here for all BMM guides -- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - Get building in 15 minutes -- **[Agents Guide](./src/modules/bmm/docs/agents-guide.md)** - Meet all 12 agents (45 min read) -- **[34 Workflow Guides](./src/modules/bmm/docs/README.md#-workflow-guides)** - Complete phase-by-phase reference -- **[BMM Module Overview](./src/modules/bmm/README.md)** - Module structure and quick links - ---- - -## ๐Ÿš€ Quick Start - -**After installation** (see [Installation](#installation) below), choose your path: - -**Three Planning Tracks:** - -1. **โšก Quick Flow Track** - Bug fixes and small features - - ๐Ÿ› Bug fixes in minutes - - โœจ Small features (2-3 related changes) - - ๐Ÿš€ Rapid prototyping - - **[โ†’ Quick Spec Flow Guide](./src/modules/bmm/docs/quick-spec-flow.md)** - -2. **๐Ÿ“‹ BMad Method Track** - Products and platforms - - Complete planning (PRD/GDD) - - Architecture decisions - - Story-centric implementation - - **[โ†’ Complete Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - -3. **๐Ÿข Brownfield Projects** - Add to existing codebases - - Document existing code first - - Then choose Quick Flow or BMad Method - - **[โ†’ Brownfield Guide](./src/modules/bmm/docs/brownfield-guide.md)** - -**Not sure which path?** Run `*workflow-init` and let BMM analyze your project goal and recommend the right track. - -**[๐Ÿ“š Learn More: Scale Adaptive System](./src/modules/bmm/docs/scale-adaptive-system.md)** - How BMM adapts across three planning tracks - ---- - -### BMad Builder (BMB) - Create Custom Solutions - -Build your own agents, workflows, and modules using the BMad-CORE framework. - -**What You Can Build:** - -- **Custom Agents** - Domain experts with specialized knowledge -- **Guided Workflows** - Multi-step processes for any task -- **Complete Modules** - Full solutions for specific domains -- **Three Agent Types** - Full module, hybrid, or standalone - -**Perfect For:** Creating domain-specific solutions (legal, medical, finance, education, creative, etc.) or extending BMM with custom development workflows. - -**Install Custom Agents:** +### 1. Install BMad Method ```bash -# Install and personalize standalone agents -npx bmad agent-install -``` - -Includes reference agents you can copy, customize, and install with personalized behavior. **[โ†’ Custom Agent Installation Guide](./docs/custom-agent-installation.md)** - -**Documentation:** - -- **[BMB Module Overview](./src/modules/bmb/README.md)** - Complete reference -- **[Custom Agent Installation](./docs/custom-agent-installation.md)** - Install standalone simple and expert agents -- **[Create Agent Workflow](./src/modules/bmb/workflows/create-agent/README.md)** - Build custom agents -- **[Create Workflow](./src/modules/bmb/workflows/create-workflow/README.md)** - Design guided processes -- **[Create Module](./src/modules/bmb/workflows/create-module/README.md)** - Package complete solutions - -### Creative Intelligence Suite (CIS) - Innovation & Creativity - -AI-powered creative facilitation using proven methodologies and techniques. - -**5 Interactive Workflows:** - -- **Brainstorming** - Generate and refine ideas with 30+ techniques -- **Design Thinking** - Human-centered problem solving -- **Problem Solving** - Systematic breakthrough techniques -- **Innovation Strategy** - Disruptive business model thinking -- **Storytelling** - Compelling narrative frameworks - -**5 Specialized Agents:** Each with unique facilitation styles and domain expertise - -**Shared Resource:** CIS workflows are used by other modules (BMM's `brainstorm-project` uses CIS brainstorming) - -**Documentation:** - -- **[CIS Module Overview](./src/modules/cis/README.md)** - Complete reference -- **[CIS Workflows Guide](./src/modules/cis/workflows/README.md)** - All 5 creative workflows - ---- - -## Installation - -**Prerequisites:** Node.js v20+ ([Download](https://nodejs.org)) - -```bash -# v6 Alpha (recommended for new projects) +# Install v6 Alpha (recommended) npx bmad-method@alpha install -# Stable v4 (production) +# Or stable v4 for production npx bmad-method install ``` -The installer provides: +### 2. Initialize Your Project -1. **Module Selection** - Choose BMM, BMB, CIS (or all) -2. **Configuration** - Your name, language preferences, game dev options -3. **IDE Integration** - Automatic setup for your IDE - -**Installation creates:** +Load any agent in your IDE and run: ``` -your-project/ -โ””โ”€โ”€ {bmad_folder}/ - โ”œโ”€โ”€ core/ # Core framework + BMad Master agent - โ”œโ”€โ”€ bmm/ # BMad Method (12 agents, 34 workflows) - โ”œโ”€โ”€ bmb/ # BMad Builder (1 agent, 7 workflows) - โ”œโ”€โ”€ cis/ # Creative Intelligence (5 agents, 5 workflows) - โ””โ”€โ”€ _cfg/ # Your customizations (survives updates) - โ””โ”€โ”€ agents/ # Agent customization files +*workflow-init ``` -**Next Steps:** +This analyzes your project and recommends the right workflow track. -1. Load any agent in your IDE -2. Run `*workflow-init` to set up your project workflow path -3. Follow the [Quick Start](#-quick-start) guide above to choose your planning track +### 3. Choose Your Track -**Alternative:** [**Web Bundles**](https://bmad-code-org.github.io/bmad-bundles/) - Download pre-built agent bundles for use in Claude Projects, ChatGPT, or Gemini without installation (automatically updated on every commit to main) +BMad Method adapts to your needs with three intelligent tracks: ---- +| Track | Use For | Planning | Time to Start | +| ------------------ | ------------------------- | ----------------------- | ------------- | +| **โšก Quick Flow** | Bug fixes, small features | Tech spec only | < 5 minutes | +| **๐Ÿ“‹ BMad Method** | Products, platforms | PRD + Architecture + UX | < 15 minutes | +| **๐Ÿข Enterprise** | Compliance, scale | Full governance suite | < 30 minutes | -## ๐ŸŽฏ Working with Agents & Commands +> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal. -**Multiple Ways to Execute Workflows:** +## ๐Ÿ”„ How It Works: 4-Phase Methodology -BMad is flexible - you can execute workflows in several ways depending on your preference and IDE: +BMad Method guides you through a proven development lifecycle: -### Method 1: Agent Menu (Recommended for Beginners) +1. **๐Ÿ“Š Analysis** (Optional) - Brainstorm, research, and explore solutions +2. **๐Ÿ“ Planning** - Create PRDs, tech specs, or game design documents +3. **๐Ÿ—๏ธ Solutioning** - Design architecture, UX, and technical approach +4. **โšก Implementation** - Story-driven development with continuous validation -1. **Load an agent** in your IDE (see [IDE-specific instructions](./docs/ide-info/)) -2. **Wait for the menu** to appear showing available workflows -3. **Tell the agent** what to run using natural language or shortcuts: - - Natural: "Run workflow-init" - - Shortcut: `*workflow-init` - - Menu number: "Run option 2" +Each phase has specialized workflows and agents working together to deliver exceptional results. -### Method 2: Direct Slash Commands +## ๐Ÿค– Meet Your Team -**Execute workflows directly** using slash commands: +**12 Specialized Agents** working in concert: -``` -/bmad:bmm:workflows:workflow-init -/bmad:bmm:workflows:prd -/bmad:bmm:workflows:dev-story -``` +| Development | Architecture | Product | Leadership | +| ----------- | -------------- | ------------- | -------------- | +| Developer | Architect | PM | Scrum Master | +| UX Designer | Test Architect | Analyst | BMad Master | +| Tech Writer | Game Architect | Game Designer | Game Developer | -**Tip:** While you can run these without loading an agent first, **loading an agent is still recommended** - it can make a difference with certain workflows. +Each agent brings deep expertise and can be customized to match your team's style. -**Benefits:** +## ๐Ÿ“ฆ What's Included -- โœ… Mix and match any agent with any workflow -- โœ… Run workflows not in the loaded agent's menu -- โœ… Faster access for experienced users who know the command names +### Core Modules -### Method 3: Party Mode Execution +- **BMad Method (BMM)** - Complete agile development framework + - 12 specialized agents + - 34 workflows across 4 phases + - Scale-adaptive planning + - [โ†’ Documentation Hub](./src/modules/bmm/docs/README.md) -**Run workflows with multi-agent collaboration:** +- **BMad Builder (BMB)** - Create custom agents and workflows + - Build anything from simple agents to complex modules + - Create domain-specific solutions (legal, medical, finance, education) + - Share your creations in the upcoming community marketplace + - [โ†’ Builder Guide](./src/modules/bmb/README.md) -1. Start party mode: `/bmad:core:workflows:party-mode` -2. Execute any workflow - **the entire team collaborates on it** -3. Get diverse perspectives from multiple specialized agents +- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving + - Brainstorming, design thinking, storytelling + - 5 creative facilitation workflows + - [โ†’ Creative Workflows](./src/modules/cis/README.md) -**Perfect for:** Strategic decisions, complex workflows, cross-functional tasks +### Key Features ---- +- **๐ŸŽจ Customizable Agents** - Modify personalities, expertise, and communication styles +- **๐ŸŒ Multi-Language Support** - Separate settings for communication and code output +- **๐Ÿ“„ Document Sharding** - 90% token savings for large projects +- **๐Ÿ”„ Update-Safe** - Your customizations persist through updates +- **๐Ÿš€ Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems -> **๐Ÿ“Œ IDE-Specific Note:** -> -> Slash command format varies by IDE: -> -> - **Claude Code:** `/bmad:bmm:workflows:prd` -> - **Cursor/Windsurf:** May use different syntax - check your IDE's [documentation](./docs/ide-info/) -> - **VS Code with Copilot Chat:** Syntax may differ -> -> See **[IDE Integration Guides](./docs/ide-info/)** for your specific IDE's command format. +## ๐Ÿ“š Documentation ---- +### Quick Links -## Key Features +- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction +- **[Complete BMM Documentation](./src/modules/bmm/docs/README.md)** - All guides and references +- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents +- **[All Documentation](./docs/index.md)** - Complete documentation index -### ๐ŸŽจ Update-Safe Customization +### For v4 Users -Modify agents without touching core files: +- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** +- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** -- Override agent names, personalities, expertise via `{bmad_folder}/_cfg/agents/` -- Customizations persist through all updates -- Multi-language support (communication + output) -- Module-level or global configuration +## ๐Ÿ’ฌ Community & Support -### ๐Ÿš€ Intelligent Installation +- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects +- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features +- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and demos +- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles -Smart setup that adapts to your environment: +## ๐Ÿ› ๏ธ Development -- Auto-detects v4 installations for smooth upgrades -- Configures IDE integrations (Claude Code, Cursor, Windsurf, VS Code) -- Resolves cross-module dependencies -- Generates unified agent/workflow manifests - -### ๐Ÿ“ Clean Architecture - -Everything in one place: - -- Single `{bmad_folder}/` folder (no scattered files, default folder name is .bmad) -- Modules live side-by-side (core, bmm, bmb, cis) -- Your configs in `_cfg/` (survives updates) -- Easy to version control or exclude - -### ๐Ÿ“„ Document Sharding (Advanced) - -Optional optimization for large projects (BMad Method and Enterprise tracks): - -- **Massive Token Savings** - Phase 4 workflows load only needed sections (90%+ reduction) -- **Automatic Support** - All workflows handle whole or sharded documents seamlessly -- **Easy Setup** - Built-in tool splits documents by headings -- **Smart Discovery** - Workflows auto-detect format - -**[โ†’ Document Sharding Guide](./docs/document-sharding-guide.md)** - ---- - -## Documentation - -**Module Documentation:** - -- **[BMM Complete Documentation Hub](./src/modules/bmm/docs/README.md)** - All BMM guides, FAQs, troubleshooting -- **[BMB Module Reference](./src/modules/bmb/README.md)** - Build custom agents and workflows -- **[CIS Workflows Guide](./src/modules/cis/workflows/README.md)** - Creative facilitation workflows - -**Customization & Sharing:** - -- **[Agent Customization Guide](./docs/agent-customization-guide.md)** - Customize agent names, personas, and behaviors -- **[Web Bundles for Gemini & GPT](./docs/web-bundles-gemini-gpt-guide.md)** - Use BMad agents in Gemini Gems and Custom GPTs - -**Additional Resources:** - -- **[Documentation Index](./docs/index.md)** - All project documentation -- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions -- **[CLI Tool Guide](./tools/cli/README.md)** - Installer and build tool reference -- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute - ---- - -## Community & Support - -- ๐Ÿ’ฌ **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects (#general-dev, #bugs-issues) -- ๐Ÿ› **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features -- ๐ŸŽฅ **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs -- โญ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Stay updated on releases - ---- - -## Development & Quality Checks - -**For contributors working on the BMAD codebase:** - -**Requirements:** Node.js 22+ (see `.nvmrc`). Run `nvm use` to switch to the correct version. - -### Testing & Validation +For contributors working on the BMad codebase: ```bash -# Run all quality checks (comprehensive - use before pushing) +# Run all quality checks npm test -# Individual test suites -npm run test:schemas # Agent schema validation (fixture-based) -npm run test:install # Installation component tests (compilation) -npm run validate:schemas # YAML schema validation -npm run validate:bundles # Web bundle integrity +# Development commands +npm run lint # Check code style +npm run format:fix # Auto-format code +npm run bundle # Build web bundles ``` -### Code Quality +See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines. -```bash -# Lint check -npm run lint +## What's New in v6 -# Auto-fix linting issues -npm run lint:fix +**v6 represents a complete architectural revolution from v4:** -# Format check -npm run format:check +### ๐Ÿš€ Major Upgrades -# Auto-format all files -npm run format:fix -``` +- **BMad Core Framework** - Modular architecture enabling custom domain solutions +- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise +- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology +- **BMad Builder Module** - Create and share your own AI agent teams +- **50+ Workflows** - Up from 20 in v4, covering every development scenario +- **19 Specialized Agents** - Enhanced with customizable personalities and expertise +- **Update-Safe Customization** - Your configs persist through all updates +- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini +- **Multi-Language Support** - Separate settings for communication and code +- **Document Sharding** - 90% token savings for large projects -### Build & Development +### ๐Ÿ”„ For v4 Users -```bash -# Bundle for web deployment -npm run bundle +- **[Comprehensive Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Step-by-step migration +- **[v4 Documentation Archive](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** - Legacy reference +- Backwards compatibility where possible +- Smooth migration path with installer detection -# Test local installation -npm run install:bmad -``` +## ๐Ÿ“„ License -**Pre-commit Hook:** Auto-fixes changed files (lint-staged) + validates everything (npm test) -**CI:** GitHub Actions runs all quality checks in parallel on every PR - ---- - -## Contributing - -We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for: - -- Code contribution guidelines -- Documentation improvements -- Module development -- Issue reporting - ---- - -## License - -**MIT License** - See [LICENSE](LICENSE) for details +MIT License - See [LICENSE](LICENSE) for details. **Trademarks:** BMADโ„ข and BMAD-METHODโ„ข are trademarks of BMad Code, LLC. --- -[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors) +

+ + Contributors + +

-Built with โค๏ธ for the human-AI collaboration community +

+ Built with โค๏ธ for the human-AI collaboration community +