## The Tale of the Frame Expert
Once upon a time, BMad Method had a specialized agent called Frame Expert.
This agent was the master of all visual artifacts - flowcharts, diagrams,
wireframes, data flows. Whenever anyone needed a diagram, they called upon
Frame Expert. The agent lived in its own isolated domain with four dedicated
workflows and a library of shared templates.
## The Awakening
But something felt wrong. Teams using BMad Method were meant to mirror real
agile teams - Product Managers, Architects, UX Designers, Tech Writers,
Developers. Each agent represented an authentic role you'd find in any
software team.
Except Frame Expert.
No real agile team has a "Frame Expert" or "Diagram Specialist" who creates
all visual artifacts. In real teams, Architects diagram system architecture.
PMs flowchart processes. UX Designers wireframe interfaces. Tech Writers
create documentation diagrams. The visuals emerge from the domain experts
who need them, not from a centralized diagram factory.
Frame Expert was an abstraction that made technical sense but violated the
very soul of BMad Method - authentic agile role modeling.
## The Transformation
And so Frame Expert was dissolved, its knowledge distributed to those who
truly needed it:
**The Architect** inherited system architecture diagrams and data flows -
the blueprints of technical systems they design.
**The Product Manager** received process flowcharts - the visual maps of
features and workflows they orchestrate.
**The UX Designer** claimed wireframes - the interface sketches that bring
their vision to life.
**The Tech Writer** gained all diagram types - the visual aids that clarify
their documentation.
Each agent now creates diagrams in their domain, using their expertise,
serving their purpose.
## The Shared Knowledge
But the wisdom of diagram creation itself - the Excalidraw templates, the
component libraries, the validation patterns - this knowledge was too
valuable to scatter. It was elevated to core resources, where both BMM
agents AND the new CIS presentation-master agent could draw upon it.
Shared infrastructure for common needs. Distributed execution for domain
expertise.
## The Ripple Effects
With diagrams now properly distributed, other misalignments became visible:
Epic creation was happening in Phase 2 (Planning), before Architecture
existed. But epics need architectural context - API contracts, data models,
technical decisions. So epic creation migrated to Phase 3 (Solutioning),
after Architecture provides that foundation.
Workflow paths were updated. Documentation gained visual flowcharts showing
the complete journey. Agent naming standards were clarified - filenames are
stable roles, persona names are user dreams.
## What Changed
**Removed:**
- frame-expert.agent.yaml (the centralized specialist)
- All frame-expert workflows and shared resources
- Phase 2 epic creation workflow (wrong timing)
- game-design workflow path (consolidated to method track)
- v6-open-items.md (planning doc, now complete)
**Distributed Diagram Capabilities:**
- Architect: create-excalidraw-diagram, create-excalidraw-dataflow
- PM: create-excalidraw-flowchart
- Tech Writer: create-excalidraw-{diagram,dataflow,flowchart}, generate-mermaid
- UX Designer: create-excalidraw-wireframe
**Created:**
- src/core/resources/ (shared diagram context for all modules)
- src/modules/cis/agents/presentation-master.agent.yaml (visual comms specialist)
- src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/ (epic creation's new home)
- src/modules/bmm/workflows/diagrams/ (distributed diagram implementations)
- src/modules/bmm/docs/images/ (workflow visualization assets)
**Enhanced:**
- All agent definitions with domain-appropriate diagram workflows
- Documentation with embedded workflow diagrams and visual guides
- Agent compilation docs with critical naming convention rules
- All 4 workflow paths (enterprise/method × brownfield/greenfield)
**Fixed:**
- Epic creation now in Phase 3 after Architecture
- Story context path variables in BMGD module
- PRD workflow descriptions (epics moved to Phase 3)
## For Users
The Frame Expert commands are gone. In their place:
- Need architecture diagrams? Ask `/architect`
- Need process flows? Ask `/pm`
- Need wireframes? Ask `/ux-designer`
- Need documentation visuals? Ask `/tech-writer`
Each expert creates diagrams in their domain, with their context, using
their judgment.
This is how real teams work.
## Overview
This commit represents a complete overhaul of the BMAD agent creation system, establishing clear standards for agent development, installation workflows, and persona design. The changes span documentation, tooling, reference implementations, and field-specific guidance.
## Key Components
### 1. Agent Installation Infrastructure
**New CLI Command: `agent-install`**
- Interactive agent installation with persona customization
- Supports Simple (single YAML), Expert (sidecar files), and Module agents
- Template variable processing with Handlebars-style syntax
- Automatic compilation from YAML to XML (.md) format
- Manifest tracking and IDE integration (Claude Code, Cursor, Windsurf, etc.)
- Source preservation in `_cfg/custom/agents/` for reinstallation
**Files Created:**
- `tools/cli/commands/agent-install.js` - Main CLI command
- `tools/cli/lib/agent/compiler.js` - YAML to XML compilation engine
- `tools/cli/lib/agent/installer.js` - Installation orchestration
- `tools/cli/lib/agent/template-engine.js` - Handlebars template processing
**Compiler Features:**
- Auto-injects frontmatter, activation, handlers, help/exit menu items
- Smart handler inclusion (only includes action/workflow/exec/tmpl handlers actually used)
- Proper XML escaping and formatting
- Persona name customization (e.g., "Fred the Commit Poet")
### 2. Documentation Overhaul
**Deleted Bloated/Outdated Docs (2,651 lines removed):**
- Old verbose architecture docs
- Redundant pattern files
- Outdated workflow guides
**Created Focused, Type-Specific Docs:**
- `src/modules/bmb/docs/understanding-agent-types.md` - Architecture vs capability distinction
- `src/modules/bmb/docs/simple-agent-architecture.md` - Self-contained agents
- `src/modules/bmb/docs/expert-agent-architecture.md` - Agents with sidecar files
- `src/modules/bmb/docs/module-agent-architecture.md` - Workflow-integrated agents
- `src/modules/bmb/docs/agent-compilation.md` - YAML → XML process
- `src/modules/bmb/docs/agent-menu-patterns.md` - Menu design patterns
- `src/modules/bmb/docs/index.md` - Documentation hub
**Net Result:** ~1,930 line reduction while adding MORE value through focused content
### 3. Create-Agent Workflow Enhancements
**Critical Persona Field Guidance Added to Step 4:**
Explains how the LLM interprets each persona field when the agent activates:
- **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, quirks, 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 restate role/identity/principles. The `communication-presets.csv` provides 60 pure communication styles with NO role/identity/principles mixed in.
**Files Updated:**
- `src/modules/bmb/workflows/create-agent/instructions.md` - Added persona field interpretation guide
- `src/modules/bmb/workflows/create-agent/brainstorm-context.md` - Refined to 137 lines
- `src/modules/bmb/workflows/create-agent/communication-presets.csv` - 60 styles across 13 categories
### 4. Reference Agent Cleanup
**Removed install_config Personality Bloat:**
Understanding: Future installer will handle personality customization, so stripped all personality toggles from reference agents.
**commit-poet.agent.yaml** (Simple Agent):
- BEFORE: 36 personality combinations (3 enthusiasm × 3 depths × 4 styles) = decision fatigue
- AFTER: Single concise persona with pure communication style
- Changed from verbose conditionals to: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
- Reduction: 248 lines → 153 lines (38% reduction)
**journal-keeper.agent.yaml** (Expert Agent):
- Stripped install_config, simplified communication_style
- Shows proper Expert agent structure with sidecar files
**security-engineer.agent.yaml & trend-analyst.agent.yaml** (Module Agents):
- Added header comments explaining WHY Module Agent (design intent, not just location)
- Clarified: Module agents are designed FOR ecosystem integration, not capability-limited
**Files Updated:**
- `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
- `src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml`
### 5. BMM Agent Voice Enhancement
**Gave all 9 BMM agents distinct, memorable communication voices:**
**Mary (analyst)** - The favorite! Changed from generic "systematic and probing" to:
"Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."
**Other Notable Voices:**
- **John (pm):** "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
- **Winston (architect):** "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
- **Amelia (dev):** "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
- **Bob (sm):** "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
- **Sally (ux-designer):** "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
**Pattern Applied:** Moved behaviors from communication_style to principles, keeping communication_style as PURE verbal patterns.
**Files Updated:**
- `src/modules/bmm/agents/analyst.agent.yaml`
- `src/modules/bmm/agents/pm.agent.yaml`
- `src/modules/bmm/agents/architect.agent.yaml`
- `src/modules/bmm/agents/dev.agent.yaml`
- `src/modules/bmm/agents/sm.agent.yaml`
- `src/modules/bmm/agents/tea.agent.yaml`
- `src/modules/bmm/agents/tech-writer.agent.yaml`
- `src/modules/bmm/agents/ux-designer.agent.yaml`
- `src/modules/bmm/agents/frame-expert.agent.yaml`
### 6. Linting Fixes
**ESLint Compliance:**
- Replaced all `'utf-8'` with `'utf8'` (unicorn/text-encoding-identifier-case)
- Changed `variables.hasOwnProperty(varName)` to `Object.hasOwn(variables, varName)` (unicorn/prefer-object-has-own)
- Replaced `JSON.parse(JSON.stringify(...))` with `structuredClone(...)` (unicorn/prefer-structured-clone)
- Fixed empty YAML mapping values in sample files
**Files Fixed:**
- 7 JavaScript files across agent tooling (compiler, installer, commands, IDE integration)
- 1 YAML sample file
## Architecture Decisions
### Agent Types Are About Architecture, Not Capability
- **Simple:** Self-contained in single YAML (NOT limited in capability)
- **Expert:** Includes sidecar files (templates, docs, etc.)
- **Module:** Designed for BMAD ecosystem integration (workflows, cross-agent coordination)
### Persona Field Separation Critical for LLM Interpretation
The LLM needs distinct fields to understand its role:
- Mixing role/identity/principles into communication_style confuses the persona
- Pure communication styles (from communication-presets.csv) have ZERO role/identity/principles content
- Example DON'T: "Experienced analyst who uses systematic approaches..." (mixing identity + style)
- Example DO: "Systematic and probing. Structures findings hierarchically." (pure style)
### Install-Time vs Runtime Configuration
- Template variables ({{var}}) resolve at compile-time
- Runtime variables ({user_name}, {bmad_folder}) resolve when agent activates
- Future installer will handle personality customization, so agents should ship with single default persona
## Testing
- All linting passes (ESLint with max-warnings=0)
- Agent compilation tested with commit-poet, journal-keeper examples
- Install workflow validated with Simple and Expert agent types
- Manifest tracking and IDE integration verified
## Impact
This establishes BMAD as having a complete, production-ready agent creation and installation system with:
- Clear documentation for all agent types
- Automated compilation and installation
- Strong persona design guidance
- Reference implementations showing best practices
- Distinct, memorable agent voices throughout BMM module
Co-Authored-By: BMad Builder <builder@bmad.dev>
Co-Authored-By: Mary the Analyst <analyst@bmad.dev>
Co-Authored-By: Paige the Tech Writer <tech-writer@bmad.dev>
Remove hardcoded .bmad folder references throughout documentation and source files, replacing them with the configurable {bmad_folder} placeholder. This change enables users to customize the BMAD installation folder name via configuration, improving flexibility and reducing coupling to a specific directory structure.
Changes include:
- Update all documentation to reference {bmad_folder} instead of .bmad
- Remove legacy configuration files from .bmad and .claude directories
- Update workflow.xml and CLI documentation with new placeholder syntax
This commit extracts game development functionality from BMM into a standalone
BMGD (BMad Game Development) module and implements workflow vendoring to enable
module independence.
BMGD Module Creation:
- 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 workflows into industry-standard game dev phases:
* Phase 1 (Preproduction): brainstorm-game, game-brief
* Phase 2 (Design): gdd, narrative
* Phase 3 (Technical): game-architecture
* Phase 4 (Production): vendored from BMM workflows
- Updated all module metadata and config_source references
Workflow Vendoring Feature:
- Enables modules to copy workflows from other modules during installation
- Build-time process that updates config_source in vendored workflows
- New agent YAML attribute: workflow-install (build-time metadata)
- Final compiled agents use workflow-install value for workflow attribute
- Implementation in module manager: vendorCrossModuleWorkflows()
- Allows standalone module installation without forced dependencies
Technical Changes:
- tools/cli/lib/yaml-xml-builder.js: Use workflow-install for workflow attribute
- tools/cli/installers/lib/modules/manager.js: Add vendoring functions
- tools/schema/agent.js: Add workflow-install to menu item schema
- Updated 3 documentation files with workflow vendoring details
BMM Workflow Updates:
- workflow-status/init: Added game detection checkpoint
- workflow-status/paths/game-design.yaml: Redirect to BMGD module
- prd/instructions.md: Route game projects to BMGD
- research/instructions-market.md: Reference BMGD for game development
Documentation:
- Created comprehensive BMGD module README
- Added workflow vendoring documentation
- Updated BMB agent creation and module creation guides
## 📚 Complete Documentation Restructure
**BMM Documentation Hub Created:**
- New centralized documentation system at `src/modules/bmm/docs/`
- 18 comprehensive guides organized by topic (7000+ lines total)
- Clear learning paths for greenfield, brownfield, and quick spec flows
- Professional technical writing standards throughout
**New Documentation:**
- `README.md` - Complete documentation hub with 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 (12 min read)
- `workflows-planning.md` - Phase 2 workflows (19 min read)
- `workflows-solutioning.md` - Phase 3 workflows (13 min read)
- `workflows-implementation.md` - Phase 4 workflows (33 min read)
- `workflows-testing.md` - Testing & QA workflows (29 min read)
- `workflow-architecture-reference.md` - Architecture workflow deep-dive
- `workflow-document-project-reference.md` - Document-project workflow reference
- `enterprise-agentic-development.md` - Team collaboration patterns
- `faq.md` - Comprehensive Q&A covering all topics
- `glossary.md` - Complete terminology reference
- `troubleshooting.md` - Common issues and solutions
**Documentation Improvements:**
- Removed all version/date footers (git handles versioning)
- Agent customization docs now include full rebuild process
- Cross-referenced links between all guides
- Reading time estimates for all major docs
- Consistent professional formatting and structure
**Consolidated & Streamlined:**
- Module README (`src/modules/bmm/README.md`) streamlined to lean signpost
- Root README polished with better hierarchy and clear CTAs
- Moved docs from root `docs/` to module-specific locations
- Better separation of user docs vs. developer reference
## 🤖 New Agent: Paige (Documentation Guide)
**Role:** Technical documentation specialist and information architect
**Expertise:**
- Professional technical writing standards
- Documentation structure and organization
- Information architecture and navigation
- User-focused content design
- Style guide enforcement
**Status:** Work in progress - Paige will evolve as documentation needs grow
**Integration:**
- Listed in agents-guide.md, glossary.md, FAQ
- Available for all phases (documentation is continuous)
- Can be customized like all BMM agents
## 🔧 Additional Changes
- Updated agent manifest with Paige
- Updated workflow manifest with new documentation workflows
- Fixed workflow-to-agent mappings across all guides
- Improved root README with clearer Quick Start section
- Better module structure explanations
- Enhanced community links with Discord channel names
**Total Impact:**
- 18 new/restructured documentation files
- 7000+ lines of professional technical documentation
- Complete navigation system with cross-references
- Clear learning paths for all user types
- Foundation for knowledge base (coming in beta)
Co-Authored-By: Claude <noreply@anthropic.com>
This major enhancement revolutionizes the tech-spec workflow from a basic template-filling exercise into a context-aware, intelligent planning system for rapid development of bug fixes and small features.
## Tech-Spec Workflow Transformation (11 files)
### Core Workflow Intelligence (instructions.md)
- Add standalone mode with interactive level/field-type detection
- Implement brownfield convention detection and user confirmation
- Integrate WebSearch for current framework versions and starter templates
- Add comprehensive context discovery (stack, patterns, dependencies)
- Implement auto-validation with quality scoring (always runs)
- Add UX/UI considerations capture for user-facing changes
- Add test framework detection and pattern analysis
- Transform from batch generation to living document approach
### Comprehensive Tech-Spec Template (tech-spec-template.md)
- Expand from 8 to 23 sections for complete context
- Add Context section (available docs, project stack, existing structure)
- Add Development Context (conventions, test framework, existing code)
- Add UX/UI Considerations section
- Add Developer Resources (file paths, key locations, testing)
- Add Integration Points and Configuration Changes
- All sections populated via template-output tags during workflow
### Enhanced Story Generation
- Level 0 (instructions-level0-story.md): Extract from comprehensive tech-spec
- Level 1 (instructions-level1-stories.md): Add story sequence validation, AC quality checks
- User Story Template: Add Dev Agent Record sections for implementation tracking
- Epic Template: Complete rewrite with proper structure and variables
### Validation & Quality (checklist.md)
- Add context gathering completeness checks
- Add definitiveness validation (no "use X or Y" statements)
- Add brownfield integration quality scoring
- Add stack alignment verification
- Add implementation readiness assessment
- Auto-generates validation report with scores
### Configuration (workflow.yaml)
- Add runtime variables: project_level, project_type, development_context, change_type, field_type
- Enable standalone operation without workflow-status.yaml
- Support both workflow-init integration and quick-start mode
## Phase 4 Integration (3 files)
### Story Context Workflow
- Add tech_spec to input_file_patterns (recognizes as authoritative source)
- Update instructions to prioritize tech-spec for Level 0-1 projects
- Tech-spec provides brownfield analysis, framework details, existing patterns
### Create Story Workflow
- Add tech_spec to input_file_patterns
- Enable story generation from tech-spec (alternative to PRD)
- Supports both Quick Spec Flow and traditional BMM flow
## Documentation (2 new files)
### Quick Spec Flow Guide (docs/quick-spec-flow.md)
- Comprehensive 595-line guide for Level 0-1 rapid development
- Complete user journey examples (bug fix, small feature)
- Context discovery explanation (stack, brownfield, conventions)
- Auto-validation details and benefits
- Integration with Phase 4 workflows
- Comparison: Quick Spec vs Full BMM
- Real-world examples and best practices
### Scale Adaptive System (docs/scale-adaptive-system.md)
- Complete 950-line technical guide to BMad Method's 5-level system
- Key terminology: Analysis, Tech-Spec, Epic-Tech-Spec, Architecture
- Level 0-4 workflows, planning docs, and progression
- Brownfield emphasis: document-project required first
- Tech-spec (upfront, Level 0-1) vs epic-tech-spec (during implementation, Level 2-4)
- Architecture document replaces tech-spec at Level 2+ (scales with complexity)
- Retrospectives after each epic in multi-epic projects
- Workflow path configuration reference
### README Updates
- Add Quick Spec Flow announcement with benefits
- Link to Scale Adaptive System documentation
- Clarify when to use Quick Spec Flow vs Full BMM
## Key Features
### Context-Aware Intelligence
- Auto-detects project stack from package.json, requirements.txt, etc.
- Analyzes brownfield codebases using document-project output
- Detects code conventions and confirms with user before proceeding
- Uses WebSearch for up-to-date framework info and starter templates
### Brownfield Respect
- Detects existing patterns (code style, test framework, naming conventions)
- Asks user for confirmation before applying conventions
- Adapts to existing code vs forcing changes
- References document-project analysis for comprehensive context
### Auto-Validation
- Always runs (not optional)
- Validates context gathering, definitiveness, brownfield integration
- Scores tech-spec quality and implementation readiness
- Validates story sequence for Level 1 (no forward dependencies)
### Living Document Approach
- Write to tech-spec continuously during discovery
- Progressive refinement vs batch generation
- Template variables populated via template-output tags in real-time
## Breaking Changes
None - all changes are additive and backward compatible.
## Impact
This transformation enables:
- Bug fixes and small features implemented in minutes vs hours
- Automatic stack detection and brownfield analysis
- Respect for existing conventions and patterns
- Current best practices via WebSearch integration
- Comprehensive context that can replace story-context for simple efforts
- Seamless integration with Phase 4 implementation workflows
Quick Spec Flow now provides a **true fast path from idea to implementation** for Level 0-1 projects while maintaining quality through auto-validation and comprehensive context gathering.
- Added docs/ide-info/opencode.md
- Added tool/cli/installers/lib/ide/opencode.js
- Modified tools/installers/lib/ide/core/detector.js to include
detection for opencode command dir
- Modified tools/cli/platform-codes.yaml to include opencode config
- Modified tools/cli/installers/lib/ide/workflow-command-template.md to
include frontmatter with description as opencode requires this for
commands and adding it to the template by default does not seem to
impact other IDEs
- Modified src/modules/bmm/workflows/workflow-status/workflow.yaml
description so that it properly escapes quotes when interpolated in the
teplate
* feat: add OpenCode integration implementation plan for BMAD-METHOD
* installer(opencode): add OpenCode target metadata in install.config.yaml
* chore(deps): add comment-json for JSONC parsing in OpenCode integration
* feat(installer/opencode): implement setupOpenCode with minimal instructions merge and BMAD-managed agents/commands
* feat(installer): add OpenCode (SST) to IDE selector and CLI --ide help
* fix(opencode): align generated opencode.json(c) with schema (instructions as strings; agent.prompt; command.template; remove unsupported fields)
* feat(installer): enhance OpenCode setup with agent selection and prefix options
* fix: update configuration file references from `bmad-core/core-config.yaml` to `.bmad-core/core-config.yaml` across multiple agent and task files for consistency and clarity.
* refactor: streamline OpenCode configuration prompts and normalize instruction paths for agents and tasks
* feat: add tools property to agent definitions for enhanced functionality. Otherwise opencode consders the subagents as readonly
* feat: add extraction of 'whenToUse' from agents markdown files for improved agent configuration in opencode
* feat: enhance task purpose extraction from markdown files with improved parsing and cleanup logic
* feat: add collision warnings for non-BMAD-managed agent and command keys during setup
* feat: generate and update AGENTS.md for OpenCode integration with agent and task details
* feat: add compact AGENTS.md generator and JSON-only integration for OpenCode
* chore(docs): remove completed OpenCode integration implementation plans
* feat: enable default prefixes for agent and command keys to avoid collisions
* fix: remove unnecessary line breaks in 'whenToUse' descriptions for QA agents to mathc the rest of the agents definitions and improve programatic parsing of whenToUse prop
* fix: update OpenCode references to remove 'SST' for consistency across documentation and configuration
* fix: update agent mode from 'subagent' to 'all' for consistency in agent definitions
* fix: consolidate 'whenToUse' description format for clarity and consistent parsing
- Added support for a new optional `.bmad-flattenignore` file to allow users to specify additional files to exclude from the flattened XML output.
- Updated README and documentation to reflect the new feature and provide examples for usage.
- Modified ignore rules to incorporate patterns from the `.bmad-flattenignore` file after applying `.gitignore` rules.
Benefits:
- Greater flexibility in managing file exclusions for AI model consumption.
- Replace old semantic-release documentation with new simplified system
- Document command line release workflow (npm run release:*)
- Explain automatic release notes generation and categorization
- Add troubleshooting section and preview functionality
- Reflect current single @stable tag installation approach
- Update installer config to use .claude/commands/BMad/ path
- Modify setupClaudeCode function to create nested directory structure
- Update documentation and upgrader to reflect new command location
- Improves organization by grouping all BMad commands together
* refactor(gemini-cli): change agent storage from multiple files to single concatenated file
- Update configuration to use .gemini/bmad-method/ directory instead of .gemini/agents/
- Implement new logic to concatenate all agent files into single GEMINI.md
- Add backward compatibility for existing settings.json
- Remove old agents directory and update related documentation
- Ensure all agent settings are properly loaded
* fix(ide-setup): change agent trigger symbol from @ to *
The change was made to standardize the agent trigger symbol across the system and avoid confusion with other special characters.
* docs: update gemini cli syntax and file structure
- Change agent mention syntax from @ to * in docs and config
- Update file structure documentation from .gemini/agents/ to .gemini/bmad-method/
- Add gemini cli syntax to workflow guide
* fix(ide-setup): remove redundant contextFileNames handling
* refactor: Standardize on 'GitHub Copilot' branding
- Update all references from 'Github Copilot' to 'GitHub Copilot' (official branding)
- Simplify GitHub Copilot guide reference in README
- Rebuild distribution files to reflect changes
- Ensure consistent branding across documentation and configuration
* fix: add Trae IDE support while maintaining GitHub Copilot branding
* fix: correct typos in documentation and agent files
Fix multiple instances of "assest" typo to "assets" in documentation
Correct "quetsions" typo to "questions" in repository structure sections
Add new words to cSpell dictionary in VS Code settings
* feat(trae): add support for trae ide integration
- Add trae guide documentation
- Update installer to support trae configuration
- Include trae in ide options and documentation references
- Fix typo in architect agent documentation
---------
Co-authored-by: Devin Stagner <devin@blackstag.family>
This release introduces significant enhancements across multiple areas:
QA Agent Transformation:
- Transform QA agent into senior developer role with active code refactoring abilities
- Add review-story task enabling QA to review, refactor, and improve code directly
- Integrate QA review step into standard development workflow (SM → Dev → QA)
- QA can fix small issues directly and leave checklist for remaining items
- Updated dev agent to maintain File List for QA review focus
Knowledge Base Improvements:
- Add extensive brownfield development documentation and best practices
- Clarify Web UI vs IDE usage with cost optimization strategies
- Document PRD-first approach for large codebases/monorepos
- Add comprehensive expansion packs explanation
- Update IDE workflow to include QA review step
- Clarify agent usage (bmad-master vs specialized agents)
Brownfield Enhancements:
- Create comprehensive Working in the Brownfield guide
- Add document-project task to analyst agent capabilities
- Implement PRD-first workflow option for focused documentation
- Transform document-project to create practical brownfield architecture docs
- Document technical debt, workarounds, and real-world constraints
- Reference actual files instead of duplicating content
- Add impact analysis when PRD is provided
Documentation Task Improvements:
- Simplify to always create ONE unified architecture document
- Add deep codebase analysis phase with targeted questions
- Focus on documenting reality including technical debt
- Include Quick Reference section with key file paths
- Add practical sections: useful commands, debugging tips, known issues
Workflow Updates:
- Update all 6 workflow files with detailed IDE transition instructions
- Add clear SM → Dev → QA → Dev cycle explanation
- Emphasize Gemini Web for brownfield analysis (1M+ context advantage)
- Support both PRD-first and document-first approaches
This release significantly improves the brownfield development experience and introduces a powerful shift-left QA approach with senior developer mentoring.
- Add markdownExploder setting to core-config.yml
- Update shard-doc task to use md-tree command when enabled
- Implement proper fallback handling when tool is unavailable
- Update core-config structure to remove nested wrapper
- Fix field naming to use camelCase throughout
- Create comprehensive PR guide at docs/how-to-contribute-with-pull-requests.md
- Add prominent links in README.md and CONTRIBUTING.md
- Include step-by-step instructions for GitHub newcomers
- Explain what makes good vs bad PRs with examples
- Add Discord community as primary support channel
This addresses issues with inexperienced contributors submitting
poorly formatted PRs or code dumps instead of proper contributions.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Auto-formatting applied by prettier and yaml-format tools.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
## CHANGES
- Fix typo in CONTRIBUTING.md header
- Rename "Web Agent Setup" to clearer title
- Rename "IDE Agent Setup" to include usage
- Update anchor links to match new headings
- Improve documentation structure and navigation
Brian Madison
Murat K Ozcan
Cameron Pitt
Dylan Buchi
Alex Verkhovsky
Javier Gomez
Daniel Dabrowski
Jonathan Borgwing
manjaroblack
Yongjip Kim
Zach
Gabriel Lemire
Davor Racic
David Elisma
Serhii
David Elisma
titocr
Reider Olivér
Kayvan Sylvan
fabb