mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-17 17:55:34 +00:00
doc updates
This commit is contained in:
Brian Madison
parent
b753fb293b
commit
334e24823a
421
README.md
421
README.md
@ -1,4 +1,4 @@
|
||||
# BMad CORE v6 Alpha
|
||||
# BMad CORE v6 Beta
|
||||
|
||||
[](https://www.npmjs.com/package/bmad-method)
|
||||
[](LICENSE)
|
||||
@ -7,408 +7,239 @@
|
||||
|
||||
**The Universal Human-AI Collaboration Platform**
|
||||
|
||||
BMad-CORE (Collaboration Optimized Reflection Engine) is a revolutionary framework that amplifies human potential through specialized AI agents. Unlike traditional AI tools that replace human thinking, BMad-CORE guides you through reflective workflows that bring out your best ideas and the AI's full capabilities.
|
||||
BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) is a revolutionary framework that amplifies human potential through specialized AI agents. Unlike traditional AI tools that replace human thinking, BMad-CORE guides you through reflective workflows that bring out your best ideas and the AI's full capabilities.
|
||||
|
||||
**🎯 Human Amplification, Not Replacement** • **🎨 Works in Any Domain** • **⚡ Powered by Specialized Agents**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
## 🔄 Upgrading from v4?
|
||||
|
||||
**Prerequisites**: [Node.js](https://nodejs.org) v20+ required
|
||||
|
||||
**One-line install** (thanks Lum!):
|
||||
|
||||
```bash
|
||||
git clone --branch v6-alpha --single-branch https://github.com/bmad-code-org/BMAD-METHOD
|
||||
cd BMAD-METHOD && npm install
|
||||
```
|
||||
|
||||
**Install to your project:**
|
||||
|
||||
```bash
|
||||
npm run install:bmad
|
||||
```
|
||||
|
||||
Follow the interactive prompts. **Important**: When asked for a destination, provide the **full path** to your project folder (don't accept the default).
|
||||
|
||||
**Essential Reading**: Before using BMad Method, read the **[BMM v6 Workflows Guide](./src/modules/bmm/workflows/README.md)** to understand the four-phase workflow system.
|
||||
|
||||
**Stay Connected**:
|
||||
|
||||
- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** to get notified of updates
|
||||
- 🎥 **[Subscribe on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)** for tutorials
|
||||
- 💬 **[Join Discord Community](https://discord.gg/gk8jAdXWmj)** for support and collaboration
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Alpha Status
|
||||
|
||||
**This is an active alpha release.** Please help us improve by testing and reporting issues!
|
||||
|
||||
| Status | Details |
|
||||
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 🔄 **Frequent Updates** | Pull often. Delete `node_modules` and run `npm install` after updates |
|
||||
| 🧪 **Potentially Unstable** | Features and file structure may change frequently. [File issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) or discuss in [Discord](https://discord.gg/gk8jAdXWmj) |
|
||||
| 🚧 **Work in Progress** | Many features, polish, docs, agents, and workflows still coming before and after beta |
|
||||
| 💻 **IDE/Local LLM Required** | Web bundles not fully working yet. Use quality LLM Models and tools for testing (especially BMM module) |
|
||||
| 🔀 **PR Target** | Submit PRs against `v6-alpha` branch, not `main` |
|
||||
|
||||
**📋 [View v6 Alpha Open Items & Roadmap](./v6-open-items.md)** - Track progress and what's coming next
|
||||
**[→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Complete migration instructions for existing v4 users
|
||||
|
||||
---
|
||||
|
||||
## What is BMad-CORE?
|
||||
|
||||
### The Problem with Traditional AI
|
||||
BMad-CORE is the **universal foundation** that powers all BMad modules. It provides:
|
||||
|
||||
Traditional AI tools provide **average, bland solutions** and do the thinking **for** you, making you dependent rather than capable.
|
||||
- **Agent orchestration framework** for specialized AI personas
|
||||
- **Workflow execution engine** for guided processes
|
||||
- **Modular architecture** allowing domain-specific extensions
|
||||
- **IDE integrations** across multiple development environments
|
||||
- **Update-safe customization system** for all agents and workflows
|
||||
|
||||
### The BMad-CORE Difference
|
||||
### Core v6 Framework Enhancements
|
||||
|
||||
BMad-CORE brings out **the best thinking in you and the AI** through:
|
||||
**All modules benefit from these new core capabilities:**
|
||||
|
||||
- **Guided Collaboration**: AI agents act as expert coaches, mentors, and collaborators
|
||||
- **Reflective Workflows**: Structured frameworks that help you discover insights
|
||||
- **Strategic Questioning**: Agents ask the right questions to stimulate your thinking
|
||||
- **Domain Mastery**: Build expertise rather than just getting answers
|
||||
- **Amplified Abilities**: Your natural talents enhanced, not replaced
|
||||
- **🎨 Full Agent Customization** - Modify any agent's name, role, personality, and behavior via `bmad/_cfg/agents/` customize files that survive all updates
|
||||
- **🌐 Multi-Language Support** - Choose your language for both agent communication and documentation output independently
|
||||
- **👤 User Personalization** - Agents address you by name and adapt to your technical level and preferences
|
||||
- **🔄 Update-Safe Configuration** - Your customizations persist through framework and module updates
|
||||
- **⚙️ Flexible Settings** - Configure communication style, technical depth, output formats, and more per module or globally
|
||||
|
||||
### The C.O.R.E. System
|
||||
### The C.O.R.E. Philosophy
|
||||
|
||||
- **C**ollaboration: Human-AI partnership where both contribute unique strengths
|
||||
- **O**ptimized: Refined processes for maximum effectiveness
|
||||
- **R**eflection: Guided thinking that unlocks better solutions
|
||||
- **E**ngine: Powerful framework orchestrating specialized agents and workflows
|
||||
|
||||
---
|
||||
|
||||
## Universal Domain Coverage Through Modules
|
||||
|
||||
BMad-CORE works in **any domain** through specialized modules!
|
||||
|
||||
### 📦 Available Alpha Modules
|
||||
|
||||
#### **BMad Core (core)** - _Always Installed_
|
||||
|
||||
The foundation that powers every module. Includes orchestration agents for local environments and web bundles (ChatGPT, Gemini Gems, etc.).
|
||||
|
||||
#### **[BMad Method (bmm)](./src/modules/bmm/README.md)** - _Software Development Excellence_
|
||||
|
||||
Agile AI-driven software development rebuilt from the ground up on BMad-CORE. Features the revolutionary **Scale Adaptive Workflow Engine™** that adjusts from simple tasks to enterprise-scale projects.
|
||||
|
||||
**Four-Phase Methodology**: Analysis → Planning → Solutioning → Implementation
|
||||
|
||||
**[📚 Full BMM Documentation](./src/modules/bmm/README.md)** | **[📖 v6 Workflows Guide](./src/modules/bmm/workflows/README.md)**
|
||||
|
||||
#### **[BMad Builder (bmb)](./src/modules/bmb/README.md)** - _Create Custom Agents & Workflows_
|
||||
|
||||
Your authoring tool for custom agents, workflows, and modules. Easier than ever to customize existing modules or create standalone solutions.
|
||||
|
||||
**Three Agent Types**: Full module agents, hybrid agents, and lightweight standalone agents
|
||||
|
||||
**[📚 Full BMB Documentation](./src/modules/bmb/README.md)** | **[🎯 Agent Creation Guide](./src/modules/bmb/workflows/create-agent/README.md)**
|
||||
|
||||
#### **Creative Intelligence Suite (cis)** - _Innovation & Problem-Solving_
|
||||
|
||||
Unlock creative thinking and innovation! Includes brainstorming workflows that power other modules (like BMM) while standing alone as a complete creative toolkit.
|
||||
|
||||
**[📚 CIS Documentation](./src/modules/cis/readme.md)**
|
||||
Instead of giving you answers, BMad-CORE helps you **discover better solutions** through strategic questioning, expert guidance, and structured thinking.
|
||||
|
||||
---
|
||||
|
||||
## 🎉 What's New in v6 Alpha
|
||||
## The BMad Method - Agile AI-Driven Development
|
||||
|
||||
### Complete Ground-Up Rewrite
|
||||
**The flagship module for software and game development excellence.**
|
||||
|
||||
Everything rebuilt with best practices, advanced prompt engineering, and standardized XML/markdown conventions for maximum agent adherence.
|
||||
The BMad Method (BMM) is a complete AI-driven agile development framework that revolutionizes how you build software and games. Whether you're fixing a bug, building a feature, or architecting an enterprise system, BMM adapts to your needs.
|
||||
|
||||
### 🎨 Unprecedented Customizability
|
||||
### What's New in v6?
|
||||
|
||||
- **Agent Customization**: Modify any agent via sidecar files in `bmad/_cfg/agents/`
|
||||
- **Update-Safe**: Your customizations persist through updates
|
||||
- **Full Control**: Change names, personas, communication styles, language
|
||||
- **Multi-Language**: Agents can communicate in your preferred language
|
||||
**🎯 Revolutionary Scale-Adaptive Workflows**
|
||||
|
||||
### 🚀 Intelligent Installer
|
||||
- **Levels 0-4**: Automatically adjusts from quick fixes to enterprise-scale projects
|
||||
- **Greenfield & Brownfield**: Full support for new projects and existing codebases
|
||||
- **Smart Context Engine**: New optimized brownfield documentation engine that understands your existing code
|
||||
|
||||
Brand new interactive installer that configures:
|
||||
**🏗️ Project-Adaptive Architecture**
|
||||
|
||||
- Your name (how agents address you)
|
||||
- Communication language preference
|
||||
- Communication (chat) technical level of explanation (beginner - advanced level technical user knowledge)
|
||||
- Documentation output language
|
||||
- Module-specific customization options
|
||||
- IDE-specific enhancements globally or per module (e.g., Claude Code sub-agents for BMM)
|
||||
- Architecture documents that adapt to YOUR project type (web, mobile, embedded, game, etc.)
|
||||
- No more "one-size-fits-all" templates
|
||||
- Specialized sections based on what you're actually building
|
||||
- Game development fully integrated with engine-specific guidance (Unity, Phaser, Godot, Unreal, and more)
|
||||
|
||||
### 📁 Unified Installation
|
||||
**⚡ From Simple to Complex - All in One System**
|
||||
|
||||
Everything installs to a single `bmad/` folder - no more scattered root folders. Clean, organized, and efficient.
|
||||
- **Level 0-1**: Quick fixes and small features with minimal overhead
|
||||
- **Level 2**: Feature development with lightweight planning
|
||||
- **Level 3-4**: Full enterprise workflows with comprehensive documentation
|
||||
- Seamless workflow progression as complexity grows
|
||||
|
||||
### 🤝 Consolidated Agent Party
|
||||
**💬 Highly Interactive & Guided**
|
||||
|
||||
When you install modules, a unified agent party is created for party-mode in your IDE. Super efficient agent simulation with more exciting features coming in beta!
|
||||
- Interactive workflows that ask the right questions
|
||||
- Agents guide you through discovery rather than giving generic answers
|
||||
- Context-aware recommendations based on your project state
|
||||
- Real-time validation and course correction
|
||||
|
||||
### 🎮 Expanded Game Development
|
||||
**📋 Four-Phase Methodology**
|
||||
|
||||
Game development now fully integrated into BMM module:
|
||||
1. **Analysis** (Optional) - Brainstorming, research, product briefs
|
||||
2. **Planning** (Required) - Scale-adaptive PRD/GDD generation
|
||||
3. **Solutioning** (Level 3-4) - Adaptive architecture and tech specs
|
||||
4. **Implementation** (Iterative) - Story creation, context gathering, development, review
|
||||
|
||||
- **Game Type Adaptive**: Adjusts to the type of game you're making
|
||||
- **Multi-Engine Support**: More platforms being added
|
||||
### Specialized Agents
|
||||
|
||||
### ⚡ BMM Scale Adaptive Workflows
|
||||
- **PM** - Product planning and requirements
|
||||
- **Analyst** - Research and business analysis
|
||||
- **Architect** - Technical architecture and design
|
||||
- **Game Designer** - Game-specific design and documentation
|
||||
- **Scrum Master** - Sprint planning and story management
|
||||
- **Developer** - Implementation with senior dev review
|
||||
- **And more** - UX, Test Architect, specialized game roles
|
||||
|
||||
The BMad Method now adapts to your project scale (Levels 0-4) based on:
|
||||
### Documentation
|
||||
|
||||
- Project scope and complexity
|
||||
- New vs. existing codebase
|
||||
- Current codebase state
|
||||
- Team size and structure
|
||||
|
||||
Guides workflows intelligently from simple tech specs to enterprise-scale planning.
|
||||
|
||||
### 🆕 Three Agent Types (BMB)
|
||||
|
||||
1. **Full Module Agents**: Complete agents embedded in modules
|
||||
2. **Hybrid Agents**: Shared across modules
|
||||
3. **Standalone Agents**: Tiny, specialized agents free from any module - perfect for specific needs
|
||||
- **[📚 Complete BMM Documentation](./src/modules/bmm/README.md)** - Full module reference
|
||||
- **[📖 BMM Workflows Guide](./src/modules/bmm/workflows/README.md)** - Essential reading for using BMM
|
||||
|
||||
---
|
||||
|
||||
## BMad Method (BMM) Four-Phase Workflow
|
||||
## Additional Beta Modules
|
||||
|
||||
The BMM module follows a comprehensive four-phase methodology. Each phase adapts to your project's scale and complexity.
|
||||
### **[BMad Builder (BMB)](./src/modules/bmb/README.md)** - Create Custom Solutions
|
||||
|
||||
**[Complete workflow documentation →](./src/modules/bmm/workflows/README.md)**
|
||||
Build your own agents, workflows, and modules using the BMad-CORE framework.
|
||||
|
||||
### Phase 1: Analysis _(Optional)_
|
||||
- **Agent Creation**: Design specialized agents with custom roles and behaviors
|
||||
- **Workflow Design**: Build structured multi-step processes
|
||||
- **Module Development**: Package complete solutions for any domain
|
||||
- **Three Agent Types**: Full module, hybrid, and standalone agents
|
||||
|
||||
**Analyst Agent**:
|
||||
|
||||
- `brainstorm-project` - Generate and refine project concepts
|
||||
- `research` - Market research, deep research, prompt generation
|
||||
- `product-brief` - Document initial product vision
|
||||
- `workflow-init` or `workflow-status` will set up or get the the status of a guided workflow
|
||||
|
||||
**Game Designer Agent** _(for game projects)_:
|
||||
|
||||
- `brainstorm-game` - Game-specific ideation
|
||||
- `game-brief` - Game concept documentation
|
||||
- `research` - Game market and technical research
|
||||
- `workflow-init` or `workflow-status` will set up or get the the status of a guided workflow
|
||||
**[📚 Complete BMB Documentation](./src/modules/bmb/README.md)** | **[🎯 Agent Creation Guide](./src/modules/bmb/workflows/create-agent/README.md)**
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Planning _(Required)_
|
||||
### **[Creative Intelligence Suite (CIS)](./src/modules/cis/readme.md)** - Innovation & Creativity
|
||||
|
||||
**PM Agent**:
|
||||
Transform creative and strategic thinking through AI-powered facilitation across five specialized domains.
|
||||
|
||||
- `prd` - Creates scale-adaptive PRD for level 2-4 workflows
|
||||
- **5 Interactive Workflows**: Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
|
||||
- **150+ Creative Techniques**: Proven frameworks and methodologies
|
||||
- **5 Specialized Agents**: Each with unique personas and facilitation styles
|
||||
- **Shared Resource**: Powers creative workflows in other modules (e.g., BMM brainstorming)
|
||||
|
||||
The planning workflow adapts to:
|
||||
|
||||
- Project complexity (Levels 0-4)
|
||||
- Project type (web, mobile, embedded, etc.)
|
||||
- New vs. existing codebase
|
||||
- Team structure
|
||||
|
||||
**Game Designer Agent** _(for game projects)_:
|
||||
|
||||
- `gdd` - Uses a specialized game design document workflow optimized for Game Design Documents
|
||||
**[📚 Complete CIS Documentation](./src/modules/cis/readme.md)** | **[📖 CIS Workflows](./src/modules/cis/workflows/README.md)**
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Solutioning _(Levels 3-4)_
|
||||
|
||||
**Architect / Game Architect Agent**:
|
||||
|
||||
- `architecture` - Creates adaptive architecture based on project type
|
||||
- No more document sharding
|
||||
- Adapts sections to your project (web, mobile, embedded, game, etc.)
|
||||
- Beyond basic concerns (complex testing, DevOps, security), specialized agents assist _(coming soon)_
|
||||
|
||||
- `tech-spec` - Generates Epic Tech Specs
|
||||
- Pulls all technical information from planning
|
||||
- Includes web research as needed
|
||||
- One tech spec per epic
|
||||
- Enhances SM's ability to prepare stories
|
||||
|
||||
**Note**: The PO can validate epics/stories with checklists, though the Architect maintains them during solutioning.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Implementation _(Iterative)_
|
||||
|
||||
**Scrum Master (SM) Agent**:
|
||||
|
||||
Before development starts, the SM prepares each story:
|
||||
|
||||
1. `create-story` - Generates story from tech spec and context
|
||||
2. `story-context` - **🎉 NEW!** Game-changing contextual preparation
|
||||
- Real-time context gathering for the specific story
|
||||
- No more generic file lists
|
||||
- Supercharged, specialized development context
|
||||
|
||||
**Dev Agent**:
|
||||
|
||||
Enhanced developer workflow:
|
||||
|
||||
- Development task execution
|
||||
- Senior dev agent review (replaces separate QA agent)
|
||||
- Pulls rich context from story-context workflow
|
||||
|
||||
**🎊 Many more exciting changes throughout BMM for you to discover during alpha!**
|
||||
|
||||
---
|
||||
|
||||
## Detailed Installation Guide
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js v20+** ([Download](https://nodejs.org))
|
||||
- **Git** (for cloning)
|
||||
|
||||
### Step-by-Step Installation
|
||||
### Installation
|
||||
|
||||
#### Step 1: Clone the Repository
|
||||
|
||||
**Option A** - One-line install:
|
||||
Install BMad to your project using npx:
|
||||
|
||||
```bash
|
||||
git clone --branch v6-alpha --single-branch https://github.com/bmad-code-org/BMAD-METHOD
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
**Option B** - Standard clone then checkout:
|
||||
The interactive installer will guide you through:
|
||||
|
||||
```bash
|
||||
# Clone via your preferred method:
|
||||
gh repo clone bmad-code-org/BMAD-METHOD
|
||||
# OR
|
||||
git clone https://github.com/bmad-code-org/BMAD-METHOD.git
|
||||
# OR
|
||||
git clone git@github.com:bmad-code-org/BMAD-METHOD.git
|
||||
1. **Project location** - Where to install BMad
|
||||
2. **Module selection** - Choose which modules you need (BMM, BMB, CIS)
|
||||
3. **Configuration** - Set your name, language preferences, and module options
|
||||
4. **IDE integration** - Configure your development environment
|
||||
|
||||
# Change to the directory
|
||||
cd BMAD-METHOD
|
||||
|
||||
# Checkout alpha branch
|
||||
git checkout v6-alpha
|
||||
|
||||
# Verify branch
|
||||
git status
|
||||
# Should show: "On branch v6-alpha. Your branch is up to date with 'origin/v6-alpha'."
|
||||
```
|
||||
|
||||
#### Step 2: Install Dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Verify `node_modules` folder exists at project root.
|
||||
|
||||
#### Step 3: Install to Your Project
|
||||
|
||||
```bash
|
||||
npm run install:bmad
|
||||
```
|
||||
|
||||
**Follow the interactive prompts:**
|
||||
|
||||
1. **Destination Path**: Enter the **full path** to your project folder
|
||||
- Don't accept the default
|
||||
- For new projects, confirm when prompted to create the directory
|
||||
2. **Module Selection**:
|
||||
- **Core** (always installed)
|
||||
- **BMM** - BMad Method for software development (default)
|
||||
- **BMB** - BMad Builder for creating agents/workflows
|
||||
- **CIS** - Creative Intelligence Suite
|
||||
|
||||
3. **Configuration**:
|
||||
- Your name
|
||||
- Preferred communication language
|
||||
- Module-specific options
|
||||
|
||||
#### Step 4: Understanding the Installation
|
||||
### What Gets Installed
|
||||
|
||||
All modules install to a single `bmad/` folder in your project:
|
||||
|
||||
```
|
||||
your-project/
|
||||
└── bmad/
|
||||
├── core/ # Core framework (always present)
|
||||
├── core/ # Core framework (always installed)
|
||||
├── bmm/ # BMad Method (if selected)
|
||||
├── bmb/ # BMad Builder (if selected)
|
||||
├── cis/ # Creative Intelligence Suite (shared resources)
|
||||
└── _cfg/ # Your customizations
|
||||
└── agents/ # Agent sidecar customization files
|
||||
└── agents/ # Agent customization files
|
||||
```
|
||||
|
||||
**Note**: You may see folders for modules you didn't explicitly select. This is intentional - modules share minimal required resources. For example, BMM uses CIS brainstorming workflows, so `bmad/cis/` appears with shared files even if you only selected BMM.
|
||||
### Getting Started with BMM
|
||||
|
||||
After installation, activate the Analyst agent in your IDE and run:
|
||||
|
||||
```bash
|
||||
/workflow-init
|
||||
```
|
||||
|
||||
Or run it directly as a command (command syntax varies by IDE - use slash commands in Claude Code, OpenCode, etc.).
|
||||
|
||||
This sets up the guided workflow system and helps you choose the right starting point for your project based on its complexity.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
## Key Features
|
||||
|
||||
### BMad Builder (BMB) Resources
|
||||
### 🎨 Update-Safe Customization
|
||||
|
||||
**Agent Development**:
|
||||
- **Agent Customization**: Modify agents via `bmad/_cfg/agents/` customize files
|
||||
- **Persistent Settings**: Your customizations survive updates
|
||||
- **Multi-Language Support**: Agents communicate in your preferred language
|
||||
- **Flexible Configuration**: Adjust agent names, roles, communication styles, and more
|
||||
|
||||
- [Agent Architecture](src/modules/bmb/workflows/create-agent/agent-architecture)
|
||||
- [Agent Command Patterns](src/modules/bmb/workflows/create-agent/agent-command-patterns.md)
|
||||
- [Agent Types](src/modules/bmb/workflows/create-agent/agent-types.md)
|
||||
- [Communication Styles](src/modules/bmb/workflows/create-agent/communication-styles.md)
|
||||
### 🚀 Intelligent Installation
|
||||
|
||||
**Module Development**:
|
||||
The installer automatically:
|
||||
|
||||
- [Module Structure](src/modules/bmb/workflows/create-module/module-structure.md)
|
||||
- Detects and migrates v4 installations
|
||||
- Configures IDE integrations
|
||||
- Resolves module dependencies
|
||||
- Sets up agent customization templates
|
||||
- Creates unified agent manifests
|
||||
|
||||
**Workflow Development**:
|
||||
### 📁 Unified Architecture
|
||||
|
||||
- [Workflow Creation Guide](src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md)
|
||||
|
||||
> **Coming Soon**: A dedicated module contribution repository (beta release) where you can share your custom modules!
|
||||
|
||||
### Installer & Bundler Documentation
|
||||
|
||||
- **[CLI Tool Guide](tools/cli/README.md)** - Complete installer, bundler, and agent compilation system
|
||||
- [IDE Injections](docs/installers-bundlers/ide-injections)
|
||||
- [Installers Modules Platforms Reference](docs/installers-bundlers/installers-modules-platforms-reference)
|
||||
- [Web Bundler Usage](docs/installers-bundlers/web-bundler-usage)
|
||||
- [Claude Code Sub Module BMM Installer](src/modules/bmm/sub-modules/claude-code/readme.md)
|
||||
Everything in one place - no more scattered configuration folders. Clean, organized, maintainable.
|
||||
|
||||
---
|
||||
|
||||
## Support & Community
|
||||
## Additional Documentation
|
||||
|
||||
We have an amazing, active community ready to help!
|
||||
- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions for v4 users
|
||||
- **[CLI Tool Guide](./tools/cli/README.md)** - Installer and bundler reference
|
||||
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to BMad
|
||||
|
||||
- 💬 **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share ideas, collaborate
|
||||
- 🐛 **[Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs and request features
|
||||
- 💬 **[GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)** - Community conversations
|
||||
- 🎥 **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Tutorials and updates
|
||||
---
|
||||
|
||||
## Community & Support
|
||||
|
||||
- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Get help, share ideas, and collaborate
|
||||
- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs and request features
|
||||
- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials and updates
|
||||
- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Get notified of updates
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions and new module development!
|
||||
|
||||
**📋 [Read CONTRIBUTING.md](CONTRIBUTING.md)** - Complete contribution guide
|
||||
|
||||
**Remember**: Submit PRs against the `v6-alpha` branch, not `main`.
|
||||
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) for details.
|
||||
MIT License - See [LICENSE](LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
## Trademark Notice
|
||||
|
||||
BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
|
||||
**Trademark Notice**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -38,10 +38,10 @@ this.modulesSourcePath = getSourcePath('modules'); // Hardcoded to src/modules/
|
||||
|
||||
### Real-World Use Case
|
||||
|
||||
- User has BMD module at `/Users/brianmadison/dev/BMAD-METHOD/bmd` (standalone folder)
|
||||
- User has a custom foo module at `/Users/username/dev/foo` (standalone folder)
|
||||
- Module has agents that need compilation (YAML → Markdown with XML)
|
||||
- Module needs IDE integration (generate commands for Claude Code, etc.)
|
||||
- Current installer cannot handle this - module must be in `src/modules/` to be discovered
|
||||
- Current installer cannot handle this - module must be in `src/modules/foo` to be discovered
|
||||
|
||||
---
|
||||
|
||||
@ -217,21 +217,7 @@ User runs: npm run install:bmad
|
||||
|
||||
```bash
|
||||
# Interactive mode
|
||||
bmad install-module
|
||||
|
||||
# Non-interactive mode
|
||||
bmad install-module \
|
||||
--source /path/to/custom-module \
|
||||
--target /path/to/project \
|
||||
--ides codex,windsurf
|
||||
|
||||
# CI/CD mode
|
||||
bmad install-module \
|
||||
--source ./my-module \
|
||||
--target . \
|
||||
--ides codex \
|
||||
--non-interactive \
|
||||
--config-file ./module-config.json
|
||||
install-module
|
||||
```
|
||||
|
||||
### System Architecture
|
||||
@ -248,7 +234,7 @@ bmad install-module \
|
||||
│ - Call CustomModuleInstaller │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
┌───────────────────────────────────────────────────────────────┐
|
||||
│ NEW: CustomModuleInstaller Class │
|
||||
│ File: tools/cli/installers/lib/core/custom-module-installer.js│
|
||||
│ │
|
||||
@ -261,7 +247,7 @@ bmad install-module \
|
||||
│ 6. Generate IDE artifacts (IdeManager) │
|
||||
│ 7. Update manifests (ManifestGenerator) │
|
||||
│ 8. Run custom installer hooks (if exists) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
└───────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ NEW: ModuleValidator Class │
|
||||
|
||||
225
docs/v4-to-v6-upgrade.md
Normal file
225
docs/v4-to-v6-upgrade.md
Normal file
@ -0,0 +1,225 @@
|
||||
# BMad v4 to v6 Upgrade Guide
|
||||
|
||||
## Overview
|
||||
|
||||
BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
|
||||
|
||||
---
|
||||
|
||||
## Automatic V4 Detection
|
||||
|
||||
When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects:
|
||||
|
||||
- **Legacy folders**: Any folders starting with `.bmad`, `bmad` (lowercase), or `Bmad`
|
||||
- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
|
||||
|
||||
### What Happens During Detection
|
||||
|
||||
1. **Automatic Backup of v4 Modules**: All `.bmad-*` folders are moved to `v4-backup/` in your project root
|
||||
- If a backup already exists, a timestamp is added to avoid conflicts
|
||||
- Example: `.bmad-core` → `v4-backup/.bmad-core`
|
||||
- Your project files and data are NOT affected
|
||||
|
||||
2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
|
||||
- Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc.
|
||||
- These old commands would still reference v4 folder structure if left in place
|
||||
- The installer provides copy/paste terminal commands for your platform
|
||||
- You can proceed without cleanup, but removing them prevents confusion with old v4 commands
|
||||
|
||||
---
|
||||
|
||||
## Module Migration
|
||||
|
||||
### Deprecated Modules
|
||||
|
||||
| v4 Module | v6 Status |
|
||||
| ----------------------------- | ------------------------------------------------ |
|
||||
| `.bmad-2d-phaser-game-dev` | Integrated into BMM |
|
||||
| `.bmad-2d-unity-game-dev` | Integrated into BMM |
|
||||
| `.bmad-godot-game-dev` | Integrated into BMM |
|
||||
| `.bmad-*-game-dev` (any) | Integrated into BMM |
|
||||
| `.bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
|
||||
| `.bmad-creative-writing` | Not adapted - New module releasing soon |
|
||||
|
||||
**Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Changes
|
||||
|
||||
### Folder Structure
|
||||
|
||||
**v4 "Expansion Packs" Structure:**
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── .bmad-core/ # Was actually the BMad Method
|
||||
├── .bmad-game-dev/ # Separate expansion packs
|
||||
├── .bmad-creative-writing/
|
||||
└── .bmad-infrastructure-devops/
|
||||
```
|
||||
|
||||
**v6 Unified Structure:**
|
||||
|
||||
```
|
||||
your-project/
|
||||
└── bmad/ # Single installation folder
|
||||
├── core/ # Real core framework (applies to all modules)
|
||||
├── bmm/ # BMad Method (software/game dev)
|
||||
├── bmb/ # BMad Builder (create agents/workflows)
|
||||
├── cis/ # Creative Intelligence Suite
|
||||
└── _cfg/ # Your customizations
|
||||
└── agents/ # Agent customization files
|
||||
```
|
||||
|
||||
### Key Concept Changes
|
||||
|
||||
- **v4 `.bmad-core`**: Was actually the BMad Method
|
||||
- **v6 `bmad/core/`**: Is the real universal core framework
|
||||
- **v6 `bmad/bmm/`**: Is the BMad Method module
|
||||
- **Module identification**: All modules now have a `config.yaml` file
|
||||
|
||||
---
|
||||
|
||||
## Project Progress Migration
|
||||
|
||||
### If You've Completed Planning Phase (PRD/Architecture) with the BMad Method:
|
||||
|
||||
After running the v6 installer:
|
||||
|
||||
1. **Run `workflow-init`** workflow to set up the guided workflow system
|
||||
2. **Specify your project level** when prompted:
|
||||
- If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4**
|
||||
- This tells v6 you've already completed planning and solutioning phases
|
||||
3. **Document paths**: Keep your existing paths during installation
|
||||
- Default PRD/Architecture location: `docs/`
|
||||
- Default stories location: `docs/stories/`
|
||||
- **Accept these defaults** if you're already using them in v4
|
||||
|
||||
> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
|
||||
|
||||
### If You're Mid-Development (Stories Created/Implemented)
|
||||
|
||||
1. Complete the v6 installation as above
|
||||
2. Run `workflow-init` and specify Level 3 or 4
|
||||
3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4)
|
||||
|
||||
---
|
||||
|
||||
## Agent Customization Migration
|
||||
|
||||
### v4 Agent Customization
|
||||
|
||||
In v4, you may have modified agent files directly in `.bmad-*` folders.
|
||||
|
||||
### v6 Agent Customization
|
||||
|
||||
**All customizations** now go in `bmad/_cfg/agents/` using customize files:
|
||||
|
||||
**Example: Renaming an agent and changing communication style**
|
||||
|
||||
File: `bmad/_cfg/agents/bmm-pm.customize.yaml`
|
||||
|
||||
```yaml
|
||||
# Customize the PM agent
|
||||
persona:
|
||||
name: 'Captain Jack' # Override agent name
|
||||
role: 'Swashbuckling Product Owner'
|
||||
communication_style: |
|
||||
- Talk like a pirate
|
||||
- Use nautical metaphors for software concepts
|
||||
- Always upbeat and adventurous
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
|
||||
- Base agent: `bmad/bmm/agents/pm.md`
|
||||
- Customization: `bmad/_cfg/agents/bmm-pm.customize.yaml`
|
||||
- Result: Agent uses your custom name and style, but updates don't overwrite your changes
|
||||
|
||||
---
|
||||
|
||||
## Document Compatibility
|
||||
|
||||
### Sharded vs Unsharded Documents
|
||||
|
||||
**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
|
||||
|
||||
- ✅ Sharded documents (split into multiple files)
|
||||
- ✅ Unsharded documents (single file per section)
|
||||
- ✅ Custom sections for your project type
|
||||
- ✅ Mixed approaches
|
||||
|
||||
All workflow files are scanned automatically. No manual configuration needed.
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### 1. Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bmad-code-org/BMAD-METHOD
|
||||
cd BMAD-METHOD
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Run Installer on Your v4 Project
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
**Enter the full path to your v4 project** when prompted.
|
||||
|
||||
### 3. Follow Interactive Prompts
|
||||
|
||||
The installer will:
|
||||
|
||||
1. Detect v4 installation and offer to backup `.bmad-*` folders
|
||||
2. Prompt for recommended cleanup (you can skip)
|
||||
3. Let you select modules (recommend: BMM for software and or game development)
|
||||
4. Configure core settings (name, language, etc.)
|
||||
5. Configure module-specific options
|
||||
6. Configure IDE integrations
|
||||
|
||||
### 4. Accept Default Paths
|
||||
|
||||
If you're using:
|
||||
|
||||
- `docs/` for PRD and architecture
|
||||
- `docs/stories/` for story files
|
||||
|
||||
**Accept these defaults** during installation.
|
||||
|
||||
### 5. Initialize Workflow
|
||||
|
||||
After installation:
|
||||
|
||||
```bash
|
||||
# In your project have the agent mode run workflow-init, in Claude Code:
|
||||
/workflow-init
|
||||
# or run the analyst and tell the analyst after it loads
|
||||
*workflow-init
|
||||
```
|
||||
|
||||
Select **Level 3 or 4** if you've already completed PRD/architecture in v4.
|
||||
|
||||
---
|
||||
|
||||
## Post-Migration Checklist
|
||||
|
||||
- [ ] v4 folders backed up to `v4-backup/`
|
||||
- [ ] v6 installed to `bmad/` folder
|
||||
- [ ] `workflow-init` run with correct project level selected
|
||||
- [ ] Agent customizations migrated to `bmad/_cfg/agents/` if needed
|
||||
- [ ] IDE integration working (test by listing agents)
|
||||
- [ ] For active development: `sprint-planning` workflow executed
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
|
||||
- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
- **Docs**: Check `bmad/docs/` in your installation for IDE-specific instructions
|
||||
@ -41,6 +41,14 @@ agent:
|
||||
workflow: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
|
||||
description: Create a new BMAD Core workflow with proper structure
|
||||
|
||||
- trigger: edit-agent
|
||||
workflow: "{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml"
|
||||
description: Edit existing agents while following best practices
|
||||
|
||||
- trigger: edit-module
|
||||
workflow: "{project-root}/bmad/bmb/workflows/edit-module/workflow.yaml"
|
||||
description: Edit existing modules (structure, agents, workflows, documentation)
|
||||
|
||||
- trigger: edit-workflow
|
||||
workflow: "{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml"
|
||||
description: Edit existing workflows while following best practices
|
||||
|
||||
@ -361,6 +361,13 @@ When building agents:
|
||||
- Workflows can be incomplete (marked "todo")
|
||||
- Workflow paths must be valid or "todo"
|
||||
|
||||
**Workflow Interaction Styles** (BMAD v6 default):
|
||||
|
||||
- **Intent-based + Interactive**: Workflows adapt to user context and skill level
|
||||
- Workflows collaborate with users, not just extract data
|
||||
- See workflow-creation-guide.md "Instruction Styles" section for details
|
||||
- When creating workflows for your agent, default to intent-based unless you need prescriptive control
|
||||
|
||||
### With Tasks
|
||||
|
||||
- Tasks are single operations
|
||||
|
||||
@ -128,10 +128,51 @@
|
||||
|
||||
<action>Transform their natural language capabilities into technical YAML command structure, explaining the implementation approach as you structure each capability into workflows, actions, or prompts</action>
|
||||
|
||||
<check if="agent will invoke workflows or have significant user interaction">
|
||||
<action>Discuss interaction style for this agent:
|
||||
|
||||
Since this agent will {{invoke_workflows/interact_significantly}}, consider how it should interact with users:
|
||||
|
||||
**For Full/Module Agents with workflows:**
|
||||
|
||||
**Interaction Style** (for workflows this agent invokes):
|
||||
|
||||
- **Intent-based (Recommended)**: Workflows adapt conversation to user context, skill level, needs
|
||||
- **Prescriptive**: Workflows use structured questions with specific options
|
||||
- **Mixed**: Strategic use of both (most workflows will be mixed)
|
||||
|
||||
**Interactivity Level** (for workflows this agent invokes):
|
||||
|
||||
- **High (Collaborative)**: Constant user collaboration, iterative refinement
|
||||
- **Medium (Guided)**: Key decision points with validation
|
||||
- **Low (Autonomous)**: Minimal input, final review
|
||||
|
||||
Explain: "Most BMAD v6 workflows default to **intent-based + medium/high interactivity**
|
||||
for better user experience. Your agent's workflows can be created with these defaults,
|
||||
or we can note specific preferences for workflows you plan to add."
|
||||
|
||||
**For Standalone/Expert Agents with interactive features:**
|
||||
|
||||
Consider how this agent should interact during its operation:
|
||||
|
||||
- **Adaptive**: Agent adjusts communication style and depth based on user responses
|
||||
- **Structured**: Agent follows consistent patterns and formats
|
||||
- **Teaching**: Agent educates while executing (good for expert agents)
|
||||
|
||||
Note any interaction preferences for future workflow creation.
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>If they seem engaged, explore whether they'd like to add special prompts for complex analyses or critical setup steps for agent activation</action>
|
||||
|
||||
<action>Build the YAML menu structure naturally from the conversation, ensuring each command has proper trigger, workflow/action reference, and description</action>
|
||||
|
||||
<action>For commands that will invoke workflows, note whether those workflows exist or need to be created:
|
||||
|
||||
- Existing workflows: Verify paths are correct
|
||||
- New workflows needed: Note that they'll be created with intent-based + interactive defaults unless specified
|
||||
</action>
|
||||
|
||||
<example>
|
||||
```yaml
|
||||
menu:
|
||||
|
||||
@ -14,6 +14,7 @@ src/modules/{module-code}/
|
||||
├── agents/ # Agent definitions (.agent.yaml)
|
||||
├── workflows/ # Workflow folders
|
||||
├── tasks/ # Task files
|
||||
├── tools/ # Tool files
|
||||
├── templates/ # Shared templates
|
||||
├── data/ # Static data
|
||||
├── _module-installer/ # Installation configuration
|
||||
@ -27,11 +28,11 @@ src/modules/{module-code}/
|
||||
├── agents/ # Compiled agent files (.md)
|
||||
├── workflows/ # Workflow instances
|
||||
├── tasks/ # Task files
|
||||
├── tools/ # Tool files
|
||||
├── templates/ # Templates
|
||||
├── data/ # Module data
|
||||
├── config.yaml # Generated from install-config.yaml
|
||||
└── README.md # Module documentation
|
||||
|
||||
```
|
||||
|
||||
## Module Types by Complexity
|
||||
|
||||
@ -72,7 +72,7 @@ Based on type, determine which files are needed:
|
||||
Store decisions for later use.
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Gather workflow metadata">
|
||||
<step n="2" goal="Gather workflow metadata and invocation settings">
|
||||
Collect essential configuration details:
|
||||
- Description (clear purpose statement)
|
||||
- Author name (default to user_name or "BMad")
|
||||
@ -80,40 +80,149 @@ Collect essential configuration details:
|
||||
- Any required input documents
|
||||
- Any required tools or dependencies
|
||||
|
||||
<action>Determine standalone property - this controls how the workflow can be invoked:
|
||||
|
||||
Explain to the user:
|
||||
|
||||
**Standalone Property** controls whether the workflow can be invoked directly or only called by other workflows/agents.
|
||||
|
||||
**standalone: true (DEFAULT - Recommended for most workflows)**:
|
||||
|
||||
- Users can invoke directly via IDE commands or `/workflow-name`
|
||||
- Shows up in IDE command palette
|
||||
- Can also be called from agent menus or other workflows
|
||||
- Use for: User-facing workflows, entry-point workflows, any workflow users run directly
|
||||
|
||||
**standalone: false (Use for helper/internal workflows)**:
|
||||
|
||||
- Cannot be invoked directly by users
|
||||
- Only called via `<invoke-workflow>` from other workflows or agent menus
|
||||
- Doesn't appear in IDE command palette
|
||||
- Use for: Internal utilities, sub-workflows, helpers that don't make sense standalone
|
||||
|
||||
Most workflows should be `standalone: true` to give users direct access.
|
||||
</action>
|
||||
|
||||
<ask>Should this workflow be directly invokable by users?
|
||||
|
||||
1. **Yes (Recommended)** - Users can run it directly (standalone: true)
|
||||
2. **No** - Only called by other workflows/agents (standalone: false)
|
||||
|
||||
Most workflows choose option 1:</ask>
|
||||
|
||||
<action>Store {{standalone_setting}} as true or false based on response</action>
|
||||
|
||||
Create the workflow name in kebab-case and verify it doesn't conflict with existing workflows.
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Design workflow steps">
|
||||
Work with user to outline the workflow steps:
|
||||
- How many major steps? (Recommend 5-10 max)
|
||||
<step n="3" goal="Understand workflow interaction style and design steps">
|
||||
<critical>Instruction style and interactivity level fundamentally shape the user experience - choose thoughtfully</critical>
|
||||
|
||||
<action>Reference the comprehensive "Instruction Styles: Intent-Based vs Prescriptive" section from the loaded creation guide</action>
|
||||
|
||||
<action>Discuss instruction style collaboratively with the user:
|
||||
|
||||
Explain that there are two primary approaches:
|
||||
|
||||
**Intent-Based (RECOMMENDED as default)**:
|
||||
|
||||
- Gives AI goals and principles, lets it adapt conversation naturally
|
||||
- More flexible, conversational, responsive to user context
|
||||
- Better for: discovery, complex decisions, teaching, varied user skill levels
|
||||
- Uses <action> tags with guiding instructions
|
||||
- Example from architecture workflow: Facilitates decisions adapting to user_skill_level
|
||||
|
||||
**Prescriptive**:
|
||||
|
||||
- Provides exact questions and specific options
|
||||
- More controlled, predictable, consistent across runs
|
||||
- Better for: simple data collection, finite options, compliance, quick setup
|
||||
- Uses <ask> tags with specific question text
|
||||
- Example: Platform selection with 5 defined choices
|
||||
|
||||
Explain that **most workflows should default to intent-based** but use prescriptive for simple data points.
|
||||
The architecture workflow is an excellent example of intent-based with prescriptive moments.
|
||||
</action>
|
||||
|
||||
<ask>For this workflow's PRIMARY style:
|
||||
|
||||
1. **Intent-based (Recommended)** - Adaptive, conversational, responds to user context
|
||||
2. **Prescriptive** - Structured, consistent, controlled interactions
|
||||
3. **Mixed/Balanced** - I'll help you decide step-by-step
|
||||
|
||||
What feels right for your workflow's purpose?</ask>
|
||||
|
||||
<action>Store {{instruction_style}} preference</action>
|
||||
|
||||
<action>Now discuss interactivity level:
|
||||
|
||||
Beyond style, consider **how interactive** this workflow should be:
|
||||
|
||||
**High Interactivity (Collaborative)**:
|
||||
|
||||
- Constant back-and-forth with user
|
||||
- User guides direction, AI facilitates
|
||||
- Iterative refinement and review
|
||||
- Best for: creative work, complex decisions, learning experiences
|
||||
- Example: Architecture workflow's collaborative decision-making
|
||||
|
||||
**Medium Interactivity (Guided)**:
|
||||
|
||||
- Key decision points have interaction
|
||||
- AI proposes, user confirms or refines
|
||||
- Validation checkpoints
|
||||
- Best for: most document workflows, structured processes
|
||||
- Example: PRD workflow with sections to review
|
||||
|
||||
**Low Interactivity (Autonomous)**:
|
||||
|
||||
- Minimal user input required
|
||||
- AI works independently with guidelines
|
||||
- User reviews final output
|
||||
- Best for: automated generation, batch processing
|
||||
- Example: Generating user stories from epics
|
||||
</action>
|
||||
|
||||
<ask>What interactivity level suits this workflow?
|
||||
|
||||
1. **High** - Highly collaborative, user actively involved throughout
|
||||
2. **Medium** - Guided with key decision points (most common)
|
||||
3. **Low** - Autonomous with final review
|
||||
|
||||
Select the level that matches your workflow's purpose:</ask>
|
||||
|
||||
<action>Store {{interactivity_level}} preference</action>
|
||||
|
||||
<action>Explain how these choices will inform the workflow design:
|
||||
|
||||
- Intent-based + High interactivity: Conversational discovery with open questions
|
||||
- Intent-based + Medium: Facilitated guidance with confirmation points
|
||||
- Intent-based + Low: Principle-based autonomous generation
|
||||
- Prescriptive + any level: Structured questions, but frequency varies
|
||||
- Mixed: Strategic use of both styles where each works best
|
||||
</action>
|
||||
|
||||
<action>Now work with user to outline workflow steps:
|
||||
|
||||
- How many major steps? (Recommend 3-7 for most workflows)
|
||||
- What is the goal of each step?
|
||||
- Which steps are optional?
|
||||
- Which steps need user input?
|
||||
- Which steps need heavy user collaboration vs autonomous execution?
|
||||
- Which steps should repeat?
|
||||
- What variables/outputs does each step produce?
|
||||
|
||||
<ask>What instruction style should this workflow favor?
|
||||
Consider their instruction_style and interactivity_level choices when designing step flow:
|
||||
|
||||
**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
|
||||
- High interactivity: More granular steps with collaboration
|
||||
- Low interactivity: Larger autonomous steps with review
|
||||
- Intent-based: Focus on goals and principles in step descriptions
|
||||
- Prescriptive: Define specific questions and options
|
||||
</action>
|
||||
|
||||
- More flexible and conversational
|
||||
- LLM chooses appropriate questions based on context
|
||||
- Better for complex discovery and iterative refinement
|
||||
- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
|
||||
<action>Create a step outline that matches the chosen style and interactivity level</action>
|
||||
<action>Note which steps should be intent-based vs prescriptive (if mixed approach)</action>
|
||||
|
||||
**2. Prescriptive** - Provide exact wording for questions and options
|
||||
|
||||
- More controlled and predictable
|
||||
- Ensures consistency across runs
|
||||
- Better for simple data collection or specific compliance needs
|
||||
- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
|
||||
|
||||
Note: Your choice will be the _primary_ style, but we'll use the other when it makes more sense for specific steps.</ask>
|
||||
|
||||
<action>Store instruction_style preference (intent-based or prescriptive)</action>
|
||||
<action>Explain that both styles have value and will be mixed appropriately</action>
|
||||
|
||||
Create a step outline with clear goals and outputs.
|
||||
<template-output>step_outline</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Create workflow.yaml">
|
||||
@ -130,6 +239,7 @@ Replace all placeholders following the workflow creation guide conventions:
|
||||
Include:
|
||||
|
||||
- All metadata from steps 1-2
|
||||
- **Standalone property**: Use {{standalone_setting}} from step 2 (true or false)
|
||||
- Proper paths for installed_path using variable substitution
|
||||
- Template/instructions/validation paths based on workflow type:
|
||||
- Document workflow: all files (template, instructions, validation)
|
||||
@ -151,6 +261,38 @@ date: system-generated
|
||||
|
||||
<critical>This standard config ensures workflows can run autonomously and communicate properly with users</critical>
|
||||
|
||||
<critical>ALWAYS include the standalone property:</critical>
|
||||
|
||||
```yaml
|
||||
standalone: { { standalone_setting } } # true or false from step 2
|
||||
```
|
||||
|
||||
**Example complete workflow.yaml structure**:
|
||||
|
||||
```yaml
|
||||
name: 'workflow-name'
|
||||
description: 'Clear purpose statement'
|
||||
|
||||
# Paths
|
||||
installed_path: '{project-root}/bmad/module/workflows/name'
|
||||
template: '{installed_path}/template.md'
|
||||
instructions: '{installed_path}/instructions.md'
|
||||
validation: '{installed_path}/checklist.md'
|
||||
|
||||
# Critical variables from config
|
||||
config_source: '{project-root}/bmad/module/config.yaml'
|
||||
output_folder: '{config_source}:output_folder'
|
||||
user_name: '{config_source}:user_name'
|
||||
communication_language: '{config_source}:communication_language'
|
||||
date: system-generated
|
||||
|
||||
# Output
|
||||
default_output_file: '{output_folder}/document.md'
|
||||
|
||||
# Invocation control
|
||||
standalone: true # or false based on step 2 decision
|
||||
```
|
||||
|
||||
Follow path conventions from guide:
|
||||
|
||||
- Use {project-root} for absolute paths
|
||||
|
||||
@ -29,6 +29,8 @@ installed_path: '{project-root}/bmad/module/workflows/my-workflow'
|
||||
template: '{installed_path}/template.md'
|
||||
instructions: '{installed_path}/instructions.md'
|
||||
default_output_file: '{output_folder}/output.md'
|
||||
|
||||
standalone: true
|
||||
```
|
||||
|
||||
```markdown
|
||||
@ -46,14 +48,14 @@ default_output_file: '{output_folder}/output.md'
|
||||
<critical>You MUST have already loaded and processed: workflow.yaml</critical>
|
||||
|
||||
<workflow>
|
||||
<step n="1" goal="Generate content">
|
||||
Create the main content for this document.
|
||||
<template-output>main_content</template-output>
|
||||
</step>
|
||||
<step n="1" goal="Generate content">
|
||||
Create the main content for this document.
|
||||
<template-output>main_content</template-output>
|
||||
</step>
|
||||
</workflow>
|
||||
```
|
||||
|
||||
That's it! To execute, tell the BMAD agent: `workflow my-workflow`
|
||||
That's it! To execute, tell the BMAD agent: `workflow path/to/my-workflow/`
|
||||
|
||||
## Core Concepts
|
||||
|
||||
@ -62,7 +64,7 @@ That's it! To execute, tell the BMAD agent: `workflow my-workflow`
|
||||
| Aspect | Task | Workflow |
|
||||
| -------------- | ------------------ | ----------------------- |
|
||||
| **Purpose** | Single operation | Multi-step process |
|
||||
| **Format** | XML in `.md` file | Folder with YAML config |
|
||||
| **Format** | XML | Folder with YAML config |
|
||||
| **Location** | `/src/core/tasks/` | `/bmad/*/workflows/` |
|
||||
| **User Input** | Minimal | Extensive |
|
||||
| **Output** | Variable | Usually documents |
|
||||
@ -91,7 +93,7 @@ my-workflow/
|
||||
├── template.md # Document structure
|
||||
├── instructions.md # Step-by-step guide
|
||||
├── checklist.md # Validation criteria
|
||||
└── [data files] # Supporting resources
|
||||
└── [data files] # Supporting resources, xml, md, csv or others
|
||||
```
|
||||
|
||||
### workflow.yaml Configuration
|
||||
@ -111,11 +113,121 @@ validation: '{installed_path}/checklist.md' # optional
|
||||
default_output_file: '{output_folder}/document.md'
|
||||
|
||||
# Advanced options
|
||||
autonomous: true # Skip user checkpoints
|
||||
recommended_inputs: # Expected input docs
|
||||
- input_doc: 'path/to/doc.md'
|
||||
|
||||
# Invocation control
|
||||
standalone: true # Can be invoked directly (default: true)
|
||||
```
|
||||
|
||||
### Standalone Property: Invocation Control
|
||||
|
||||
**CRITICAL**: The `standalone` property controls whether a workflow, task, or tool can be invoked independently or must be called through an agent's menu.
|
||||
|
||||
#### For Workflows (workflow.yaml)
|
||||
|
||||
```yaml
|
||||
standalone: true # Can invoke directly: /workflow-name or via IDE command
|
||||
standalone: false # Must be called from an agent menu or another workflow
|
||||
```
|
||||
|
||||
**When to use `standalone: true` (DEFAULT)**:
|
||||
|
||||
- ✅ User-facing workflows that should be directly accessible
|
||||
- ✅ Workflows invoked via IDE commands or CLI
|
||||
- ✅ Workflows that users will run independently
|
||||
- ✅ Most document generation workflows (PRD, architecture, etc.)
|
||||
- ✅ Action workflows users trigger directly (refactor, analyze, etc.)
|
||||
- ✅ Entry-point workflows for a module
|
||||
|
||||
**When to use `standalone: false`**:
|
||||
|
||||
- ✅ Sub-workflows only called by other workflows (via `<invoke-workflow>`)
|
||||
- ✅ Internal utility workflows not meant for direct user access
|
||||
- ✅ Workflows that require specific context from parent workflow
|
||||
- ✅ Helper workflows that don't make sense alone
|
||||
|
||||
**Examples**:
|
||||
|
||||
```yaml
|
||||
# Standalone: User invokes directly
|
||||
name: 'plan-project'
|
||||
description: 'Create PRD/GDD for any project'
|
||||
standalone: true # Users run this directly
|
||||
|
||||
---
|
||||
# Non-standalone: Only called by parent workflow
|
||||
name: 'validate-requirements'
|
||||
description: 'Internal validation helper for PRD workflow'
|
||||
standalone: false # Only invoked by plan-project workflow
|
||||
```
|
||||
|
||||
#### For Tasks and Tools (XML files)
|
||||
|
||||
Tasks and tools in `src/core/tasks/` and `src/core/tools/` also support the standalone attribute:
|
||||
|
||||
```xml
|
||||
<!-- Standalone task: Can be invoked directly -->
|
||||
<task name="workflow" standalone="true">
|
||||
<!-- Task definition -->
|
||||
</task>
|
||||
|
||||
<!-- Non-standalone: Only called by workflows/agents -->
|
||||
<tool name="internal-helper" standalone="false">
|
||||
<!-- Tool definition -->
|
||||
</tool>
|
||||
```
|
||||
|
||||
**Task/Tool Standalone Guidelines**:
|
||||
|
||||
- `standalone="true"`: Core tasks like workflow.xml, create-doc.xml that users/agents invoke directly
|
||||
- `standalone="false"`: Internal helpers, utilities only called by other tasks/workflows
|
||||
|
||||
#### Default Behavior
|
||||
|
||||
**If standalone property is omitted**:
|
||||
|
||||
- Workflows: Default to `standalone: true` (accessible directly)
|
||||
- Tasks/Tools: Default to `standalone: true` (accessible directly)
|
||||
|
||||
**Best Practice**: Explicitly set standalone even if using default to make intent clear.
|
||||
|
||||
#### Invocation Patterns
|
||||
|
||||
**Standalone workflows can be invoked**:
|
||||
|
||||
1. Directly by users: `/workflow-name` or IDE command
|
||||
2. From agent menus: `workflow: "{path}/workflow.yaml"`
|
||||
3. From other workflows: `<invoke-workflow path="{path}/workflow.yaml">`
|
||||
|
||||
**Non-standalone workflows**:
|
||||
|
||||
1. ❌ Cannot be invoked directly by users
|
||||
2. ❌ Cannot be called from IDE commands
|
||||
3. ✅ Can be invoked by other workflows via `<invoke-workflow>`
|
||||
4. ✅ Can be called from agent menu items
|
||||
|
||||
#### Module Design Implications
|
||||
|
||||
**Typical Module Pattern**:
|
||||
|
||||
```yaml
|
||||
# Entry-point workflows: standalone: true
|
||||
bmm/workflows/plan-project/workflow.yaml → standalone: true
|
||||
bmm/workflows/architecture/workflow.yaml → standalone: true
|
||||
|
||||
# Helper workflows: standalone: false
|
||||
bmm/workflows/internal/validate-epic/workflow.yaml → standalone: false
|
||||
bmm/workflows/internal/format-story/workflow.yaml → standalone: false
|
||||
```
|
||||
|
||||
**Benefits of this pattern**:
|
||||
|
||||
- Clear separation between user-facing and internal workflows
|
||||
- Prevents users from accidentally invoking incomplete/internal workflows
|
||||
- Cleaner IDE command palette (only shows standalone workflows)
|
||||
- Better encapsulation and maintainability
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**Full Document Workflow** (most common)
|
||||
@ -135,6 +247,395 @@ recommended_inputs: # Expected input docs
|
||||
|
||||
## Writing Instructions
|
||||
|
||||
### Instruction Styles: Intent-Based vs Prescriptive
|
||||
|
||||
**CRITICAL DESIGN DECISION**: Choose your instruction style early - it fundamentally shapes the user experience.
|
||||
|
||||
#### Default Recommendation: Intent-Based (Adaptive)
|
||||
|
||||
**Intent-based workflows give the AI goals and principles, letting it adapt the conversation naturally to the user's context.** This is the BMAD v6 default for most workflows.
|
||||
|
||||
#### The Two Approaches
|
||||
|
||||
##### 1. Intent-Based Instructions (RECOMMENDED)
|
||||
|
||||
**What it is**: Guide the AI with goals, principles, and context - let it determine the best way to interact with each user.
|
||||
|
||||
**Characteristics**:
|
||||
|
||||
- Uses `<action>` tags with guiding instructions
|
||||
- Focuses on WHAT to accomplish and WHY it matters
|
||||
- Lets AI adapt conversation to user needs
|
||||
- More flexible and conversational
|
||||
- Better for complex discovery and iterative refinement
|
||||
|
||||
**When to use**:
|
||||
|
||||
- Complex discovery processes (requirements gathering, architecture design)
|
||||
- Creative brainstorming and ideation
|
||||
- Iterative refinement workflows
|
||||
- When user input quality matters more than consistency
|
||||
- Workflows requiring adaptation to context
|
||||
- Teaching/educational workflows
|
||||
- When users have varying skill levels
|
||||
|
||||
**Example**:
|
||||
|
||||
```xml
|
||||
<step n="2" goal="Understand user's target audience">
|
||||
<action>Engage in collaborative discovery to understand their target users:
|
||||
|
||||
Ask open-ended questions to explore:
|
||||
- Who will use this product?
|
||||
- What problems do they face?
|
||||
- What are their goals and motivations?
|
||||
- How tech-savvy are they?
|
||||
|
||||
Listen for clues about:
|
||||
- Demographics and characteristics
|
||||
- Pain points and needs
|
||||
- Current solutions they use
|
||||
- Unmet needs or frustrations
|
||||
|
||||
Adapt your depth and terminology to the user's responses.
|
||||
If they give brief answers, dig deeper with follow-ups.
|
||||
If they're uncertain, help them think through it with examples.
|
||||
</action>
|
||||
|
||||
<template-output>target_audience</template-output>
|
||||
</step>
|
||||
```
|
||||
|
||||
**Intent-based workflow adapts**:
|
||||
|
||||
- **Expert user** might get: "Tell me about your target users - demographics, pain points, and technical profile?"
|
||||
- **Beginner user** might get: "Let's talk about who will use this. Imagine your ideal customer - what do they look like? What problem are they trying to solve?"
|
||||
|
||||
##### 2. Prescriptive Instructions (Use Selectively)
|
||||
|
||||
**What it is**: Provide exact wording for questions and specific options for answers.
|
||||
|
||||
**Characteristics**:
|
||||
|
||||
- Uses `<ask>` tags with exact question text
|
||||
- Provides specific options or formats
|
||||
- More controlled and predictable
|
||||
- Ensures consistency across runs
|
||||
- Better for simple data collection or compliance needs
|
||||
|
||||
**When to use**:
|
||||
|
||||
- Simple data collection (platform choice, format selection)
|
||||
- Compliance verification and standards adherence
|
||||
- Configuration with finite, well-defined options
|
||||
- When consistency is critical across all executions
|
||||
- Quick setup wizards
|
||||
- Binary decisions (yes/no, enable/disable)
|
||||
- When gathering specific required fields
|
||||
|
||||
**Example**:
|
||||
|
||||
```xml
|
||||
<step n="3" goal="Select target platform">
|
||||
<ask>What is your target platform?
|
||||
|
||||
1. Web (browser-based application)
|
||||
2. Mobile (iOS/Android native apps)
|
||||
3. Desktop (Windows/Mac/Linux applications)
|
||||
4. CLI (command-line tool)
|
||||
5. API (backend service)
|
||||
|
||||
Enter the number (1-5):</ask>
|
||||
|
||||
<action>Store the platform choice as {{target_platform}}</action>
|
||||
<template-output>target_platform</template-output>
|
||||
</step>
|
||||
```
|
||||
|
||||
**Prescriptive workflow stays consistent** - every user gets the same 5 options in the same format.
|
||||
|
||||
#### Best Practice: Mix Both Styles
|
||||
|
||||
**Even predominantly intent-based workflows should use prescriptive moments** for simple choices. Even prescriptive workflows can have intent-based discovery.
|
||||
|
||||
**Example of effective mixing**:
|
||||
|
||||
```xml
|
||||
<!-- Intent-based: Complex discovery -->
|
||||
<step n="1" goal="Understand user vision">
|
||||
<action>Explore the user's vision through open conversation:
|
||||
|
||||
Help them articulate:
|
||||
- The core problem they're solving
|
||||
- Their unique approach or innovation
|
||||
- The experience they want to create
|
||||
|
||||
Adapt your questions based on their expertise and communication style.
|
||||
If they're visionary, explore the "why". If they're technical, explore the "how".
|
||||
</action>
|
||||
<template-output>vision</template-output>
|
||||
</step>
|
||||
|
||||
<!-- Prescriptive: Simple data -->
|
||||
<step n="2" goal="Capture basic metadata">
|
||||
<ask>What is your target platform? Choose one:
|
||||
- Web
|
||||
- Mobile
|
||||
- Desktop
|
||||
- CLI
|
||||
- API</ask>
|
||||
|
||||
<action>Store as {{platform}}</action>
|
||||
</step>
|
||||
|
||||
<!-- Intent-based: Deep exploration -->
|
||||
<step n="3" goal="Design user experience">
|
||||
<action>Facilitate collaborative UX design:
|
||||
|
||||
Guide them to explore:
|
||||
- User journey and key flows
|
||||
- Interaction patterns and affordances
|
||||
- Visual/aesthetic direction
|
||||
|
||||
Use their platform choice from step 2 to inform relevant patterns.
|
||||
For web: discuss responsive design. For mobile: touch interactions. Etc.
|
||||
</action>
|
||||
<template-output>ux_design</template-output>
|
||||
</step>
|
||||
```
|
||||
|
||||
#### Interactivity Levels
|
||||
|
||||
Beyond style (intent vs prescriptive), consider **how interactive** your workflow should be:
|
||||
|
||||
##### High Interactivity (Collaborative)
|
||||
|
||||
- Constant back-and-forth with user
|
||||
- Multiple asks per step
|
||||
- Iterative refinement and review
|
||||
- User guides the direction
|
||||
- **Best for**: Creative work, complex decisions, learning
|
||||
|
||||
**Example**:
|
||||
|
||||
```xml
|
||||
<step n="4" goal="Design feature set" repeat="until-satisfied">
|
||||
<action>Collaborate on feature definitions:
|
||||
|
||||
For each feature the user proposes:
|
||||
- Help them articulate it clearly
|
||||
- Explore edge cases together
|
||||
- Consider implications and dependencies
|
||||
- Refine the description iteratively
|
||||
|
||||
After each feature: "Want to refine this, add another, or move on?"
|
||||
</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
##### Medium Interactivity (Guided)
|
||||
|
||||
- Key decision points have interaction
|
||||
- AI proposes, user confirms or refines
|
||||
- Validation checkpoints
|
||||
- **Best for**: Most document workflows, structured processes
|
||||
|
||||
**Example**:
|
||||
|
||||
```xml
|
||||
<step n="5" goal="Generate architecture decisions">
|
||||
<action>Based on the PRD, identify 10-15 key architectural decisions needed</action>
|
||||
<action>For each decision, research options and present recommendation</action>
|
||||
<ask>Approve this decision or propose alternative?</ask>
|
||||
<action>Record decision and rationale</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
##### Low Interactivity (Autonomous)
|
||||
|
||||
- Minimal user input required
|
||||
- AI works independently with guidelines
|
||||
- User reviews final output
|
||||
- **Best for**: Automated generation, batch processing
|
||||
|
||||
**Example**:
|
||||
|
||||
```xml
|
||||
<step n="6" goal="Generate user stories">
|
||||
<action>For each epic in the PRD, generate 3-7 user stories following this pattern:
|
||||
- As a [user type]
|
||||
- I want to [action]
|
||||
- So that [benefit]
|
||||
|
||||
Ensure stories are:
|
||||
- Independently valuable
|
||||
- Testable
|
||||
- Sized appropriately (1-5 days of work)
|
||||
</action>
|
||||
|
||||
<template-output>user_stories</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Review generated stories">
|
||||
<ask>Review the generated user stories. Want to refine any? (y/n)</ask>
|
||||
<check if="yes">
|
||||
<goto step="6">Regenerate with feedback</goto>
|
||||
</check>
|
||||
</step>
|
||||
```
|
||||
|
||||
#### Decision Framework
|
||||
|
||||
**Choose Intent-Based when**:
|
||||
|
||||
- ✅ User knowledge/skill level varies
|
||||
- ✅ Context matters (one-size-fits-all won't work)
|
||||
- ✅ Discovery and exploration are important
|
||||
- ✅ Quality of input matters more than consistency
|
||||
- ✅ Teaching/education is part of the goal
|
||||
- ✅ Iteration and refinement expected
|
||||
|
||||
**Choose Prescriptive when**:
|
||||
|
||||
- ✅ Options are finite and well-defined
|
||||
- ✅ Consistency across users is critical
|
||||
- ✅ Compliance or standards matter
|
||||
- ✅ Simple data collection
|
||||
- ✅ Users just need to make a choice and move on
|
||||
- ✅ Speed matters more than depth
|
||||
|
||||
**Choose High Interactivity when**:
|
||||
|
||||
- ✅ User expertise is essential
|
||||
- ✅ Creative collaboration needed
|
||||
- ✅ Decisions have major implications
|
||||
- ✅ Learning and understanding matter
|
||||
- ✅ Iteration is expected
|
||||
|
||||
**Choose Low Interactivity when**:
|
||||
|
||||
- ✅ Process is well-defined and repeatable
|
||||
- ✅ AI can work autonomously with clear guidelines
|
||||
- ✅ User time is constrained
|
||||
- ✅ Batch processing or automation desired
|
||||
- ✅ Review-and-refine model works
|
||||
|
||||
#### Implementation Guidelines
|
||||
|
||||
**For Intent-Based Workflows**:
|
||||
|
||||
1. **Use `<action>` tags with guiding instructions**
|
||||
|
||||
```xml
|
||||
<action>Facilitate discovery of {{topic}}:
|
||||
|
||||
Ask open-ended questions to explore:
|
||||
- {{aspect_1}}
|
||||
- {{aspect_2}}
|
||||
|
||||
Listen for clues about {{patterns_to_notice}}.
|
||||
|
||||
Adapt your approach based on their {{context_factor}}.
|
||||
</action>
|
||||
```
|
||||
|
||||
2. **Provide principles, not scripts**
|
||||
|
||||
```xml
|
||||
<!-- ✅ Good: Principles -->
|
||||
<action>Help user articulate their unique value proposition.
|
||||
Focus on what makes them different, not just what they do.
|
||||
If they struggle, offer examples from analogous domains.</action>
|
||||
|
||||
<!-- ❌ Avoid: Prescriptive script -->
|
||||
<ask>What makes your product unique? Provide 2-3 bullet points.</ask>
|
||||
```
|
||||
|
||||
3. **Guide with context and rationale**
|
||||
|
||||
```xml
|
||||
<action>Now that we understand their {{context_from_previous}},
|
||||
explore how {{current_topic}} connects to their vision.
|
||||
|
||||
This matters because {{reason_it_matters}}.
|
||||
|
||||
If they seem uncertain about {{potential_challenge}}, help them think through {{approach}}.
|
||||
</action>
|
||||
```
|
||||
|
||||
**For Prescriptive Workflows**:
|
||||
|
||||
1. **Use `<ask>` tags with specific questions**
|
||||
|
||||
```xml
|
||||
<ask>Select your preferred database:
|
||||
1. PostgreSQL
|
||||
2. MySQL
|
||||
3. MongoDB
|
||||
4. SQLite
|
||||
|
||||
Enter number (1-4):</ask>
|
||||
```
|
||||
|
||||
2. **Provide clear options and formats**
|
||||
|
||||
```xml
|
||||
<ask>Enable user authentication? (yes/no)</ask>
|
||||
<ask>Enter project name (lowercase, no spaces):</ask>
|
||||
```
|
||||
|
||||
3. **Keep it crisp and clear**
|
||||
|
||||
```xml
|
||||
<!-- ✅ Good: Clear and direct -->
|
||||
<ask>Target platform? (web/mobile/desktop)</ask>
|
||||
|
||||
<!-- ❌ Avoid: Over-explaining -->
|
||||
<ask>We need to know what platform you're building for. This will affect
|
||||
the technology stack recommendations. Please choose: web, mobile, or desktop.</ask>
|
||||
```
|
||||
|
||||
#### Mixing Styles Within a Workflow
|
||||
|
||||
**Pattern: Intent-based discovery → Prescriptive capture → Intent-based refinement**
|
||||
|
||||
```xml
|
||||
<step n="1" goal="Explore user needs">
|
||||
<!-- Intent-based discovery -->
|
||||
<action>Engage in open conversation to understand user needs deeply...</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Capture key metrics">
|
||||
<!-- Prescriptive data collection -->
|
||||
<ask>Expected daily active users? (number)</ask>
|
||||
<ask>Data sensitivity level? (public/internal/sensitive/highly-sensitive)</ask>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Design solution approach">
|
||||
<!-- Intent-based design -->
|
||||
<action>Collaborate on solution design, using the metrics from step 2 to inform scale and security decisions...</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
**Pattern: Prescriptive setup → Intent-based execution**
|
||||
|
||||
```xml
|
||||
<step n="1" goal="Quick setup">
|
||||
<!-- Prescriptive configuration -->
|
||||
<ask>Project type? (web-app/api/cli/library)</ask>
|
||||
<ask>Language? (typescript/python/go/rust)</ask>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Detailed design">
|
||||
<!-- Intent-based design -->
|
||||
<action>Now that we know it's a {{project_type}} in {{language}},
|
||||
let's explore the architecture in detail.
|
||||
|
||||
Guide them through design decisions appropriate for a {{project_type}}...
|
||||
</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```markdown
|
||||
@ -395,21 +896,21 @@ _Generated on {{date}}_
|
||||
|
||||
```xml
|
||||
<workflow>
|
||||
<step n="1" goal="Gather context">
|
||||
Load existing documents and understand project scope.
|
||||
<template-output>context</template-output>
|
||||
</step>
|
||||
<step n="1" goal="Gather context">
|
||||
Load existing documents and understand project scope.
|
||||
<template-output>context</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define requirements">
|
||||
Create functional and non-functional requirements.
|
||||
<template-output>requirements</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
</step>
|
||||
<step n="2" goal="Define requirements">
|
||||
Create functional and non-functional requirements.
|
||||
<template-output>requirements</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Validate">
|
||||
Check requirements against goals.
|
||||
<template-output>validated_requirements</template-output>
|
||||
</step>
|
||||
<step n="3" goal="Validate">
|
||||
Check requirements against goals.
|
||||
<template-output>validated_requirements</template-output>
|
||||
</step>
|
||||
</workflow>
|
||||
```
|
||||
|
||||
@ -441,20 +942,20 @@ Check requirements against goals.
|
||||
|
||||
```xml
|
||||
<workflow name="greenfield-app">
|
||||
<step n="1" goal="Discovery">
|
||||
<step n="1" goal="Discovery">
|
||||
<invoke-workflow>product-brief</invoke-workflow>
|
||||
<template-output>brief</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Requirements">
|
||||
<step n="2" goal="Requirements">
|
||||
<invoke-workflow input="{{brief}}">prd</invoke-workflow>
|
||||
<template-output>prd</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Architecture">
|
||||
<step n="3" goal="Architecture">
|
||||
<invoke-workflow input="{{prd}}">architecture</invoke-workflow>
|
||||
<template-output>architecture</template-output>
|
||||
</step>
|
||||
</step>
|
||||
</workflow>
|
||||
```
|
||||
|
||||
@ -463,9 +964,9 @@ Check requirements against goals.
|
||||
### Design Principles
|
||||
|
||||
1. **Keep steps focused** - Single goal per step
|
||||
2. **Limit scope** - 5-10 steps maximum
|
||||
2. **Limit scope** - 5-12 steps maximum
|
||||
3. **Build progressively** - Start simple, add detail
|
||||
4. **Checkpoint often** - Save after major sections
|
||||
4. **Checkpoint often** - Save after major workflow sections and ensure documents are being drafted from the start
|
||||
5. **Make sections optional** - Let users skip when appropriate
|
||||
|
||||
### Instruction Guidelines
|
||||
@ -539,7 +1040,7 @@ Web bundles allow workflows to be deployed as self-contained packages for web en
|
||||
|
||||
### Creating a Web Bundle
|
||||
|
||||
Add this section to your workflow.yaml:
|
||||
Add this section to your workflow.yaml ensuring critically all dependant files or workflows are listed:
|
||||
|
||||
```yaml
|
||||
web_bundle:
|
||||
@ -598,6 +1099,8 @@ web_bundle:
|
||||
# Sub-workflow reference
|
||||
validation_workflow: 'bmad/bmm/workflows/validate-requirements/workflow.yaml'
|
||||
|
||||
standalone: true
|
||||
|
||||
web_bundle_files:
|
||||
# Core workflow files
|
||||
- 'bmad/bmm/workflows/analyze-requirements/instructions.md'
|
||||
@ -636,14 +1139,9 @@ web_bundle:
|
||||
|
||||
- Combine related steps
|
||||
- Make sections optional
|
||||
- Create multiple focused workflows with a parent orchestration
|
||||
- Reduce elicitation points
|
||||
|
||||
### User Confusion
|
||||
|
||||
- Add clearer step goals
|
||||
- Provide more examples
|
||||
- Explain section purpose
|
||||
|
||||
---
|
||||
|
||||
_For implementation details, see:_
|
||||
|
||||
112
src/modules/bmb/workflows/edit-agent/README.md
Normal file
112
src/modules/bmb/workflows/edit-agent/README.md
Normal file
@ -0,0 +1,112 @@
|
||||
# Edit Agent Workflow
|
||||
|
||||
Interactive workflow for editing existing BMAD Core agents while maintaining best practices and conventions.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow helps you refine and improve existing agents by:
|
||||
|
||||
- Analyzing agents against BMAD Core best practices
|
||||
- Identifying issues and improvement opportunities
|
||||
- Providing guided editing for specific aspects
|
||||
- Validating changes against agent standards
|
||||
- Ensuring consistency with agent architecture
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this workflow when you need to:
|
||||
|
||||
- Fix issues in existing agents
|
||||
- Add new menu items or workflows
|
||||
- Improve agent persona or communication style
|
||||
- Update configuration handling
|
||||
- Convert between agent types (full/hybrid/standalone)
|
||||
- Optimize agent structure and clarity
|
||||
|
||||
## What You'll Need
|
||||
|
||||
- Path to the agent file you want to edit (.yaml or .md)
|
||||
- Understanding of what changes you want to make
|
||||
- Access to the agent documentation (loaded automatically)
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
1. **Load and analyze target agent** - Provide path to agent file
|
||||
2. **Analyze against best practices** - Automatic audit of agent structure
|
||||
3. **Select editing focus** - Choose what aspect to edit
|
||||
4. **Load relevant documentation** - Auto-loads guides based on your choice
|
||||
5. **Perform edits** - Review and approve changes iteratively
|
||||
6. **Validate all changes** - Comprehensive validation checklist
|
||||
7. **Generate change summary** - Summary of improvements made
|
||||
|
||||
## Editing Options
|
||||
|
||||
The workflow provides 12 focused editing options:
|
||||
|
||||
1. **Fix critical issues** - Address broken references, syntax errors
|
||||
2. **Add/fix standard config** - Ensure config loading and variable usage
|
||||
3. **Refine persona** - Improve role, communication style, principles
|
||||
4. **Update activation** - Modify activation steps and greeting
|
||||
5. **Manage menu items** - Add, remove, or reorganize commands
|
||||
6. **Update workflow references** - Fix paths, add new workflows
|
||||
7. **Enhance menu handlers** - Improve handler logic
|
||||
8. **Improve command triggers** - Refine asterisk commands
|
||||
9. **Optimize agent type** - Convert between full/hybrid/standalone
|
||||
10. **Add new capabilities** - Add menu items, workflows, features
|
||||
11. **Remove bloat** - Delete unused commands, redundant instructions
|
||||
12. **Full review and update** - Comprehensive improvements
|
||||
|
||||
## Agent Documentation Loaded
|
||||
|
||||
This workflow automatically loads:
|
||||
|
||||
- **Agent Types Guide** - Understanding full, hybrid, and standalone agents
|
||||
- **Agent Architecture** - Structure, activation, and menu patterns
|
||||
- **Command Patterns** - Menu handlers and command triggers
|
||||
- **Communication Styles** - Persona and communication guidance
|
||||
- **Workflow Execution Engine** - How agents execute workflows
|
||||
|
||||
## Output
|
||||
|
||||
The workflow modifies your agent file in place, maintaining the original format (YAML or markdown). Changes are reviewed and approved by you before being applied.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start with analysis** - Let the workflow audit your agent first
|
||||
- **Focus your edits** - Choose specific aspects to improve
|
||||
- **Review each change** - Approve or modify proposed changes
|
||||
- **Validate thoroughly** - Use the validation step to catch issues
|
||||
- **Test after editing** - Invoke the edited agent to verify it works
|
||||
|
||||
## Tips
|
||||
|
||||
- If you're unsure what needs improvement, choose option 12 (Full review)
|
||||
- For quick fixes, choose the specific option (like option 6 for workflow paths)
|
||||
- The workflow loads documentation automatically - you don't need to read it first
|
||||
- You can make multiple rounds of edits in one session
|
||||
- Use the validation step to ensure you didn't miss anything
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- **create-agent** - Create new agents from scratch
|
||||
- **edit-workflow** - Edit workflows referenced by agents
|
||||
- **audit-workflow** - Audit workflows for compliance
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
User: I want to add a new workflow to the PM agent
|
||||
Workflow: Analyzes agent → Loads it → You choose option 5 (manage menu items)
|
||||
→ Adds new menu item with workflow reference → Validates → Done
|
||||
```
|
||||
|
||||
## Activation
|
||||
|
||||
Invoke via BMad Builder agent:
|
||||
|
||||
```
|
||||
/bmad:bmb:agents:bmad-builder
|
||||
Then select: *edit-agent
|
||||
```
|
||||
|
||||
Or directly via workflow.xml with this workflow config.
|
||||
112
src/modules/bmb/workflows/edit-agent/checklist.md
Normal file
112
src/modules/bmb/workflows/edit-agent/checklist.md
Normal file
@ -0,0 +1,112 @@
|
||||
# Edit Agent - Validation Checklist
|
||||
|
||||
Use this checklist to validate agent edits meet BMAD Core standards.
|
||||
|
||||
## Agent Structure Validation
|
||||
|
||||
- [ ] Agent file format is valid (YAML or markdown/XML)
|
||||
- [ ] Agent type is clearly identified (full, hybrid, standalone)
|
||||
- [ ] File naming follows convention: `{agent-name}.agent.yaml` or `{agent-name}.agent.md`
|
||||
|
||||
## Persona Validation
|
||||
|
||||
- [ ] Role is clearly defined and specific
|
||||
- [ ] Identity/purpose articulates what the agent does
|
||||
- [ ] Communication style is specified (if custom style desired)
|
||||
- [ ] Principles are listed and actionable (if applicable)
|
||||
|
||||
## Activation Validation
|
||||
|
||||
- [ ] Step 1: Loads persona from current agent file
|
||||
- [ ] Step 2: Loads config file (if agent needs user context)
|
||||
- [ ] Step 3: Sets user context variables (user_name, etc.)
|
||||
- [ ] Step 4: Displays greeting using user_name and shows menu
|
||||
- [ ] Step 5: WAITs for user input (doesn't auto-execute)
|
||||
- [ ] Step 6: Processes user selection (number or trigger text)
|
||||
- [ ] Step 7: Executes appropriate menu handler
|
||||
|
||||
## Menu Validation
|
||||
|
||||
- [ ] All menu items numbered sequentially
|
||||
- [ ] Each item has cmd attribute with asterisk trigger (*help, *create, etc.)
|
||||
- [ ] Workflow paths are correct (if workflow attribute present)
|
||||
- [ ] Help command is present (\*help)
|
||||
- [ ] Exit command is present (\*exit)
|
||||
- [ ] Menu items are in logical order
|
||||
|
||||
## Configuration Validation
|
||||
|
||||
- [ ] Config file path is correct for module
|
||||
- [ ] Config variables loaded in activation step 2
|
||||
- [ ] Error handling present if config fails to load
|
||||
- [ ] user_name used in greeting and communication
|
||||
- [ ] communication_language used for output
|
||||
- [ ] output_folder used for file outputs (if applicable)
|
||||
|
||||
## Menu Handler Validation
|
||||
|
||||
- [ ] menu-handlers section is present
|
||||
- [ ] Workflow handler loads {project-root}/bmad/core/tasks/workflow.xml
|
||||
- [ ] Workflow handler passes yaml path as 'workflow-config' parameter
|
||||
- [ ] Handlers check for attributes (workflow, exec, tmpl, data, action)
|
||||
- [ ] Handler logic is complete and follows patterns
|
||||
|
||||
## Workflow Integration Validation
|
||||
|
||||
- [ ] All workflow paths exist and are correct
|
||||
- [ ] Workflow paths use {project-root} variable
|
||||
- [ ] Workflows are appropriate for agent's purpose
|
||||
- [ ] Workflow parameters are passed correctly
|
||||
|
||||
## Communication Validation
|
||||
|
||||
- [ ] Agent communicates in {communication_language}
|
||||
- [ ] Communication style matches persona
|
||||
- [ ] Error messages are clear and helpful
|
||||
- [ ] Confirmation messages for user actions
|
||||
|
||||
## Rules Validation
|
||||
|
||||
- [ ] Rules section defines agent behavior clearly
|
||||
- [ ] File loading rules are specified
|
||||
- [ ] Menu trigger format rules are clear
|
||||
- [ ] Communication rules align with persona
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, etc.)
|
||||
- [ ] No broken references or missing files
|
||||
- [ ] Syntax is valid (YAML or XML)
|
||||
- [ ] Indentation is consistent
|
||||
- [ ] Agent purpose is clear from reading persona alone
|
||||
|
||||
## Type-Specific Validation
|
||||
|
||||
### Full Agent
|
||||
|
||||
- [ ] Has complete menu system with multiple items
|
||||
- [ ] Loads config file for user context
|
||||
- [ ] Supports multiple workflows
|
||||
- [ ] Session management is clear
|
||||
|
||||
### Hybrid Agent
|
||||
|
||||
- [ ] Simplified activation (may skip some steps)
|
||||
- [ ] Focused set of workflows
|
||||
- [ ] May or may not have menu
|
||||
- [ ] Config loading is appropriate
|
||||
|
||||
### Standalone Agent
|
||||
|
||||
- [ ] Single focused purpose
|
||||
- [ ] Minimal activation (1-3 steps)
|
||||
- [ ] No menu system
|
||||
- [ ] Direct execution pattern
|
||||
- [ ] May not need config file
|
||||
|
||||
## Final Checks
|
||||
|
||||
- [ ] Agent file has been saved
|
||||
- [ ] File path is in correct module directory
|
||||
- [ ] Agent is ready for testing
|
||||
- [ ] Documentation is updated (if needed)
|
||||
290
src/modules/bmb/workflows/edit-agent/instructions.md
Normal file
290
src/modules/bmb/workflows/edit-agent/instructions.md
Normal file
@ -0,0 +1,290 @@
|
||||
# Edit Agent - Agent Editor Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
|
||||
<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and deeply understand the target agent">
|
||||
<ask>What is the path to the agent you want to edit?</ask>
|
||||
|
||||
<action>Load the agent file from the provided path</action>
|
||||
<action>Load ALL agent documentation to inform understanding:
|
||||
|
||||
- Agent types guide: {agent_types}
|
||||
- Agent architecture: {agent_architecture}
|
||||
- Command patterns: {agent_commands}
|
||||
- Communication styles: {communication_styles}
|
||||
- Workflow execution engine: {workflow_execution_engine}
|
||||
</action>
|
||||
|
||||
<action>Analyze the agent structure thoroughly:
|
||||
|
||||
- Parse persona (role, identity, communication_style, principles)
|
||||
- Understand activation flow and steps
|
||||
- Map menu items and their workflows
|
||||
- Identify configuration dependencies
|
||||
- Assess agent type (full, hybrid, standalone)
|
||||
- Check workflow references for validity
|
||||
- Evaluate against best practices from loaded guides
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
|
||||
Present a warm, conversational summary adapted to the agent's complexity:
|
||||
|
||||
- What this agent does (its role and purpose)
|
||||
- How it's structured (type, menu items, workflows)
|
||||
- What you notice (strengths, potential improvements, issues)
|
||||
- Your initial assessment of its health
|
||||
|
||||
Be conversational, not clinical. Help {user_name} see their agent through your eyes.
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of what this agent should do?</ask>
|
||||
<template-output>agent_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover improvement goals collaboratively">
|
||||
<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
|
||||
|
||||
<action>Engage in collaborative discovery:
|
||||
|
||||
Ask open-ended questions to understand their goals:
|
||||
|
||||
- What prompted you to want to edit this agent?
|
||||
- What isn't working the way you'd like?
|
||||
- Are there specific behaviors you want to change?
|
||||
- Is there functionality you want to add or remove?
|
||||
- How do users interact with this agent? What feedback have they given?
|
||||
|
||||
Listen for clues about:
|
||||
|
||||
- Functional issues (broken references, missing workflows)
|
||||
- User experience issues (confusing menu, unclear communication)
|
||||
- Performance issues (too slow, too verbose, not adaptive enough)
|
||||
- Maintenance issues (hard to update, bloated, inconsistent)
|
||||
- Integration issues (doesn't work well with other agents/workflows)
|
||||
</action>
|
||||
|
||||
<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
|
||||
|
||||
Organize by priority and user goals:
|
||||
|
||||
- CRITICAL issues blocking functionality
|
||||
- IMPORTANT improvements enhancing user experience
|
||||
- NICE-TO-HAVE enhancements for polish
|
||||
|
||||
Present these conversationally, explaining WHY each matters and HOW it would help.
|
||||
</action>
|
||||
|
||||
<action>Collaborate on priorities:
|
||||
|
||||
Don't just list options - discuss them:
|
||||
|
||||
- "I noticed {{issue}} - this could cause {{problem}}. Does this concern you?"
|
||||
- "The agent could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
|
||||
- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
|
||||
|
||||
Let the conversation flow naturally. Build a shared vision of what "better" looks like.
|
||||
</action>
|
||||
|
||||
<template-output>improvement_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
|
||||
<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
|
||||
|
||||
<action>For each improvement area, facilitate collaboratively:
|
||||
|
||||
1. **Explain the current state and why it matters**
|
||||
- Show relevant sections of the agent
|
||||
- Explain how it works now and implications
|
||||
- Connect to user's goals from step 2
|
||||
|
||||
2. **Propose improvements with rationale**
|
||||
- Suggest specific changes that align with best practices
|
||||
- Explain WHY each change helps
|
||||
- Provide examples from the loaded guides when helpful
|
||||
- Show before/after comparisons for clarity
|
||||
|
||||
3. **Collaborate on the approach**
|
||||
- Ask if the proposed change addresses their need
|
||||
- Invite modifications or alternative approaches
|
||||
- Explain tradeoffs when relevant
|
||||
- Adapt based on their feedback
|
||||
|
||||
4. **Apply changes iteratively**
|
||||
- Make one focused improvement at a time
|
||||
- Show the updated section
|
||||
- Confirm it meets their expectation
|
||||
- Move to next improvement or refine current one
|
||||
</action>
|
||||
|
||||
<action>Common improvement patterns to facilitate:
|
||||
|
||||
**If fixing broken references:**
|
||||
|
||||
- Identify all broken paths
|
||||
- Explain what each reference should point to
|
||||
- Verify new paths exist before updating
|
||||
- Update and confirm working
|
||||
|
||||
**If refining persona/communication:**
|
||||
|
||||
- Review current persona definition
|
||||
- Discuss desired communication style with examples
|
||||
- Explore communication styles guide for patterns
|
||||
- Refine language to match intent
|
||||
- Test tone with example interactions
|
||||
|
||||
**If updating activation:**
|
||||
|
||||
- Walk through current activation flow
|
||||
- Identify bottlenecks or confusion points
|
||||
- Propose streamlined flow
|
||||
- Ensure config loading works correctly
|
||||
- Verify all session variables are set
|
||||
|
||||
**If managing menu items:**
|
||||
|
||||
- Review current menu organization
|
||||
- Discuss if structure serves user mental model
|
||||
- Add/remove/reorganize as needed
|
||||
- Ensure all workflow references are valid
|
||||
- Update triggers to be intuitive
|
||||
|
||||
**If enhancing menu handlers:**
|
||||
|
||||
- Explain current handler logic
|
||||
- Identify where handlers could be smarter
|
||||
- Propose enhanced logic based on agent architecture patterns
|
||||
- Ensure handlers properly invoke workflows
|
||||
|
||||
**If optimizing agent type:**
|
||||
|
||||
- Discuss whether current type fits use case
|
||||
- Explain characteristics of full/hybrid/standalone
|
||||
- If converting, guide through structural changes
|
||||
- Ensure all pieces align with new type
|
||||
</action>
|
||||
|
||||
<action>Throughout improvements, educate when helpful:
|
||||
|
||||
Share insights from the guides naturally:
|
||||
|
||||
- "The agent architecture guide suggests {{pattern}} for this scenario"
|
||||
- "Looking at the command patterns, we could use {{approach}}"
|
||||
- "The communication styles guide has a great example of {{technique}}"
|
||||
|
||||
Connect improvements to broader BMAD principles without being preachy.
|
||||
</action>
|
||||
|
||||
<ask>After each significant change:
|
||||
|
||||
- "Does this feel right for what you're trying to achieve?"
|
||||
- "Want to refine this further, or move to the next improvement?"
|
||||
- "Is there anything about this change that concerns you?"
|
||||
</ask>
|
||||
|
||||
<template-output>improvement_implementation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Validate improvements holistically">
|
||||
<action>Run comprehensive validation conversationally:
|
||||
|
||||
Don't just check boxes - explain what you're validating and why it matters:
|
||||
|
||||
- "Let me verify all the workflow paths resolve correctly..."
|
||||
- "Checking that the activation flow works smoothly..."
|
||||
- "Making sure menu handlers are wired up properly..."
|
||||
- "Validating config loading is robust..."
|
||||
</action>
|
||||
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
<action>Check all items from checklist systematically</action>
|
||||
|
||||
<check if="validation_issues_found">
|
||||
<action>Present issues conversationally:
|
||||
|
||||
Explain what's wrong and implications:
|
||||
|
||||
- "I found {{issue}} which could cause {{problem}}"
|
||||
- "The {{component}} needs {{fix}} because {{reason}}"
|
||||
|
||||
Propose fixes immediately:
|
||||
|
||||
- "I can fix this by {{solution}}. Should I?"
|
||||
- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
|
||||
</action>
|
||||
|
||||
<action>Fix approved issues and re-validate</action>
|
||||
</check>
|
||||
|
||||
<check if="validation_passes">
|
||||
<action>Confirm success warmly:
|
||||
|
||||
"Excellent! Everything validates cleanly:
|
||||
|
||||
- All paths resolve correctly
|
||||
- Activation flow is solid
|
||||
- Menu structure is clear
|
||||
- Handlers work properly
|
||||
- Config loading is robust
|
||||
|
||||
Your agent is in great shape."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Review improvements and guide next steps">
|
||||
<action>Create a conversational summary of what improved:
|
||||
|
||||
Tell the story of the transformation:
|
||||
|
||||
- "We started with {{initial_state}}"
|
||||
- "You wanted to {{user_goals}}"
|
||||
- "We made these key improvements: {{changes_list}}"
|
||||
- "Now your agent {{improved_capabilities}}"
|
||||
|
||||
Highlight the impact:
|
||||
|
||||
- "This means users will experience {{benefit}}"
|
||||
- "The agent is now more {{quality}}"
|
||||
- "It follows best practices for {{patterns}}"
|
||||
</action>
|
||||
|
||||
<action>Guide next steps based on changes made:
|
||||
|
||||
If significant structural changes:
|
||||
|
||||
- "Since we restructured the activation, you should test the agent with a real user interaction"
|
||||
|
||||
If workflow references changed:
|
||||
|
||||
- "The agent now uses {{new_workflows}} - make sure those workflows are up to date"
|
||||
|
||||
If this is part of larger module work:
|
||||
|
||||
- "This agent is part of {{module}} - consider if other agents need similar improvements"
|
||||
|
||||
Be a helpful guide to what comes next, not just a task completer.
|
||||
</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- Test the edited agent by invoking it
|
||||
- Edit another agent
|
||||
- Make additional refinements to this one
|
||||
- Return to your module work
|
||||
</ask>
|
||||
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
35
src/modules/bmb/workflows/edit-agent/workflow.yaml
Normal file
35
src/modules/bmb/workflows/edit-agent/workflow.yaml
Normal file
@ -0,0 +1,35 @@
|
||||
# Edit Agent - Agent Editor Configuration
|
||||
name: "edit-agent"
|
||||
description: "Edit existing BMAD agents while following all best practices and conventions"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables load from config_source
|
||||
config_source: "{project-root}/bmad/bmb/config.yaml"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_name: "{config_source}:user_name"
|
||||
|
||||
# Required Data Files - Critical for understanding agent conventions
|
||||
agent_types: "{project-root}/bmad/bmb/workflows/create-agent/agent-types.md"
|
||||
agent_architecture: "{project-root}/bmad/bmb/workflows/create-agent/agent-architecture.md"
|
||||
agent_commands: "{project-root}/bmad/bmb/workflows/create-agent/agent-command-patterns.md"
|
||||
communication_styles: "{project-root}/bmad/bmb/workflows/create-agent/communication-styles.md"
|
||||
|
||||
# Workflow execution engine reference
|
||||
workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
|
||||
|
||||
# Optional docs that can be used to understand the target agent
|
||||
recommended_inputs:
|
||||
- target_agent: "Path to the agent.yaml or agent.md file to edit"
|
||||
- example_agents: "{project-root}/bmad/bmm/agents/"
|
||||
- agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.xml"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmb/workflows/edit-agent"
|
||||
template: false # This is an action workflow - no template needed
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
standalone: true
|
||||
|
||||
# Web bundle configuration
|
||||
web_bundle: false # BMB workflows run locally in BMAD-METHOD project
|
||||
187
src/modules/bmb/workflows/edit-module/README.md
Normal file
187
src/modules/bmb/workflows/edit-module/README.md
Normal file
@ -0,0 +1,187 @@
|
||||
# Edit Module Workflow
|
||||
|
||||
Interactive workflow for editing existing BMAD modules, including structure, agents, workflows, configuration, and documentation.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow helps you improve and maintain BMAD modules by:
|
||||
|
||||
- Analyzing module structure against best practices
|
||||
- Managing agents and workflows within the module
|
||||
- Updating configuration and documentation
|
||||
- Ensuring cross-module integration works correctly
|
||||
- Maintaining installer configuration (for source modules)
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this workflow when you need to:
|
||||
|
||||
- Add new agents or workflows to a module
|
||||
- Update module configuration
|
||||
- Improve module documentation
|
||||
- Reorganize module structure
|
||||
- Set up cross-module workflow sharing
|
||||
- Fix issues in module organization
|
||||
- Update installer configuration
|
||||
|
||||
## What You'll Need
|
||||
|
||||
- Path to the module directory you want to edit
|
||||
- Understanding of what changes you want to make
|
||||
- Access to module documentation (loaded automatically)
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
1. **Load and analyze target module** - Provide path to module directory
|
||||
2. **Analyze against best practices** - Automatic audit of module structure
|
||||
3. **Select editing focus** - Choose what aspect to edit
|
||||
4. **Load relevant documentation and tools** - Auto-loads guides and workflows
|
||||
5. **Perform edits** - Review and approve changes iteratively
|
||||
6. **Validate all changes** - Comprehensive validation checklist
|
||||
7. **Generate change summary** - Summary of improvements made
|
||||
|
||||
## Editing Options
|
||||
|
||||
The workflow provides 12 focused editing options:
|
||||
|
||||
1. **Fix critical issues** - Address missing files, broken references
|
||||
2. **Update module config** - Edit config.yaml fields
|
||||
3. **Manage agents** - Add, edit, or remove agents
|
||||
4. **Manage workflows** - Add, edit, or remove workflows
|
||||
5. **Update documentation** - Improve README files and guides
|
||||
6. **Reorganize structure** - Fix directory organization
|
||||
7. **Add new agent** - Create and integrate new agent
|
||||
8. **Add new workflow** - Create and integrate new workflow
|
||||
9. **Update installer** - Modify installer configuration (source only)
|
||||
10. **Cross-module integration** - Set up workflow sharing with other modules
|
||||
11. **Remove deprecated items** - Delete unused agents, workflows, or files
|
||||
12. **Full module review** - Comprehensive analysis and improvements
|
||||
|
||||
## Integration with Other Workflows
|
||||
|
||||
This workflow integrates with:
|
||||
|
||||
- **edit-agent** - For editing individual agents
|
||||
- **edit-workflow** - For editing individual workflows
|
||||
- **create-agent** - For adding new agents
|
||||
- **create-workflow** - For adding new workflows
|
||||
|
||||
When you select options to manage agents or workflows, the appropriate specialized workflow is invoked automatically.
|
||||
|
||||
## Module Structure
|
||||
|
||||
A proper BMAD module has:
|
||||
|
||||
```
|
||||
module-code/
|
||||
├── agents/ # Agent definitions
|
||||
│ └── *.agent.yaml
|
||||
├── workflows/ # Workflow definitions
|
||||
│ └── workflow-name/
|
||||
│ ├── workflow.yaml
|
||||
│ ├── instructions.md
|
||||
│ ├── checklist.md
|
||||
│ └── README.md
|
||||
├── config.yaml # Module configuration
|
||||
└── README.md # Module documentation
|
||||
```
|
||||
|
||||
## Standard Module Config
|
||||
|
||||
Every module config.yaml should have:
|
||||
|
||||
```yaml
|
||||
module_name: 'Full Module Name'
|
||||
module_code: 'xyz'
|
||||
user_name: 'User Name'
|
||||
communication_language: 'english'
|
||||
output_folder: 'path/to/output'
|
||||
```
|
||||
|
||||
Optional fields may be added for module-specific needs.
|
||||
|
||||
## Cross-Module Integration
|
||||
|
||||
Modules can share workflows:
|
||||
|
||||
```yaml
|
||||
# In agent menu item:
|
||||
workflow: '{project-root}/bmad/other-module/workflows/shared-workflow/workflow.yaml'
|
||||
```
|
||||
|
||||
Common patterns:
|
||||
|
||||
- BMM uses CIS brainstorming workflows
|
||||
- All modules can use core workflows
|
||||
- Modules can invoke each other's workflows
|
||||
|
||||
## Output
|
||||
|
||||
The workflow modifies module files in place, including:
|
||||
|
||||
- config.yaml
|
||||
- Agent files
|
||||
- Workflow files
|
||||
- README and documentation files
|
||||
- Directory structure (if reorganizing)
|
||||
|
||||
Changes are reviewed and approved by you before being applied.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start with analysis** - Let the workflow audit your module first
|
||||
- **Use specialized workflows** - Let edit-agent and edit-workflow handle detailed edits
|
||||
- **Update documentation** - Keep README files current with changes
|
||||
- **Validate thoroughly** - Use the validation step to catch structural issues
|
||||
- **Test after editing** - Invoke agents and workflows to verify they work
|
||||
|
||||
## Tips
|
||||
|
||||
- For adding agents/workflows, use options 7-8 to create and integrate in one step
|
||||
- For quick config changes, use option 2 (update module config)
|
||||
- Cross-module integration (option 10) helps set up workflow sharing
|
||||
- Full module review (option 12) is great for inherited or legacy modules
|
||||
- The workflow handles path updates when you reorganize structure
|
||||
|
||||
## Source vs Installed Modules
|
||||
|
||||
**Source modules** (in src/modules/):
|
||||
|
||||
- Have installer files in tools/cli/installers/
|
||||
- Can configure web bundles
|
||||
- Are the development source of truth
|
||||
|
||||
**Installed modules** (in bmad/):
|
||||
|
||||
- Are deployed to target projects
|
||||
- Use config.yaml for user customization
|
||||
- Are compiled from source during installation
|
||||
|
||||
This workflow works with both, but installer options only apply to source modules.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
User: I want to add a new workflow to BMM for API design
|
||||
Workflow: Analyzes BMM → You choose option 8 (add new workflow)
|
||||
→ Invokes create-workflow → Creates workflow
|
||||
→ Integrates it into module → Updates README → Done
|
||||
```
|
||||
|
||||
## Activation
|
||||
|
||||
Invoke via BMad Builder agent:
|
||||
|
||||
```
|
||||
/bmad:bmb:agents:bmad-builder
|
||||
Then select: *edit-module
|
||||
```
|
||||
|
||||
Or directly via workflow.xml with this workflow config.
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Module Structure Guide** - Comprehensive module architecture documentation
|
||||
- **BMM Module** - Example of full-featured module
|
||||
- **BMB Module** - Example of builder/tooling module
|
||||
- **CIS Module** - Example of workflow library module
|
||||
165
src/modules/bmb/workflows/edit-module/checklist.md
Normal file
165
src/modules/bmb/workflows/edit-module/checklist.md
Normal file
@ -0,0 +1,165 @@
|
||||
# Edit Module - Validation Checklist
|
||||
|
||||
Use this checklist to validate module edits meet BMAD Core standards.
|
||||
|
||||
## Module Structure Validation
|
||||
|
||||
- [ ] Module has clear 3-letter code (bmm, bmb, cis, etc.)
|
||||
- [ ] Module is in correct location (src/modules/ for source, bmad/ for installed)
|
||||
- [ ] agents/ directory exists
|
||||
- [ ] workflows/ directory exists
|
||||
- [ ] config.yaml exists in module root
|
||||
- [ ] README.md exists in module root
|
||||
- [ ] Directory structure follows BMAD conventions
|
||||
|
||||
## Configuration Validation
|
||||
|
||||
### Required Fields
|
||||
|
||||
- [ ] module_name is descriptive and clear
|
||||
- [ ] module_code is 3-letter code matching directory name
|
||||
- [ ] user_name field present
|
||||
- [ ] communication_language field present
|
||||
- [ ] output_folder field present
|
||||
|
||||
### Optional Fields (if used)
|
||||
|
||||
- [ ] custom_agent_location documented
|
||||
- [ ] custom_module_location documented
|
||||
- [ ] Module-specific fields documented in README
|
||||
|
||||
### File Quality
|
||||
|
||||
- [ ] config.yaml is valid YAML syntax
|
||||
- [ ] No duplicate keys
|
||||
- [ ] Values are appropriate types (strings, paths, etc.)
|
||||
- [ ] Comments explain non-obvious fields
|
||||
|
||||
## Agent Validation
|
||||
|
||||
### Agent Files
|
||||
|
||||
- [ ] All agents in agents/ directory
|
||||
- [ ] Agent files follow naming: {agent-name}.agent.yaml or .md
|
||||
- [ ] Agent filenames use kebab-case
|
||||
- [ ] No orphaned or temporary agent files
|
||||
|
||||
### Agent Content
|
||||
|
||||
- [ ] Each agent has clear role and purpose
|
||||
- [ ] Agents reference workflows correctly
|
||||
- [ ] Agent workflow paths are valid
|
||||
- [ ] Agents load module config correctly (if needed)
|
||||
- [ ] Agent menu items reference existing workflows
|
||||
|
||||
### Agent Integration
|
||||
|
||||
- [ ] All agents listed in module README
|
||||
- [ ] Agent relationships documented (if applicable)
|
||||
- [ ] Cross-agent workflows properly linked
|
||||
|
||||
## Workflow Validation
|
||||
|
||||
### Workflow Structure
|
||||
|
||||
- [ ] All workflows in workflows/ directory
|
||||
- [ ] Each workflow directory has workflow.yaml
|
||||
- [ ] Each workflow directory has instructions.md
|
||||
- [ ] Workflow directories use kebab-case naming
|
||||
- [ ] No orphaned or incomplete workflow directories
|
||||
|
||||
### Workflow Content
|
||||
|
||||
- [ ] workflow.yaml is valid YAML
|
||||
- [ ] workflow.yaml has name field
|
||||
- [ ] workflow.yaml has description field
|
||||
- [ ] workflow.yaml has author field
|
||||
- [ ] instructions.md has proper <workflow> structure
|
||||
- [ ] Workflow steps are numbered and logical
|
||||
|
||||
### Workflow Integration
|
||||
|
||||
- [ ] All workflows listed in module README
|
||||
- [ ] Workflow paths in agents are correct
|
||||
- [ ] Cross-module workflow references are valid
|
||||
- [ ] Sub-workflow references exist
|
||||
|
||||
## Documentation Validation
|
||||
|
||||
### Module README
|
||||
|
||||
- [ ] Module README describes purpose clearly
|
||||
- [ ] README lists all agents with descriptions
|
||||
- [ ] README lists all workflows with descriptions
|
||||
- [ ] README includes installation instructions (if applicable)
|
||||
- [ ] README explains module's role in BMAD ecosystem
|
||||
|
||||
### Workflow READMEs
|
||||
|
||||
- [ ] Each workflow has its own README.md
|
||||
- [ ] Workflow READMEs explain purpose
|
||||
- [ ] Workflow READMEs list inputs/outputs
|
||||
- [ ] Workflow READMEs include usage examples
|
||||
|
||||
### Other Documentation
|
||||
|
||||
- [ ] Usage guides present (if needed)
|
||||
- [ ] Architecture docs present (if complex module)
|
||||
- [ ] Examples provided (if applicable)
|
||||
|
||||
## Cross-References Validation
|
||||
|
||||
- [ ] Agent workflow references point to existing workflows
|
||||
- [ ] Workflow sub-workflow references are valid
|
||||
- [ ] Cross-module references use correct paths
|
||||
- [ ] Config file paths use {project-root} correctly
|
||||
- [ ] No hardcoded absolute paths
|
||||
|
||||
## Installer Validation (Source Modules Only)
|
||||
|
||||
- [ ] Installer script exists in tools/cli/installers/
|
||||
- [ ] Installer script name: install-{module-code}.js
|
||||
- [ ] Module metadata in installer is correct
|
||||
- [ ] Web bundle configuration valid (if applicable)
|
||||
- [ ] Installation paths are correct
|
||||
- [ ] Dependencies documented in installer
|
||||
|
||||
## Web Bundle Validation (If Applicable)
|
||||
|
||||
- [ ] Web bundles configured in workflow.yaml files
|
||||
- [ ] All referenced files included in web_bundle_files
|
||||
- [ ] Paths are bmad/-relative (not project-root)
|
||||
- [ ] No config_source references in web bundles
|
||||
- [ ] Invoked workflows included in dependencies
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No placeholder text remains ({MODULE_NAME}, {CODE}, etc.)
|
||||
- [ ] No broken file references
|
||||
- [ ] No duplicate content across files
|
||||
- [ ] Consistent naming conventions throughout
|
||||
- [ ] Module purpose is clear from README alone
|
||||
|
||||
## Integration Checks
|
||||
|
||||
- [ ] Module doesn't conflict with other modules
|
||||
- [ ] Shared resources properly documented
|
||||
- [ ] Dependencies on other modules explicit
|
||||
- [ ] Module can be installed independently (if designed that way)
|
||||
|
||||
## User Experience
|
||||
|
||||
- [ ] Module purpose is immediately clear
|
||||
- [ ] Agents have intuitive names
|
||||
- [ ] Workflows have descriptive names
|
||||
- [ ] Menu items are logically organized
|
||||
- [ ] Error messages are helpful
|
||||
- [ ] Success messages confirm actions
|
||||
|
||||
## Final Checks
|
||||
|
||||
- [ ] All files have been saved
|
||||
- [ ] File permissions are correct
|
||||
- [ ] Git status shows expected changes
|
||||
- [ ] Module is ready for testing
|
||||
- [ ] Documentation accurately reflects changes
|
||||
339
src/modules/bmb/workflows/edit-module/instructions.md
Normal file
339
src/modules/bmb/workflows/edit-module/instructions.md
Normal file
@ -0,0 +1,339 @@
|
||||
# Edit Module - Module Editor Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-module/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
|
||||
<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and deeply understand the target module">
|
||||
<ask>What is the path to the module you want to edit? (provide path to module directory like bmad/bmm/ or src/modules/bmm/)</ask>
|
||||
|
||||
<action>Load the module directory structure completely:
|
||||
|
||||
- Scan all directories and files
|
||||
- Load config.yaml
|
||||
- Load README.md
|
||||
- List all agents in agents/ directory
|
||||
- List all workflows in workflows/ directory
|
||||
- Check for installer files (if in src/modules/)
|
||||
- Identify any custom structure or patterns
|
||||
</action>
|
||||
|
||||
<action>Load ALL module documentation to inform understanding:
|
||||
|
||||
- Module structure guide: {module_structure_guide}
|
||||
- Study reference modules: BMM, BMB, CIS
|
||||
- Understand BMAD module patterns and conventions
|
||||
</action>
|
||||
|
||||
<action>Analyze the module deeply:
|
||||
|
||||
- Identify module purpose and role in BMAD ecosystem
|
||||
- Understand agent organization and relationships
|
||||
- Map workflow organization and dependencies
|
||||
- Evaluate config structure and completeness
|
||||
- Check documentation quality and currency
|
||||
- Assess installer configuration (if source module)
|
||||
- Identify cross-module integrations
|
||||
- Evaluate against best practices from loaded guides
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
|
||||
Present a warm, conversational summary adapted to the module's complexity:
|
||||
|
||||
- What this module provides (its purpose and value in BMAD)
|
||||
- How it's organized (agents, workflows, structure)
|
||||
- What you notice (strengths, potential improvements, issues)
|
||||
- How it fits in the larger BMAD ecosystem
|
||||
- Your initial assessment based on best practices
|
||||
|
||||
Be conversational and insightful. Help {user_name} see their module through your eyes.
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of what this module should provide?</ask>
|
||||
<template-output>module_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover improvement goals collaboratively">
|
||||
<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
|
||||
|
||||
<action>Engage in collaborative discovery:
|
||||
|
||||
Ask open-ended questions to understand their goals:
|
||||
|
||||
- What prompted you to want to edit this module?
|
||||
- What feedback have you gotten from users of this module?
|
||||
- Are there specific agents or workflows that need attention?
|
||||
- Is the module fulfilling its intended purpose?
|
||||
- Are there new capabilities you want to add?
|
||||
- How well does it integrate with other modules?
|
||||
- Is the documentation helping users understand and use the module?
|
||||
|
||||
Listen for clues about:
|
||||
|
||||
- Structural issues (poor organization, hard to navigate)
|
||||
- Agent/workflow issues (outdated, broken, missing functionality)
|
||||
- Configuration issues (missing fields, incorrect setup)
|
||||
- Documentation issues (outdated, incomplete, unclear)
|
||||
- Integration issues (doesn't work well with other modules)
|
||||
- Installer issues (installation problems, missing files)
|
||||
- User experience issues (confusing, hard to use)
|
||||
</action>
|
||||
|
||||
<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
|
||||
|
||||
Organize by priority and user goals:
|
||||
|
||||
- CRITICAL issues blocking module functionality
|
||||
- IMPORTANT improvements enhancing user experience
|
||||
- NICE-TO-HAVE enhancements for polish
|
||||
|
||||
Present these conversationally, explaining WHY each matters and HOW it would help.
|
||||
</action>
|
||||
|
||||
<action>Collaborate on priorities:
|
||||
|
||||
Don't just list options - discuss them:
|
||||
|
||||
- "I noticed {{issue}} - this could make it hard for users to {{problem}}. Want to address this?"
|
||||
- "The module could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
|
||||
- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
|
||||
|
||||
Let the conversation flow naturally. Build a shared vision of what "better" looks like.
|
||||
</action>
|
||||
|
||||
<template-output>improvement_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
|
||||
<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
|
||||
<critical>For agent and workflow edits, invoke specialized workflows rather than doing inline</critical>
|
||||
|
||||
<action>For each improvement area, facilitate collaboratively:
|
||||
|
||||
1. **Explain the current state and why it matters**
|
||||
- Show relevant sections of the module
|
||||
- Explain how it works now and implications
|
||||
- Connect to user's goals from step 2
|
||||
|
||||
2. **Propose improvements with rationale**
|
||||
- Suggest specific changes that align with best practices
|
||||
- Explain WHY each change helps
|
||||
- Provide examples from reference modules when helpful
|
||||
- Reference the structure guide's patterns naturally
|
||||
|
||||
3. **Collaborate on the approach**
|
||||
- Ask if the proposed change addresses their need
|
||||
- Invite modifications or alternative approaches
|
||||
- Explain tradeoffs when relevant
|
||||
- Adapt based on their feedback
|
||||
|
||||
4. **Apply changes appropriately**
|
||||
- For agent edits: Invoke edit-agent workflow
|
||||
- For workflow edits: Invoke edit-workflow workflow
|
||||
- For module-level changes: Make directly and iteratively
|
||||
- Show updates and confirm satisfaction
|
||||
</action>
|
||||
|
||||
<action>Common improvement patterns to facilitate:
|
||||
|
||||
**If improving module organization:**
|
||||
|
||||
- Discuss how the current structure serves (or doesn't serve) users
|
||||
- Propose reorganization that aligns with mental models
|
||||
- Consider feature-based vs type-based organization
|
||||
- Plan the reorganization steps
|
||||
- Update all references after moving files
|
||||
|
||||
**If updating module configuration:**
|
||||
|
||||
- Review current config.yaml fields
|
||||
- Check for missing standard fields (user_name, communication_language, output_folder)
|
||||
- Add module-specific fields as needed
|
||||
- Remove unused or outdated fields
|
||||
- Ensure config is properly documented
|
||||
|
||||
**If managing agents:**
|
||||
|
||||
- Ask which agent needs attention and why
|
||||
- For editing existing agent: <invoke-workflow path="{agent_editor}">
|
||||
- For adding new agent: Guide creation and integration
|
||||
- For removing agent: Confirm, remove, update references
|
||||
- Ensure all agent references in workflows remain valid
|
||||
|
||||
**If managing workflows:**
|
||||
|
||||
- Ask which workflow needs attention and why
|
||||
- For editing existing workflow: <invoke-workflow path="{workflow_editor}">
|
||||
- For adding new workflow: Guide creation and integration
|
||||
- For removing workflow: Confirm, remove, update agent references
|
||||
- Ensure all workflow files are properly organized
|
||||
|
||||
**If improving documentation:**
|
||||
|
||||
- Review current README and identify gaps
|
||||
- Discuss what users need to know
|
||||
- Update module overview and purpose
|
||||
- List agents and workflows with clear descriptions
|
||||
- Add usage examples if helpful
|
||||
- Ensure installation/setup instructions are clear
|
||||
|
||||
**If setting up cross-module integration:**
|
||||
|
||||
- Identify which workflows from other modules are needed
|
||||
- Show how to reference workflows properly: {project-root}/bmad/{{module}}/workflows/{{workflow}}/workflow.yaml
|
||||
- Document the integration in README
|
||||
- Ensure dependencies are clear
|
||||
- Consider adding example usage
|
||||
|
||||
**If updating installer (source modules only):**
|
||||
|
||||
- Review installer script for correctness
|
||||
- Check web bundle configurations
|
||||
- Verify all files are included
|
||||
- Test installation paths
|
||||
- Update module metadata
|
||||
</action>
|
||||
|
||||
<action>When invoking specialized workflows:
|
||||
|
||||
Explain why you're handing off:
|
||||
|
||||
- "This agent needs detailed attention. Let me invoke the edit-agent workflow to give it proper focus."
|
||||
- "The workflow editor can handle this more thoroughly. I'll pass control there."
|
||||
|
||||
After the specialized workflow completes, return and continue:
|
||||
|
||||
- "Great! That agent/workflow is updated. Want to work on anything else in the module?"
|
||||
</action>
|
||||
|
||||
<action>Throughout improvements, educate when helpful:
|
||||
|
||||
Share insights from the guides naturally:
|
||||
|
||||
- "The module structure guide recommends {{pattern}} for this scenario"
|
||||
- "Looking at how BMM organized this, we could use {{approach}}"
|
||||
- "The BMAD convention is to {{pattern}} which helps with {{benefit}}"
|
||||
|
||||
Connect improvements to broader BMAD principles without being preachy.
|
||||
</action>
|
||||
|
||||
<ask>After each significant change:
|
||||
|
||||
- "Does this organization feel more intuitive?"
|
||||
- "Want to refine this further, or move to the next improvement?"
|
||||
- "How does this change affect users of the module?"
|
||||
</ask>
|
||||
|
||||
<template-output>improvement_implementation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Validate improvements holistically">
|
||||
<action>Run comprehensive validation conversationally:
|
||||
|
||||
Don't just check boxes - explain what you're validating and why it matters:
|
||||
|
||||
- "Let me verify the module structure is solid..."
|
||||
- "Checking that all agent workflow references are valid..."
|
||||
- "Making sure config.yaml has all necessary fields..."
|
||||
- "Validating documentation is complete and accurate..."
|
||||
- "Ensuring cross-module references work correctly..."
|
||||
</action>
|
||||
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
<action>Check all items from checklist systematically</action>
|
||||
|
||||
<check if="validation_issues_found">
|
||||
<action>Present issues conversationally:
|
||||
|
||||
Explain what's wrong and implications:
|
||||
|
||||
- "I found {{issue}} which could cause {{problem}} for users"
|
||||
- "The {{component}} needs {{fix}} because {{reason}}"
|
||||
|
||||
Propose fixes immediately:
|
||||
|
||||
- "I can fix this by {{solution}}. Should I?"
|
||||
- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
|
||||
</action>
|
||||
|
||||
<action>Fix approved issues and re-validate</action>
|
||||
</check>
|
||||
|
||||
<check if="validation_passes">
|
||||
<action>Confirm success warmly:
|
||||
|
||||
"Excellent! Everything validates cleanly:
|
||||
|
||||
- Module structure is well-organized
|
||||
- All agent and workflow references are valid
|
||||
- Configuration is complete
|
||||
- Documentation is thorough and current
|
||||
- Cross-module integrations work properly
|
||||
- Installer is correct (if applicable)
|
||||
|
||||
Your module is in great shape."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Review improvements and guide next steps">
|
||||
<action>Create a conversational summary of what improved:
|
||||
|
||||
Tell the story of the transformation:
|
||||
|
||||
- "We started with {{initial_state}}"
|
||||
- "You wanted to {{user_goals}}"
|
||||
- "We made these key improvements: {{changes_list}}"
|
||||
- "Now your module {{improved_capabilities}}"
|
||||
|
||||
Highlight the impact:
|
||||
|
||||
- "This means users will experience {{benefit}}"
|
||||
- "The module is now more {{quality}}"
|
||||
- "It follows best practices for {{patterns}}"
|
||||
</action>
|
||||
|
||||
<action>Guide next steps based on changes made:
|
||||
|
||||
If structure changed significantly:
|
||||
|
||||
- "Since we reorganized the structure, you should update any external references to this module"
|
||||
|
||||
If agents or workflows were updated:
|
||||
|
||||
- "The updated agents/workflows should be tested with real user interactions"
|
||||
|
||||
If cross-module integration was added:
|
||||
|
||||
- "Test the integration with {{other_module}} to ensure it works smoothly"
|
||||
|
||||
If installer was updated:
|
||||
|
||||
- "Test the installation process to verify all files are included correctly"
|
||||
|
||||
If this is part of larger BMAD work:
|
||||
|
||||
- "Consider if patterns from this module could benefit other modules"
|
||||
|
||||
Be a helpful guide to what comes next, not just a task completer.
|
||||
</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- Test the edited module by invoking one of its agents
|
||||
- Edit a specific agent or workflow in more detail
|
||||
- Make additional refinements to the module
|
||||
- Work on a different module
|
||||
</ask>
|
||||
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
36
src/modules/bmb/workflows/edit-module/workflow.yaml
Normal file
36
src/modules/bmb/workflows/edit-module/workflow.yaml
Normal file
@ -0,0 +1,36 @@
|
||||
# Edit Module - Module Editor Configuration
|
||||
name: "edit-module"
|
||||
description: "Edit existing BMAD modules (structure, agents, workflows, documentation) while following all best practices"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables load from config_source
|
||||
config_source: "{project-root}/bmad/bmb/config.yaml"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_name: "{config_source}:user_name"
|
||||
|
||||
# Required Data Files - Critical for understanding module conventions
|
||||
module_structure_guide: "{project-root}/bmad/bmb/workflows/create-module/module-structure.md"
|
||||
|
||||
# Related workflow editors
|
||||
agent_editor: "{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml"
|
||||
workflow_editor: "{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml"
|
||||
|
||||
# Optional docs that can be used to understand the target module
|
||||
recommended_inputs:
|
||||
- target_module: "Path to the module directory to edit"
|
||||
- bmm_module: "{project-root}/bmad/bmm/"
|
||||
- bmb_module: "{project-root}/bmad/bmb/"
|
||||
- cis_module: "{project-root}/bmad/cis/"
|
||||
- existing_agents: "{project-root}/bmad/*/agents/"
|
||||
- existing_workflows: "{project-root}/bmad/*/workflows/"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmb/workflows/edit-module"
|
||||
template: false # This is an action workflow - no template needed
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
standalone: true
|
||||
|
||||
# Web bundle configuration
|
||||
web_bundle: false # BMB workflows run locally in BMAD-METHOD project
|
||||
@ -2,404 +2,341 @@
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml</critical>
|
||||
<critical>Study the workflow creation guide thoroughly at: {workflow_creation_guide}</critical>
|
||||
<critical>Communicate in {communication_language} throughout the workflow editing process</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
|
||||
<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and analyze target workflow">
|
||||
<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow folder)</ask>
|
||||
<step n="1" goal="Load and deeply understand the target workflow">
|
||||
<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow directory)</ask>
|
||||
|
||||
<action>Load the workflow.yaml file from the provided path</action>
|
||||
<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
|
||||
<action>List all associated files (template.md, instructions.md, checklist.md, data files)</action>
|
||||
<action>Load any existing instructions.md and template.md files if present</action>
|
||||
<action>Load the target workflow completely:
|
||||
|
||||
Display a summary:
|
||||
|
||||
- Workflow name and description
|
||||
- Type of workflow
|
||||
- Files present
|
||||
- Current structure overview
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Analyze against best practices">
|
||||
<action>Load the complete workflow creation guide from: {workflow_creation_guide}</action>
|
||||
<action>Check the workflow against the guide's best practices:</action>
|
||||
|
||||
Analyze for:
|
||||
|
||||
- **Critical headers**: Are workflow engine references present?
|
||||
- **File structure**: Are all expected files present for this workflow type?
|
||||
- **Variable consistency**: Do variable names match between files?
|
||||
- **Step structure**: Are steps properly numbered and focused?
|
||||
- **XML tags**: Are tags used correctly and consistently?
|
||||
- **Instructions clarity**: Are instructions specific with examples and limits?
|
||||
- **Template variables**: Use snake_case and descriptive names?
|
||||
- **Validation criteria**: Are checklist items measurable and specific?
|
||||
|
||||
**Standard Config Audit:**
|
||||
|
||||
- **workflow.yaml config block**: Check for standard config variables
|
||||
- Is config_source defined?
|
||||
- Are output_folder, user_name, communication_language pulled from config?
|
||||
- Is date set to system-generated?
|
||||
- **Instructions usage**: Do instructions use config variables?
|
||||
- Does it communicate in {communication_language}?
|
||||
- Does it address {user_name}?
|
||||
- Does it write to {output_folder}?
|
||||
- **Template usage**: Does template.md include config variables in metadata?
|
||||
|
||||
**YAML/File Alignment:**
|
||||
|
||||
- **Unused yaml fields**: Are there variables in workflow.yaml not used in instructions OR template?
|
||||
- **Missing variables**: Are there hardcoded values that should be variables?
|
||||
- **Web bundle completeness**: If web_bundle exists, does it include all dependencies?
|
||||
- All referenced files listed?
|
||||
- Called workflows included?
|
||||
|
||||
<action>Create a list of identified issues or improvement opportunities</action>
|
||||
<action>Prioritize issues by importance (critical, important, nice-to-have)</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Select editing focus">
|
||||
Present the editing menu to the user:
|
||||
|
||||
**What aspect would you like to edit?**
|
||||
|
||||
1. **Fix critical issues** - Address missing headers, broken references
|
||||
2. **Add/fix standard config** - Ensure standard config block and variable usage
|
||||
3. **Update workflow.yaml** - Modify configuration, paths, metadata
|
||||
4. **Refine instructions** - Improve steps, add detail, fix flow
|
||||
5. **Update template** - Fix variables, improve structure (if applicable)
|
||||
6. **Enhance validation** - Make checklist more specific and measurable
|
||||
7. **Add new features** - Add steps, optional sections, or capabilities
|
||||
8. **Configure web bundle** - Add/update web bundle for deployment
|
||||
9. **Remove bloat** - Delete unused yaml fields, duplicate values
|
||||
10. **Optimize for clarity** - Improve descriptions, add examples
|
||||
11. **Adjust instruction style** - Convert between intent-based and prescriptive styles
|
||||
12. **Full review and update** - Comprehensive improvements across all files
|
||||
|
||||
<ask>Select an option (1-12) or describe a custom edit:</ask>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Load relevant documentation">
|
||||
Based on the selected edit type, load appropriate reference materials:
|
||||
|
||||
<check if="option 2 (Add/fix standard config) selected">
|
||||
<action>Prepare standard config block template:</action>
|
||||
|
||||
```yaml
|
||||
# Critical variables from config
|
||||
config_source: '{project-root}/bmad/{module}/config.yaml'
|
||||
output_folder: '{config_source}:output_folder'
|
||||
user_name: '{config_source}:user_name'
|
||||
communication_language: '{config_source}:communication_language'
|
||||
date: system-generated
|
||||
```
|
||||
|
||||
<action>Check if workflow.yaml has existing config section (don't duplicate)</action>
|
||||
<action>Identify missing config variables to add</action>
|
||||
<action>Check instructions.md for config variable usage</action>
|
||||
<action>Check template.md for config variable usage</action>
|
||||
</check>
|
||||
|
||||
<check if="editing instructions or adding features">
|
||||
<action>Review the "Writing Instructions" section of the creation guide</action>
|
||||
<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
|
||||
</check>
|
||||
|
||||
<check if="editing templates">
|
||||
<action>Review the "Templates and Variables" section of the creation guide</action>
|
||||
<action>Ensure variable naming conventions are followed</action>
|
||||
</check>
|
||||
|
||||
<action if="editing validation">Review the "Validation" section and measurable criteria examples</action>
|
||||
|
||||
<check if="option 9 (Remove bloat) selected">
|
||||
<action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
|
||||
<action>Identify yaml fields not used in any file</action>
|
||||
<action>Check for duplicate fields in web_bundle section</action>
|
||||
</check>
|
||||
|
||||
<check if="configuring web bundle">
|
||||
<action>Review the "Web Bundles" section of the creation guide</action>
|
||||
<action>Scan all workflow files for referenced resources</action>
|
||||
<action>Create inventory of all files that must be included</action>
|
||||
<action>Scan instructions for invoke-workflow calls - those yamls must be included</action>
|
||||
</check>
|
||||
|
||||
<check if="fixing critical issues">
|
||||
<action>Load the workflow execution engine documentation</action>
|
||||
<action>Verify all required elements are present</action>
|
||||
</check>
|
||||
|
||||
<check if="adjusting instruction style (option 11) selected">
|
||||
<action>Analyze current instruction style in instructions.md:</action>
|
||||
|
||||
- Count action tags vs ask tags
|
||||
- Identify goal-oriented language ("guide", "explore", "help") vs prescriptive ("choose", "select", "specify")
|
||||
- Assess whether steps are open-ended or structured with specific options
|
||||
<action>Determine current dominant style: intent-based, prescriptive, or mixed</action>
|
||||
<action>Load the instruction style guide section from create-workflow</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Perform edits" repeat="until-complete">
|
||||
Based on the selected focus area:
|
||||
|
||||
<check if="configuring web bundle (option 7) selected">
|
||||
<action>Check if web_bundle section exists in workflow.yaml</action>
|
||||
|
||||
If creating new web bundle:
|
||||
|
||||
1. Extract workflow metadata (name, description, author)
|
||||
2. Convert all file paths to bmad/-relative format
|
||||
3. Remove any {config_source} references
|
||||
4. Scan instructions.md for all file references:
|
||||
- Data files (CSV, JSON)
|
||||
- Sub-workflows
|
||||
- Shared templates
|
||||
- Any included files
|
||||
5. Scan template.md for any includes
|
||||
6. Create complete web_bundle_files array
|
||||
7. **CRITICAL**: Check for invoke-workflow calls in instructions:
|
||||
- If workflow invokes other workflows, add existing_workflows field
|
||||
- Maps workflow variable name to bmad/-relative path
|
||||
- Signals bundler to recursively include invoked workflow's web_bundle
|
||||
- Example: `existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"`
|
||||
8. Generate web_bundle section
|
||||
|
||||
If updating existing web bundle:
|
||||
|
||||
1. Verify all paths are bmad/-relative
|
||||
2. Check for missing files in web_bundle_files
|
||||
3. Remove any config dependencies
|
||||
4. Update file list with newly referenced files
|
||||
</check>
|
||||
|
||||
<check if="adjusting instruction style (option 11) selected">
|
||||
<action>Present current style analysis to user:</action>
|
||||
|
||||
**Current Instruction Style Analysis:**
|
||||
|
||||
- Current dominant style: {{detected_style}}
|
||||
- Intent-based elements: {{intent_count}}
|
||||
- Prescriptive elements: {{prescriptive_count}}
|
||||
|
||||
**Understanding Intent-Based vs Prescriptive:**
|
||||
|
||||
**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally
|
||||
|
||||
- More flexible and conversational
|
||||
- LLM chooses appropriate questions based on context
|
||||
- Better for complex discovery and iterative refinement
|
||||
- Example: `<action>Guide user to define their target audience with specific demographics and needs</action>`
|
||||
|
||||
**2. Prescriptive** - Provide exact wording for questions and options
|
||||
|
||||
- More controlled and predictable
|
||||
- Ensures consistency across runs
|
||||
- Better for simple data collection or specific compliance needs
|
||||
- Example: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
|
||||
|
||||
**When to use Intent-Based:**
|
||||
|
||||
- Complex discovery processes (user research, requirements gathering)
|
||||
- Creative brainstorming and ideation
|
||||
- Iterative refinement workflows
|
||||
- When user input quality matters more than consistency
|
||||
- Workflows requiring adaptation to context
|
||||
|
||||
**When to use Prescriptive:**
|
||||
|
||||
- Simple data collection (platform, format, yes/no choices)
|
||||
- Compliance verification and standards adherence
|
||||
- Configuration with finite options
|
||||
- When consistency is critical across all executions
|
||||
- Quick setup wizards
|
||||
|
||||
**Best Practice: Mix Both Styles**
|
||||
|
||||
Even workflows with a primary style should use the other when appropriate. For example:
|
||||
|
||||
```xml
|
||||
<!-- Intent-based workflow with prescriptive moments -->
|
||||
<step n="1" goal="Understand user vision">
|
||||
<action>Explore the user's vision, uncovering their creative intent and target experience</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Capture basic metadata">
|
||||
<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask> <!-- Prescriptive for simple choice -->
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Deep dive into details">
|
||||
<action>Guide user to articulate their approach, exploring mechanics and unique aspects</action> <!-- Back to intent-based -->
|
||||
</step>
|
||||
```
|
||||
|
||||
<ask>What would you like to do?
|
||||
|
||||
1. **Make more intent-based** - Convert prescriptive ask tags to goal-oriented action tags where appropriate
|
||||
2. **Make more prescriptive** - Convert open-ended action tags to specific ask tags with options
|
||||
3. **Optimize mix** - Use intent-based for complex steps, prescriptive for simple data collection
|
||||
4. **Review specific steps** - Show me each step and let me decide individually
|
||||
5. **Cancel** - Keep current style
|
||||
|
||||
Select option (1-5):</ask>
|
||||
|
||||
<action>Store user's style adjustment preference as {{style_adjustment_choice}}</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 1 (make more intent-based)">
|
||||
<action>Identify prescriptive ask tags that could be converted to intent-based action tags</action>
|
||||
<action>For each candidate conversion:
|
||||
|
||||
- Show original prescriptive version
|
||||
- Suggest intent-based alternative focused on goals
|
||||
- Explain the benefit of the conversion
|
||||
- Ask for approval
|
||||
- workflow.yaml configuration
|
||||
- instructions.md (if exists)
|
||||
- template.md (if exists)
|
||||
- checklist.md (if exists)
|
||||
- Any additional data files referenced
|
||||
</action>
|
||||
<action>Apply approved conversions</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 2 (make more prescriptive)">
|
||||
<action>Identify open-ended action tags that could be converted to prescriptive ask tags</action>
|
||||
<action>For each candidate conversion:
|
||||
<action>Load ALL workflow documentation to inform understanding:
|
||||
|
||||
- Show original intent-based version
|
||||
- Suggest prescriptive alternative with specific options
|
||||
- Explain when prescriptive is better here
|
||||
- Ask for approval
|
||||
- Workflow creation guide: {workflow_creation_guide}
|
||||
- Workflow execution engine: {workflow_execution_engine}
|
||||
- Study example workflows from: {project-root}/bmad/bmm/workflows/
|
||||
</action>
|
||||
<action>Apply approved conversions</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 3 (optimize mix)">
|
||||
<action>Analyze each step for complexity and purpose</action>
|
||||
<action>Recommend style for each step:
|
||||
<action>Analyze the workflow deeply:
|
||||
|
||||
- Simple data collection → Prescriptive
|
||||
- Complex discovery → Intent-based
|
||||
- Binary decisions → Prescriptive
|
||||
- Creative exploration → Intent-based
|
||||
- Standards/compliance → Prescriptive
|
||||
- Iterative refinement → Intent-based
|
||||
- Identify workflow type (document, action, interactive, autonomous, meta)
|
||||
- Understand purpose and user journey
|
||||
- Map out step flow and logic
|
||||
- Check variable consistency across files
|
||||
- Evaluate instruction style (intent-based vs prescriptive)
|
||||
- Assess template structure (if applicable)
|
||||
- Review validation criteria
|
||||
- Identify config dependencies
|
||||
- Check for web bundle configuration
|
||||
- Evaluate against best practices from loaded guides
|
||||
</action>
|
||||
<action>Show recommendations with reasoning</action>
|
||||
<action>Apply approved optimizations</action>
|
||||
</check>
|
||||
|
||||
<check if="choice is 4 (review specific steps)">
|
||||
<action>Present each step one at a time</action>
|
||||
<action>For each step:
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
|
||||
- Show current instruction text
|
||||
- Identify current style (intent-based, prescriptive, or mixed)
|
||||
- Offer to keep, convert to intent-based, or convert to prescriptive
|
||||
- Apply user's choice before moving to next step
|
||||
Present a warm, conversational summary adapted to the workflow's complexity:
|
||||
|
||||
- What this workflow accomplishes (its purpose and value)
|
||||
- How it's structured (type, steps, interactive points)
|
||||
- What you notice (strengths, potential improvements, issues)
|
||||
- Your initial assessment based on best practices
|
||||
- How it fits in the larger BMAD ecosystem
|
||||
|
||||
Be conversational and insightful. Help {user_name} see their workflow through your eyes.
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of what this workflow should accomplish?</ask>
|
||||
<template-output>workflow_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover improvement goals collaboratively">
|
||||
<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
|
||||
|
||||
<action>Engage in collaborative discovery:
|
||||
|
||||
Ask open-ended questions to understand their goals:
|
||||
|
||||
- What prompted you to want to edit this workflow?
|
||||
- What feedback have you gotten from users running it?
|
||||
- Are there specific steps that feel clunky or confusing?
|
||||
- Is the workflow achieving its intended outcome?
|
||||
- Are there new capabilities you want to add?
|
||||
- Is the instruction style working well for your users?
|
||||
|
||||
Listen for clues about:
|
||||
|
||||
- User experience issues (confusing steps, unclear instructions)
|
||||
- Functional issues (broken references, missing validation)
|
||||
- Performance issues (too many steps, repetitive, tedious)
|
||||
- Maintainability issues (hard to update, bloated, inconsistent variables)
|
||||
- Instruction style mismatch (too prescriptive when should be adaptive, or vice versa)
|
||||
- Integration issues (doesn't work well with other workflows)
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action if="choice is 5 (cancel)"><goto step="3">Return to editing menu</goto></action>
|
||||
<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
|
||||
|
||||
<action>Show the current content that will be edited</action>
|
||||
<action>Explain the proposed changes and why they improve the workflow</action>
|
||||
<action>Generate the updated content following all conventions from the guide</action>
|
||||
Organize by priority and user goals:
|
||||
|
||||
<ask>Review the proposed changes. Options:
|
||||
- CRITICAL issues blocking successful runs
|
||||
- IMPORTANT improvements enhancing user experience
|
||||
- NICE-TO-HAVE enhancements for polish
|
||||
|
||||
- [a] Accept and apply
|
||||
- [e] Edit/modify the changes
|
||||
- [s] Skip this change
|
||||
- [n] Move to next file/section
|
||||
- [d] Done with edits
|
||||
Present these conversationally, explaining WHY each matters and HOW it would help.
|
||||
</action>
|
||||
|
||||
<action>Assess instruction style fit:
|
||||
|
||||
Based on the workflow's purpose and your analysis:
|
||||
|
||||
- Is the current style (intent-based vs prescriptive) appropriate?
|
||||
- Would users benefit from more/less structure?
|
||||
- Are there steps that should be more adaptive?
|
||||
- Are there steps that need more specificity?
|
||||
|
||||
Discuss style as part of improvement discovery, not as a separate concern.
|
||||
</action>
|
||||
|
||||
<action>Collaborate on priorities:
|
||||
|
||||
Don't just list options - discuss them:
|
||||
|
||||
- "I noticed {{issue}} - this could make users feel {{problem}}. Want to address this?"
|
||||
- "The workflow could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
|
||||
- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
|
||||
|
||||
Let the conversation flow naturally. Build a shared vision of what "better" looks like.
|
||||
</action>
|
||||
|
||||
<template-output>improvement_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
|
||||
<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
|
||||
|
||||
<action>For each improvement area, facilitate collaboratively:
|
||||
|
||||
1. **Explain the current state and why it matters**
|
||||
- Show relevant sections of the workflow
|
||||
- Explain how it works now and implications
|
||||
- Connect to user's goals from step 2
|
||||
|
||||
2. **Propose improvements with rationale**
|
||||
- Suggest specific changes that align with best practices
|
||||
- Explain WHY each change helps
|
||||
- Provide examples from the loaded guides when helpful
|
||||
- Show before/after comparisons for clarity
|
||||
- Reference the creation guide's patterns naturally
|
||||
|
||||
3. **Collaborate on the approach**
|
||||
- Ask if the proposed change addresses their need
|
||||
- Invite modifications or alternative approaches
|
||||
- Explain tradeoffs when relevant
|
||||
- Adapt based on their feedback
|
||||
|
||||
4. **Apply changes iteratively**
|
||||
- Make one focused improvement at a time
|
||||
- Show the updated section
|
||||
- Confirm it meets their expectation
|
||||
- Move to next improvement or refine current one
|
||||
</action>
|
||||
|
||||
<action>Common improvement patterns to facilitate:
|
||||
|
||||
**If refining instruction style:**
|
||||
|
||||
- Discuss where the workflow feels too rigid or too loose
|
||||
- Identify steps that would benefit from intent-based approach
|
||||
- Identify steps that need prescriptive structure
|
||||
- Convert between styles thoughtfully, explaining tradeoffs
|
||||
- Show how each style serves the user differently
|
||||
- Test proposed changes by reading them aloud
|
||||
|
||||
**If improving step flow:**
|
||||
|
||||
- Walk through the user journey step by step
|
||||
- Identify friction points or redundancy
|
||||
- Propose streamlined flow
|
||||
- Consider where steps could merge or split
|
||||
- Ensure each step has clear goal and value
|
||||
- Check that repeat conditions make sense
|
||||
|
||||
**If fixing variable consistency:**
|
||||
|
||||
- Identify variables used across files
|
||||
- Find mismatches in naming or usage
|
||||
- Propose consistent naming scheme
|
||||
- Update all files to match
|
||||
- Verify variables are defined in workflow.yaml
|
||||
|
||||
**If enhancing validation:**
|
||||
|
||||
- Review current checklist (if exists)
|
||||
- Discuss what "done well" looks like
|
||||
- Make criteria specific and measurable
|
||||
- Add validation for new features
|
||||
- Remove outdated or vague criteria
|
||||
|
||||
**If updating configuration:**
|
||||
|
||||
- Review standard config pattern
|
||||
- Check if user context variables are needed
|
||||
- Ensure output_folder, user_name, communication_language are used appropriately
|
||||
- Add missing config dependencies
|
||||
- Clean up unused config fields
|
||||
|
||||
**If adding/updating templates:**
|
||||
|
||||
- Understand the document structure needed
|
||||
- Design template variables that match instruction outputs
|
||||
- Ensure variable names are descriptive snake_case
|
||||
- Include proper metadata headers
|
||||
- Test that all variables can be filled
|
||||
|
||||
**If configuring web bundle:**
|
||||
|
||||
- Identify all files the workflow depends on
|
||||
- Check for invoked workflows (must be included)
|
||||
- Verify paths are bmad/-relative
|
||||
- Remove config_source dependencies
|
||||
- Build complete file list
|
||||
|
||||
**If improving user interaction:**
|
||||
|
||||
- Find places where <ask> could be more open-ended
|
||||
- Add educational context where users might be lost
|
||||
- Remove unnecessary confirmation steps
|
||||
- Make questions clearer and more purposeful
|
||||
- Balance guidance with user autonomy
|
||||
</action>
|
||||
|
||||
<action>Throughout improvements, educate when helpful:
|
||||
|
||||
Share insights from the guides naturally:
|
||||
|
||||
- "The creation guide recommends {{pattern}} for workflows like this"
|
||||
- "Looking at examples in BMM, this type of step usually {{approach}}"
|
||||
- "The execution engine expects {{structure}} for this to work properly"
|
||||
|
||||
Connect improvements to broader BMAD principles without being preachy.
|
||||
</action>
|
||||
|
||||
<ask>After each significant change:
|
||||
|
||||
- "Does this flow feel better for what you're trying to achieve?"
|
||||
- "Want to refine this further, or move to the next improvement?"
|
||||
- "How does this change affect the user experience?"
|
||||
</ask>
|
||||
|
||||
<check if="user selects 'a'">
|
||||
<action>Apply the changes to the file</action>
|
||||
<action>Log the change for the summary</action>
|
||||
</check>
|
||||
|
||||
<check if="user selects 'e'">
|
||||
<ask>What modifications would you like to make?</ask>
|
||||
<goto step="5">Regenerate with modifications</goto>
|
||||
</check>
|
||||
|
||||
<action if="user selects 'd'"><continue>Proceed to validation</continue></action>
|
||||
<template-output>improvement_implementation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Validate all changes" optional="true">
|
||||
<action>Run a comprehensive validation check:</action>
|
||||
<step n="4" goal="Validate improvements holistically">
|
||||
<action>Run comprehensive validation conversationally:
|
||||
|
||||
**Basic Validation:**
|
||||
Don't just check boxes - explain what you're validating and why it matters:
|
||||
|
||||
- [ ] All file paths resolve correctly
|
||||
- [ ] Variable names are consistent across files
|
||||
- [ ] Step numbering is sequential and logical
|
||||
- [ ] Required XML tags are properly formatted
|
||||
- [ ] No placeholders remain (like {TITLE} or {WORKFLOW_CODE})
|
||||
- [ ] Instructions match the workflow type
|
||||
- [ ] Template variables match instruction outputs (if applicable)
|
||||
- [ ] Checklist criteria are measurable (if present)
|
||||
- [ ] Critical headers are present in instructions
|
||||
- [ ] YAML syntax is valid
|
||||
- "Let me verify all file references resolve correctly..."
|
||||
- "Checking that variables are consistent across all files..."
|
||||
- "Making sure the step flow is logical and complete..."
|
||||
- "Validating template variables match instruction outputs..."
|
||||
- "Ensuring config dependencies are properly set up..."
|
||||
</action>
|
||||
|
||||
**Standard Config Validation:**
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
<action>Check all items from checklist systematically</action>
|
||||
|
||||
- [ ] workflow.yaml contains config_source
|
||||
- [ ] output_folder, user_name, communication_language pulled from config
|
||||
- [ ] date set to system-generated
|
||||
- [ ] Instructions communicate in {communication_language} where appropriate
|
||||
- [ ] Instructions address {user_name} where appropriate
|
||||
- [ ] Instructions write to {output_folder} for file outputs
|
||||
- [ ] Template optionally includes {{user_name}}, {{date}} in metadata (if document workflow)
|
||||
- [ ] Template does NOT use {{communication_language}} in headers (agent-only variable)
|
||||
<check if="validation_issues_found">
|
||||
<action>Present issues conversationally:
|
||||
|
||||
**YAML/File Alignment:**
|
||||
Explain what's wrong and implications:
|
||||
|
||||
- [ ] All workflow.yaml variables used in instructions OR template
|
||||
- [ ] No unused yaml fields (bloat-free)
|
||||
- [ ] No duplicate fields between top-level and web_bundle
|
||||
- [ ] Template variables match <template-output> tags in instructions
|
||||
- "I found {{issue}} which could cause {{problem}} when users run this"
|
||||
- "The {{component}} needs {{fix}} because {{reason}}"
|
||||
|
||||
**Web bundle validation (if applicable):**
|
||||
Propose fixes immediately:
|
||||
|
||||
- [ ] web_bundle section present if needed
|
||||
- [ ] All paths are bmad/-relative (no {project-root})
|
||||
- [ ] No {config_source} variables in web bundle
|
||||
- [ ] All referenced files listed in web_bundle_files
|
||||
- [ ] Instructions, validation, template paths correct
|
||||
- [ ] Called workflows (<invoke-workflow>) included in web_bundle_files
|
||||
- [ ] Complete file inventory verified
|
||||
- "I can fix this by {{solution}}. Should I?"
|
||||
- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
|
||||
</action>
|
||||
|
||||
<check if="any validation fails">
|
||||
<ask>Issues found. Would you like to fix them? (y/n)</ask>
|
||||
<check if="yes">
|
||||
<goto step="5">Return to editing</goto>
|
||||
</check>
|
||||
<action>Fix approved issues and re-validate</action>
|
||||
</check>
|
||||
|
||||
<check if="validation_passes">
|
||||
<action>Confirm success warmly:
|
||||
|
||||
"Excellent! Everything validates cleanly:
|
||||
|
||||
- All file references resolve
|
||||
- Variables are consistent throughout
|
||||
- Step flow is logical and complete
|
||||
- Template aligns with instructions (if applicable)
|
||||
- Config dependencies are set up correctly
|
||||
- Web bundle is complete (if applicable)
|
||||
|
||||
Your workflow is in great shape."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Generate change summary">
|
||||
<action>Create a summary of all changes made for {user_name} in {communication_language}:</action>
|
||||
<step n="5" goal="Review improvements and guide next steps">
|
||||
<action>Create a conversational summary of what improved:
|
||||
|
||||
**Summary Structure:**
|
||||
Tell the story of the transformation:
|
||||
|
||||
- Workflow name
|
||||
- Changes made (file-by-file descriptions)
|
||||
- Improvements (how workflow is now better aligned with best practices)
|
||||
- Files modified (complete list with paths)
|
||||
- Next steps (suggestions for additional improvements or testing)
|
||||
- "We started with {{initial_state}}"
|
||||
- "You wanted to {{user_goals}}"
|
||||
- "We made these key improvements: {{changes_list}}"
|
||||
- "Now your workflow {{improved_capabilities}}"
|
||||
|
||||
Highlight the impact:
|
||||
|
||||
- "This means users will experience {{benefit}}"
|
||||
- "The workflow is now more {{quality}}"
|
||||
- "It follows best practices for {{patterns}}"
|
||||
</action>
|
||||
|
||||
<action>Guide next steps based on changes made:
|
||||
|
||||
If instruction style changed:
|
||||
|
||||
- "Since we made the workflow more {{style}}, you might want to test it with a real user to see how it feels"
|
||||
|
||||
If template was updated:
|
||||
|
||||
- "The template now has {{new_variables}} - run the workflow to generate a sample document"
|
||||
|
||||
If this is part of larger module work:
|
||||
|
||||
- "This workflow is part of {{module}} - consider if other workflows need similar improvements"
|
||||
|
||||
If web bundle was configured:
|
||||
|
||||
- "The web bundle is now set up - you can test deploying this workflow standalone"
|
||||
|
||||
Be a helpful guide to what comes next, not just a task completer.
|
||||
</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- Test the edited workflow
|
||||
- Make additional edits
|
||||
- Exit
|
||||
- Test the edited workflow by running it
|
||||
- Edit another workflow
|
||||
- Make additional refinements to this one
|
||||
- Return to your module work
|
||||
</ask>
|
||||
|
||||
<action if="test workflow">Invoke the edited workflow for testing</action>
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
||||
@ -1,58 +1,21 @@
|
||||
# v6 Pending Items
|
||||
|
||||
## Needed before Alpha → Beta
|
||||
## Needed Beta → v0 release
|
||||
|
||||
Aside from stability and bug fixes found during the alpha period - the main focus will be on the following:
|
||||
|
||||
- NPX installer
|
||||
- github pipelines, branch protection, vulnerability scanners
|
||||
- subagent injections reenabled
|
||||
- docs docs docs
|
||||
|
||||
--- done ---
|
||||
|
||||
- Done - UX Expert replaced with UX Designer and has a massively improved create-design workflow.
|
||||
- Done - Architecture Reworked, searches web, more user interactive
|
||||
- Done - Sprint Status Workflow to generate the story status tracker
|
||||
- Done - Brownfield v6 integrated into the workflow.
|
||||
- Done - Full workflow single file tracking.
|
||||
- Done - BoMB Tooling included with module install
|
||||
- Done - All project levels (0 through 4) manual flows validated through workflow phase 1-4 for greenfield and brownfield
|
||||
- Done - bmm existing project scanning and integration with workflow phase 0-4 improvements
|
||||
- DONE: Single Agent web bundler finalized - run `npm run bundle'
|
||||
- DONE: 4->v6 upgrade installer fixed.
|
||||
- DONE: v6->v6 updates will no longer remove custom content. so if you have a new agent you created for example anywhere under the bmad folder, updates will no longer remove them.
|
||||
- DONE: if you modify an installed file and upgrade, the file will be saved as a .bak file and the installer will inform you.
|
||||
- DONE: Game Agents comms style WAY to over the top - reduced a bit.
|
||||
- DONE: need to nest subagents for better organization.
|
||||
- DONE: Quick note on BMM v6 Flow
|
||||
- DONE: CC SubAgents installed to sub-folders now.
|
||||
- DONE: Qwen TOML update.
|
||||
- DONE: Diagram alpha BMM flow. - added to src/modules/bmm/workflows/
|
||||
- DONE: Fix Redoc task to BMB.
|
||||
- DONE: Team Web Bundler functional
|
||||
- DONE: Agent improvement to loading instruction insertion and customization system overhaul
|
||||
- DONE: Stand along agents now will install to bmad/agents and are able to be compiled by the installer also
|
||||
|
||||
## Needed before Beta → v0 release
|
||||
|
||||
Once the alpha is stabilized and we switch to beta, work on v4.x will freeze and the beta will merge to main. The NPX installer will still install v4 by default, but people will be able to npm install the beta version also.
|
||||
|
||||
- Orchestration tracking works consistently across all workflow phases on BMM module
|
||||
- Single Reference Architecture
|
||||
- knowledge base for BMM
|
||||
- Module repository and submission process defined
|
||||
- Final polished documentation and user guide for each module
|
||||
- Final polished documentation for overall project architecture
|
||||
- MCP Injections based on installation selection
|
||||
- sub agent optimization
|
||||
- sub agent for opencode and claude code optimization
|
||||
- TDD Workflow Integration
|
||||
- BMad-Master BMad-Init workflow will be a single entrypoint agent command that will set the user on the correct path and workflow. BMad-Init will become very powerful in the future, empowering the BMad Master to be a full orchestrator across any current or future module.
|
||||
|
||||
## Late Beta or Post v0 official release items
|
||||
# Post v0 Roadmap
|
||||
|
||||
- Installer offers installation of vetted community modules
|
||||
- DevOps Module
|
||||
- Security Module
|
||||
- Further BoMB improvements
|
||||
- 2-3 functional Reference Architecture Project Scaffolds and community contribution process defined
|
||||
- Centralized BMad Installer (instead of per project)
|
||||
-
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user