feat: enhance QA agent as senior developer with code review capabilities and major brownfield improvements
This release introduces significant enhancements across multiple areas: QA Agent Transformation: - Transform QA agent into senior developer role with active code refactoring abilities - Add review-story task enabling QA to review, refactor, and improve code directly - Integrate QA review step into standard development workflow (SM → Dev → QA) - QA can fix small issues directly and leave checklist for remaining items - Updated dev agent to maintain File List for QA review focus Knowledge Base Improvements: - Add extensive brownfield development documentation and best practices - Clarify Web UI vs IDE usage with cost optimization strategies - Document PRD-first approach for large codebases/monorepos - Add comprehensive expansion packs explanation - Update IDE workflow to include QA review step - Clarify agent usage (bmad-master vs specialized agents) Brownfield Enhancements: - Create comprehensive Working in the Brownfield guide - Add document-project task to analyst agent capabilities - Implement PRD-first workflow option for focused documentation - Transform document-project to create practical brownfield architecture docs - Document technical debt, workarounds, and real-world constraints - Reference actual files instead of duplicating content - Add impact analysis when PRD is provided Documentation Task Improvements: - Simplify to always create ONE unified architecture document - Add deep codebase analysis phase with targeted questions - Focus on documenting reality including technical debt - Include Quick Reference section with key file paths - Add practical sections: useful commands, debugging tips, known issues Workflow Updates: - Update all 6 workflow files with detailed IDE transition instructions - Add clear SM → Dev → QA → Dev cycle explanation - Emphasize Gemini Web for brownfield analysis (1M+ context advantage) - Support both PRD-first and document-first approaches This release significantly improves the brownfield development experience and introduces a powerful shift-left QA approach with senior developer mentoring.
This commit is contained in:
Brian Madison
@@ -77,39 +77,6 @@ See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples an
|
||||
5. NEVER display template markup or LLM instructions to users
|
||||
6. Focus on clean output - all processing instructions stay internal
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Dev Agent
|
||||
|
||||
```yaml
|
||||
name: API Developer
|
||||
role: Creates REST APIs
|
||||
dependencies:
|
||||
templates:
|
||||
- api-endpoint-tmpl
|
||||
tasks:
|
||||
- implement-endpoint
|
||||
```
|
||||
|
||||
### Good Planning Agent (Web)
|
||||
|
||||
```yaml
|
||||
name: PRD Writer
|
||||
role: Creates comprehensive PRDs
|
||||
dependencies:
|
||||
templates:
|
||||
- prd-tmpl
|
||||
- epic-tmpl
|
||||
- story-tmpl
|
||||
tasks:
|
||||
- elicit-requirements
|
||||
- analyze-market
|
||||
- define-features
|
||||
data:
|
||||
- prd-best-practices
|
||||
- market-analysis-guide
|
||||
```
|
||||
|
||||
## Remember
|
||||
|
||||
- The power is in natural language orchestration, not code
|
||||
|
||||
@@ -188,14 +188,14 @@ The reason #2 and 3 are optional is because now BMad V4 makes sharding optional
|
||||
|
||||
This configuration file tells BMAD agents exactly where to find your project documents and how they're structured. It's the key to V4's flexibility and backwards compatibility.
|
||||
|
||||
#### Key Features:
|
||||
#### Key Features
|
||||
|
||||
- **Version Awareness**: Agents understand if your PRD/Architecture follows V4 conventions or earlier versions
|
||||
- **Flexible Document Locations**: Works whether your epics are embedded in PRD or properly sharded
|
||||
- **Developer Context**: Define which files the dev agent should always load
|
||||
- **Debug Support**: Built-in logging for troubleshooting story implementation
|
||||
|
||||
#### Why It Matters:
|
||||
#### Why It Matters
|
||||
|
||||
- **Use BMAD with ANY project structure** - V3, V4, or custom layouts
|
||||
- **No forced migrations** - Keep your existing document organization
|
||||
@@ -363,6 +363,7 @@ npm install
|
||||
### Workflow Guides
|
||||
|
||||
- 📚 [Universal BMAD Workflow Guide](docs/bmad-workflow-guide.md) - Core workflow that applies to all IDEs
|
||||
- 🏗️ [Working in the Brownfield Guide](docs/working-in-the-brownfield.md) - Complete guide for enhancing existing projects
|
||||
- 🎯 [Cursor Guide](docs/cursor-guide.md) - Complete workflow for Cursor users
|
||||
- 🤖 [Claude Code Guide](docs/claude-code-guide.md) - Complete workflow for Claude Code users
|
||||
- 🌊 [Windsurf Guide](docs/windsurf-guide.md) - Complete workflow for Windsurf users
|
||||
|
||||
@@ -16,7 +16,7 @@ agent:
|
||||
id: analyst
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
|
||||
customization: null
|
||||
persona:
|
||||
role: Insightful Analyst & Strategic Ideation Partner
|
||||
@@ -44,6 +44,7 @@ commands: # All commands require * prefix when used (e.g., *help)
|
||||
- brainstorm {topic}: Facilitate structured brainstorming session
|
||||
- research {topic}: Generate deep research prompt for investigation
|
||||
- elicit: Run advanced elicitation to clarify requirements
|
||||
- document-project: Analyze and document existing project structure comprehensively
|
||||
- exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
@@ -51,6 +52,7 @@ dependencies:
|
||||
- create-deep-research-prompt
|
||||
- create-doc
|
||||
- advanced-elicitation
|
||||
- document-project
|
||||
templates:
|
||||
- project-brief-tmpl
|
||||
- market-research-tmpl
|
||||
|
||||
@@ -52,9 +52,10 @@ task-execution:
|
||||
- "Debug Log: | Task | File | Change | Reverted? |"
|
||||
- "Completion Notes: Deviations only, <50 words"
|
||||
- "Change Log: Requirement changes only"
|
||||
- "File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation"
|
||||
blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations"
|
||||
done: "Code matches reqs + All validations pass + Follows standards"
|
||||
completion: "All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Summary→HALT"
|
||||
done: "Code matches reqs + All validations pass + Follows standards + File List complete"
|
||||
completion: "All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Update File List→Mark Ready for Review→HALT"
|
||||
|
||||
dependencies:
|
||||
tasks:
|
||||
|
||||
@@ -14,34 +14,35 @@ activation-instructions:
|
||||
agent:
|
||||
name: Quinn
|
||||
id: qa
|
||||
title: Quality Assurance Test Architect
|
||||
title: Senior Developer & QA Architect
|
||||
icon: 🧪
|
||||
whenToUse: Use for test planning, test case creation, quality assurance, bug reporting, and testing strategy
|
||||
whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
|
||||
customization: null
|
||||
persona:
|
||||
role: Test Architect & Automation Expert
|
||||
style: Methodical, detail-oriented, quality-focused, strategic
|
||||
identity: Senior quality advocate with expertise in test architecture and automation
|
||||
focus: Comprehensive testing strategies, automation frameworks, quality assurance at every phase
|
||||
role: Senior Developer & Test Architect
|
||||
style: Methodical, detail-oriented, quality-focused, mentoring, strategic
|
||||
identity: Senior developer with deep expertise in code quality, architecture, and test automation
|
||||
focus: Code excellence through review, refactoring, and comprehensive testing strategies
|
||||
core_principles:
|
||||
- Senior Developer Mindset - Review and improve code as a senior mentoring juniors
|
||||
- Active Refactoring - Don't just identify issues, fix them with clear explanations
|
||||
- Test Strategy & Architecture - Design holistic testing strategies across all levels
|
||||
- Automation Excellence - Build maintainable and efficient test automation frameworks
|
||||
- Code Quality Excellence - Enforce best practices, patterns, and clean code principles
|
||||
- Shift-Left Testing - Integrate testing early in development lifecycle
|
||||
- Performance & Security - Proactively identify and fix performance/security issues
|
||||
- Mentorship Through Action - Explain WHY and HOW when making improvements
|
||||
- Risk-Based Testing - Prioritize testing based on risk and critical areas
|
||||
- Performance & Load Testing - Ensure systems meet performance requirements
|
||||
- Security Testing Integration - Incorporate security testing into QA process
|
||||
- Test Data Management - Design strategies for realistic and compliant test data
|
||||
- Continuous Testing & CI/CD - Integrate tests seamlessly into pipelines
|
||||
- Quality Metrics & Reporting - Track meaningful metrics and provide insights
|
||||
- Cross-Browser & Cross-Platform Testing - Ensure comprehensive compatibility
|
||||
- Continuous Improvement - Balance perfection with pragmatism
|
||||
- Architecture & Design Patterns - Ensure proper patterns and maintainable code structure
|
||||
startup:
|
||||
- Greet the user with your name and role, and inform of the *help command.
|
||||
commands: # All commands require * prefix when used (e.g., *help)
|
||||
- help: Show numbered list of the following commands to allow selection
|
||||
- chat-mode: (Default) QA consultation with advanced-elicitation for test strategy
|
||||
- create-doc {template}: Create doc (no template = show available templates)
|
||||
- exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
- review-story
|
||||
data:
|
||||
- technical-preferences
|
||||
utils:
|
||||
|
||||
@@ -20,6 +20,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -34,7 +78,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -43,13 +87,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -66,6 +119,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -306,10 +400,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -343,10 +443,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -360,19 +464,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -392,12 +511,72 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -478,9 +657,91 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
|
||||
@@ -8,7 +8,39 @@ Generate comprehensive documentation for existing projects optimized for AI deve
|
||||
|
||||
### 1. Initial Project Analysis
|
||||
|
||||
[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
|
||||
[[LLM: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
@@ -23,367 +55,263 @@ Ask the user these elicitation questions to better understand their needs:
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- Are there any existing documentation standards or formats you prefer?
|
||||
- What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
|
||||
- Is there a specific feature or enhancement you're planning? (This helps focus documentation)
|
||||
]]
|
||||
|
||||
### 2. Core Documentation Generation
|
||||
### 2. Deep Codebase Analysis
|
||||
|
||||
[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
|
||||
[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
|
||||
|
||||
**Core Documents (always generate):**
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
1. **docs/index.md** - Master documentation index
|
||||
2. **docs/architecture/index.md** - Architecture documentation index
|
||||
3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
|
||||
4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
|
||||
5. **docs/architecture/unified-project-structure.md** - Project structure and organization
|
||||
6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
**Backend Documents (generate for backend/full-stack projects):**
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- Document workarounds and technical debt
|
||||
- Note areas that differ from standard patterns
|
||||
|
||||
7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
|
||||
8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
|
||||
9. **docs/architecture/data-models.md** - Data structures and validation rules
|
||||
10. **docs/architecture/database-schema.md** - Database design and relationships
|
||||
11. **docs/architecture/external-apis.md** - Third-party integrations
|
||||
**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
|
||||
|
||||
**Frontend Documents (generate for frontend/full-stack projects):**
|
||||
### 3. Core Documentation Generation
|
||||
|
||||
12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
|
||||
13. **docs/architecture/components.md** - UI component specifications
|
||||
14. **docs/architecture/core-workflows.md** - User interaction flows
|
||||
15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
|
||||
[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
|
||||
|
||||
**Additional Documents (generate if applicable):**
|
||||
**CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
|
||||
- Technical debt and workarounds
|
||||
- Inconsistent patterns between different parts
|
||||
- Legacy code that can't be changed
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
16. **docs/prd.md** - Product requirements document (if not exists)
|
||||
17. **docs/architecture/deployment-guide.md** - Deployment and operations info
|
||||
18. **docs/architecture/security-considerations.md** - Security patterns and requirements
|
||||
19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
|
||||
**Document Structure**:
|
||||
|
||||
**Optional Enhancement Documents:**
|
||||
# [Project Name] Brownfield Architecture Document
|
||||
|
||||
20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
|
||||
21. **docs/architecture/changelog-conventions.md** - Change management practices
|
||||
22. **docs/architecture/code-review-checklist.md** - Review standards and practices
|
||||
## Introduction
|
||||
This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
|
||||
|
||||
Present each document section by section, using the advanced elicitation task after each major section.]]
|
||||
### Document Scope
|
||||
[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
|
||||
[If no PRD: "Comprehensive documentation of entire system"]
|
||||
|
||||
### 3. Document Structure Template
|
||||
### Change Log
|
||||
| Date | Version | Description | Author |
|
||||
|------|---------|-------------|--------|
|
||||
| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
|
||||
|
||||
[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
|
||||
## Quick Reference - Key Files and Entry Points
|
||||
|
||||
```markdown
|
||||
# {{Document Title}}
|
||||
### Critical Files for Understanding the System
|
||||
- **Main Entry**: `src/index.js` (or actual entry point)
|
||||
- **Configuration**: `config/app.config.js`, `.env.example`
|
||||
- **Core Business Logic**: `src/services/`, `src/domain/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **Key Algorithms**: [List specific files with complex logic]
|
||||
|
||||
## Overview
|
||||
### If PRD Provided - Enhancement Impact Areas
|
||||
[Highlight which files/modules will be affected by the planned enhancement]
|
||||
|
||||
{{Brief description of what this document covers and why it's important for AI agents}}
|
||||
## High Level Architecture
|
||||
|
||||
## Quick Reference
|
||||
### Technical Summary
|
||||
[Real assessment of architecture - mention if it's well-structured or has issues]
|
||||
|
||||
{{Key points, commands, or patterns that agents need most frequently}}
|
||||
### Actual Tech Stack (from package.json/requirements.txt)
|
||||
| Category | Technology | Version | Notes |
|
||||
|----------|------------|---------|--------|
|
||||
| Runtime | Node.js | 16.x | [Any constraints] |
|
||||
| Framework | Express | 4.18.2 | [Custom middleware?] |
|
||||
| Database | PostgreSQL | 13 | [Connection pooling setup] |
|
||||
| [etc...] |
|
||||
|
||||
## Detailed Information
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
{{Comprehensive information organized into logical sections}}
|
||||
## Source Tree and Module Organization
|
||||
|
||||
## Examples
|
||||
|
||||
{{Concrete examples showing proper usage or implementation}}
|
||||
|
||||
## Common Patterns
|
||||
|
||||
{{Recurring patterns agents should recognize and follow}}
|
||||
|
||||
## Things to Avoid
|
||||
|
||||
{{Anti-patterns, deprecated approaches, or common mistakes}}
|
||||
|
||||
## Related Resources
|
||||
|
||||
{{Links to other relevant documentation or external resources}}
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
Each document should be:
|
||||
|
||||
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
|
||||
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
|
||||
- **Example-rich** - Include specific code examples and real file references
|
||||
- **Context-aware** - Reference actual project files, folders, and conventions
|
||||
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
|
||||
]]
|
||||
|
||||
### 4. Content Guidelines for Each Document Type
|
||||
|
||||
#### Core Architecture Documents
|
||||
|
||||
##### docs/architecture/index.md
|
||||
|
||||
[[LLM: Create a comprehensive index of all architecture documentation:
|
||||
|
||||
- List all architecture documents with brief descriptions
|
||||
- Group documents by category (backend, frontend, shared)
|
||||
- Include quick links to key sections
|
||||
- Provide reading order recommendations for different use cases]]
|
||||
|
||||
##### docs/architecture/unified-project-structure.md
|
||||
|
||||
[[LLM: Document the complete project structure:
|
||||
|
||||
- Root-level directory structure with explanations
|
||||
- Where each type of code belongs (backend, frontend, tests, etc.)
|
||||
- File naming conventions and patterns
|
||||
- Module/package organization
|
||||
- Generated vs. source file locations
|
||||
- Build output locations]]
|
||||
|
||||
##### docs/architecture/coding-standards.md
|
||||
|
||||
[[LLM: Capture project-wide coding conventions:
|
||||
|
||||
- Language-specific style guidelines
|
||||
- Naming conventions (variables, functions, classes, files)
|
||||
- Code organization within files
|
||||
- Import/export patterns
|
||||
- Comment and documentation standards
|
||||
- Linting and formatting tool configurations
|
||||
- Git commit message conventions]]
|
||||
|
||||
##### docs/architecture/tech-stack.md
|
||||
|
||||
[[LLM: Document all technologies and versions:
|
||||
|
||||
- Primary languages and versions
|
||||
- Frameworks and major libraries with versions
|
||||
- Development tools and their versions
|
||||
- Database systems and versions
|
||||
- External services and APIs used
|
||||
- Browser/runtime requirements]]
|
||||
|
||||
##### docs/architecture/testing-strategy.md
|
||||
|
||||
[[LLM: Define testing approaches and requirements:
|
||||
|
||||
- Test file locations and naming conventions
|
||||
- Unit testing patterns and frameworks
|
||||
- Integration testing approaches
|
||||
- E2E testing setup (if applicable)
|
||||
- Test coverage requirements
|
||||
- Mocking strategies
|
||||
- Test data management]]
|
||||
|
||||
#### Backend Architecture Documents
|
||||
|
||||
##### docs/architecture/backend-architecture.md
|
||||
|
||||
[[LLM: Document backend service structure:
|
||||
|
||||
- Service layer organization
|
||||
- Controller/route patterns
|
||||
- Middleware architecture
|
||||
- Authentication/authorization patterns
|
||||
- Request/response flow
|
||||
- Background job processing
|
||||
- Service communication patterns]]
|
||||
|
||||
##### docs/architecture/rest-api-spec.md
|
||||
|
||||
[[LLM: Specify all API endpoints:
|
||||
|
||||
- Base URL and versioning strategy
|
||||
- Authentication methods
|
||||
- Common headers and parameters
|
||||
- Each endpoint with:
|
||||
- HTTP method and path
|
||||
- Request parameters/body
|
||||
- Response format and status codes
|
||||
- Error responses
|
||||
- Rate limiting and quotas]]
|
||||
|
||||
##### docs/architecture/data-models.md
|
||||
|
||||
[[LLM: Define data structures and validation:
|
||||
|
||||
- Core business entities
|
||||
- Data validation rules
|
||||
- Relationships between entities
|
||||
- Computed fields and derivations
|
||||
- Data transformation patterns
|
||||
- Serialization formats]]
|
||||
|
||||
##### docs/architecture/database-schema.md
|
||||
|
||||
[[LLM: Document database design:
|
||||
|
||||
- Database type and version
|
||||
- Table/collection structures
|
||||
- Indexes and constraints
|
||||
- Relationships and foreign keys
|
||||
- Migration patterns
|
||||
- Seed data requirements
|
||||
- Backup and recovery procedures]]
|
||||
|
||||
##### docs/architecture/external-apis.md
|
||||
|
||||
[[LLM: Document third-party integrations:
|
||||
|
||||
- List of external services used
|
||||
- Authentication methods for each
|
||||
- API endpoints and usage patterns
|
||||
- Rate limits and quotas
|
||||
- Error handling strategies
|
||||
- Webhook configurations
|
||||
- Data synchronization patterns]]
|
||||
|
||||
#### Frontend Architecture Documents
|
||||
|
||||
##### docs/architecture/frontend-architecture.md
|
||||
|
||||
[[LLM: Document frontend application structure:
|
||||
|
||||
- Component hierarchy and organization
|
||||
- State management patterns
|
||||
- Routing architecture
|
||||
- Data fetching patterns
|
||||
- Authentication flow
|
||||
- Error boundary strategies
|
||||
- Performance optimization patterns]]
|
||||
|
||||
##### docs/architecture/components.md
|
||||
|
||||
[[LLM: Specify UI components:
|
||||
|
||||
- Component library/design system used
|
||||
- Custom component specifications
|
||||
- Props and state for each component
|
||||
- Component composition patterns
|
||||
- Styling approaches
|
||||
- Accessibility requirements
|
||||
- Component testing patterns]]
|
||||
|
||||
##### docs/architecture/core-workflows.md
|
||||
|
||||
[[LLM: Document user interaction flows:
|
||||
|
||||
- Major user journeys
|
||||
- Screen flow diagrams
|
||||
- Form handling patterns
|
||||
- Navigation patterns
|
||||
- Data flow through workflows
|
||||
- Error states and recovery
|
||||
- Loading and transition states]]
|
||||
|
||||
##### docs/architecture/ui-ux-spec.md
|
||||
|
||||
[[LLM: Define UI/UX guidelines:
|
||||
|
||||
- Design system specifications
|
||||
- Color palette and typography
|
||||
- Spacing and layout grids
|
||||
- Responsive breakpoints
|
||||
- Animation and transition guidelines
|
||||
- Accessibility standards
|
||||
- Browser compatibility requirements]]
|
||||
|
||||
### 5. Adaptive Content Strategy
|
||||
|
||||
[[LLM: Adapt your documentation approach based on project characteristics:
|
||||
|
||||
**For Web Applications:**
|
||||
|
||||
- Focus on component patterns, routing, state management
|
||||
- Include build processes, asset handling, and deployment
|
||||
- Cover API integration patterns and data fetching
|
||||
|
||||
**For Backend Services:**
|
||||
|
||||
- Emphasize service architecture, data models, and API design
|
||||
- Include database interaction patterns and migration strategies
|
||||
- Cover authentication, authorization, and security patterns
|
||||
|
||||
**For CLI Tools:**
|
||||
|
||||
- Focus on command structure, argument parsing, and output formatting
|
||||
- Include plugin/extension patterns if applicable
|
||||
- Cover configuration file handling and user interaction patterns
|
||||
|
||||
**For Libraries/Frameworks:**
|
||||
|
||||
- Emphasize public API design and usage patterns
|
||||
- Include extension points and customization approaches
|
||||
- Cover versioning, compatibility, and migration strategies
|
||||
|
||||
**For Mobile Applications:**
|
||||
|
||||
- Focus on platform-specific patterns and navigation
|
||||
- Include state management and data persistence approaches
|
||||
- Cover platform integration and native feature usage
|
||||
|
||||
**For Data Science/ML Projects:**
|
||||
|
||||
- Emphasize data pipeline patterns and model organization
|
||||
- Include experiment tracking and reproducibility approaches
|
||||
- Cover data validation and model deployment patterns
|
||||
]]
|
||||
|
||||
### 6. Quality Assurance
|
||||
|
||||
[[LLM: Before completing each document:
|
||||
|
||||
1. **Accuracy Check**: Verify all file paths, commands, and code examples work
|
||||
2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
|
||||
3. **Clarity Assessment**: Check that explanations are clear and actionable
|
||||
4. **Consistency Verification**: Ensure terminology and patterns align across all documents
|
||||
5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
|
||||
|
||||
Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
|
||||
|
||||
### 7. Final Integration
|
||||
|
||||
[[LLM: After all documents are completed:
|
||||
|
||||
1. Ensure all documents are created in the proper BMAD-expected locations:
|
||||
|
||||
- Core docs in `docs/` (index.md, prd.md)
|
||||
- Architecture shards in `docs/architecture/` subdirectory
|
||||
- Create the `docs/architecture/` directory if it doesn't exist
|
||||
|
||||
2. Create/update the master index documents:
|
||||
|
||||
- Update `docs/index.md` to reference all documentation
|
||||
- Create `docs/architecture/index.md` listing all architecture shards
|
||||
|
||||
3. Verify document cross-references:
|
||||
|
||||
- Ensure all documents link to related documentation
|
||||
- Check that file paths match the actual project structure
|
||||
- Validate that examples reference real files in the project
|
||||
|
||||
4. Provide maintenance guidance:
|
||||
|
||||
- Document update triggers (when to update each doc)
|
||||
- Create a simple checklist for keeping docs current
|
||||
- Suggest automated validation approaches
|
||||
|
||||
5. Summary report including:
|
||||
- List of all documents created with their paths
|
||||
- Any gaps or areas needing human review
|
||||
- Recommendations for project-specific additions
|
||||
- Next steps for maintaining documentation accuracy
|
||||
|
||||
Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
|
||||
### Key Modules and Their Purpose
|
||||
- **User Management**: `src/services/userService.js` - Handles all user operations
|
||||
- **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
|
||||
- **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## Data Models and APIs
|
||||
|
||||
### Data Models
|
||||
Instead of duplicating, reference actual model files:
|
||||
- **User Model**: See `src/models/User.js`
|
||||
- **Order Model**: See `src/models/Order.js`
|
||||
- **Related Types**: TypeScript definitions in `src/types/`
|
||||
|
||||
### API Specifications
|
||||
- **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
|
||||
- **Postman Collection**: `docs/api/postman-collection.json`
|
||||
- **Manual Endpoints**: [List any undocumented endpoints discovered]
|
||||
|
||||
## Technical Debt and Known Issues
|
||||
|
||||
### Critical Technical Debt
|
||||
1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
|
||||
2. **User Service**: Different pattern than other services, uses callbacks instead of promises
|
||||
3. **Database Migrations**: Manually tracked, no proper migration tool
|
||||
4. **[Other significant debt]**
|
||||
|
||||
### Workarounds and Gotchas
|
||||
- **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
|
||||
- **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
|
||||
- **[Other workarounds developers need to know]**
|
||||
|
||||
## Integration Points and External Dependencies
|
||||
|
||||
### External Services
|
||||
| Service | Purpose | Integration Type | Key Files |
|
||||
|---------|---------|------------------|-----------|
|
||||
| Stripe | Payments | REST API | `src/integrations/stripe/` |
|
||||
| SendGrid | Emails | SDK | `src/services/emailService.js` |
|
||||
| [etc...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## Development and Deployment
|
||||
|
||||
### Local Development Setup
|
||||
1. Actual steps that work (not ideal steps)
|
||||
2. Known issues with setup
|
||||
3. Required environment variables (see `.env.example`)
|
||||
|
||||
### Build and Deployment Process
|
||||
- **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
|
||||
- **Deployment**: Manual deployment via `scripts/deploy.sh`
|
||||
- **Environments**: Dev, Staging, Prod (see `config/environments/`)
|
||||
|
||||
## Testing Reality
|
||||
|
||||
### Current Test Coverage
|
||||
- Unit Tests: 60% coverage (Jest)
|
||||
- Integration Tests: Minimal, in `tests/integration/`
|
||||
- E2E Tests: None
|
||||
- Manual Testing: Primary QA method
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
npm test # Runs unit tests
|
||||
npm run test:integration # Runs integration tests (requires local DB)
|
||||
```
|
||||
|
||||
## If Enhancement PRD Provided - Impact Analysis
|
||||
|
||||
### Files That Will Need Modification
|
||||
Based on the enhancement requirements, these files will be affected:
|
||||
- `src/services/userService.js` - Add new user fields
|
||||
- `src/models/User.js` - Update schema
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [etc...]
|
||||
|
||||
### New Files/Modules Needed
|
||||
- `src/services/newFeatureService.js` - New business logic
|
||||
- `src/models/NewFeature.js` - New data model
|
||||
- [etc...]
|
||||
|
||||
### Integration Considerations
|
||||
- Will need to integrate with existing auth middleware
|
||||
- Must follow existing response format in `src/utils/responseFormatter.js`
|
||||
- [Other integration points]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
npm run seed # Seed test data
|
||||
```
|
||||
|
||||
### Debugging and Troubleshooting
|
||||
- **Logs**: Check `logs/app.log` for application logs
|
||||
- **Debug Mode**: Set `DEBUG=app:*` for verbose logging
|
||||
- **Common Issues**: See `docs/troubleshooting.md`]]
|
||||
|
||||
### 4. Document Delivery
|
||||
|
||||
[[LLM: After generating the complete architecture document:
|
||||
|
||||
1. **In Web UI (Gemini, ChatGPT, Claude)**:
|
||||
- Present the entire document in one response (or multiple if too long)
|
||||
- Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- Can be sharded later using PO agent if desired
|
||||
|
||||
The document should be comprehensive enough that future agents can understand:
|
||||
- The actual state of the system (not idealized)
|
||||
- Where to find key files and logic
|
||||
- What technical debt exists
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: Before finalizing the document:
|
||||
|
||||
1. **Accuracy Check**: Verify all technical details match the actual codebase
|
||||
2. **Completeness Review**: Ensure all major system components are documented
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
4. **Clarity Assessment**: Check that explanations are clear for AI agents
|
||||
5. **Navigation**: Ensure document has clear section structure for easy reference
|
||||
|
||||
Apply the advanced elicitation task after major sections to refine based on user feedback.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Documentation enables AI agents to understand project context without additional explanation
|
||||
- All major architectural patterns and coding conventions are captured
|
||||
- Examples reference actual project files and demonstrate real usage
|
||||
- Documentation is structured consistently and easy to navigate
|
||||
- Content is actionable and focuses on what agents need to do, not just understand
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task is designed to work with any project type, language, or framework
|
||||
- The documentation should reflect the project as it actually is, not as it should be
|
||||
- Focus on patterns that agents can recognize and replicate consistently
|
||||
- Include both positive examples (what to do) and negative examples (what to avoid)
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
135
bmad-core/tasks/review-story.md
Normal file
135
bmad-core/tasks/review-story.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# review-story
|
||||
|
||||
When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
|
||||
|
||||
[[LLM: QA Agent executing review-story task as Senior Developer]]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Story status must be "Review"
|
||||
- Developer has completed all tasks and updated the File List
|
||||
- All automated tests are passing
|
||||
|
||||
## Review Process
|
||||
|
||||
1. **Read the Complete Story**
|
||||
- Review all acceptance criteria
|
||||
- Understand the dev notes and requirements
|
||||
- Note any completion notes from the developer
|
||||
|
||||
2. **Focus on the File List**
|
||||
- Verify all files listed were actually created/modified
|
||||
- Check for any missing files that should have been updated
|
||||
|
||||
3. **Senior Developer Code Review**
|
||||
- Review code with the eye of a senior developer
|
||||
- If changes form a cohesive whole, review them together
|
||||
- If changes are independent, review incrementally file by file
|
||||
- Focus on:
|
||||
- Code architecture and design patterns
|
||||
- Refactoring opportunities
|
||||
- Code duplication or inefficiencies
|
||||
- Performance optimizations
|
||||
- Security concerns
|
||||
- Best practices and patterns
|
||||
|
||||
4. **Active Refactoring**
|
||||
- As a senior developer, you CAN and SHOULD refactor code where improvements are needed
|
||||
- When refactoring:
|
||||
- Make the changes directly in the files
|
||||
- Explain WHY you're making the change
|
||||
- Describe HOW the change improves the code
|
||||
- Ensure all tests still pass after refactoring
|
||||
- Update the File List if you modify additional files
|
||||
|
||||
5. **Standards Compliance Check**
|
||||
- Verify adherence to `docs/coding-standards.md`
|
||||
- Check compliance with `docs/unified-project-structure.md`
|
||||
- Validate testing approach against `docs/testing-strategy.md`
|
||||
- Ensure all guidelines mentioned in the story are followed
|
||||
|
||||
6. **Acceptance Criteria Validation**
|
||||
- Verify each AC is fully implemented
|
||||
- Check for any missing functionality
|
||||
- Validate edge cases are handled
|
||||
|
||||
7. **Test Coverage Review**
|
||||
- Ensure unit tests cover edge cases
|
||||
- Add missing tests if critical coverage is lacking
|
||||
- Verify integration tests (if required) are comprehensive
|
||||
- Check that test assertions are meaningful
|
||||
- Look for missing test scenarios
|
||||
|
||||
8. **Documentation and Comments**
|
||||
- Verify code is self-documenting where possible
|
||||
- Add comments for complex logic if missing
|
||||
- Ensure any API changes are documented
|
||||
|
||||
## Append Results to Story File
|
||||
|
||||
After review and any refactoring, append your results to the story file in the QA Results section:
|
||||
|
||||
```markdown
|
||||
## QA Results
|
||||
|
||||
### Review Date: [Date]
|
||||
### Reviewed By: Quinn (Senior Developer QA)
|
||||
|
||||
### Code Quality Assessment
|
||||
[Overall assessment of implementation quality]
|
||||
|
||||
### Refactoring Performed
|
||||
[List any refactoring you performed with explanations]
|
||||
- **File**: [filename]
|
||||
- **Change**: [what was changed]
|
||||
- **Why**: [reason for change]
|
||||
- **How**: [how it improves the code]
|
||||
|
||||
### Compliance Check
|
||||
- Coding Standards: [✓/✗] [notes if any]
|
||||
- Project Structure: [✓/✗] [notes if any]
|
||||
- Testing Strategy: [✓/✗] [notes if any]
|
||||
- All ACs Met: [✓/✗] [notes if any]
|
||||
|
||||
### Improvements Checklist
|
||||
[Check off items you handled yourself, leave unchecked for dev to address]
|
||||
|
||||
- [x] Refactored user service for better error handling (services/user.service.ts)
|
||||
- [x] Added missing edge case tests (services/user.service.test.ts)
|
||||
- [ ] Consider extracting validation logic to separate validator class
|
||||
- [ ] Add integration test for error scenarios
|
||||
- [ ] Update API documentation for new error codes
|
||||
|
||||
### Security Review
|
||||
[Any security concerns found and whether addressed]
|
||||
|
||||
### Performance Considerations
|
||||
[Any performance issues found and whether addressed]
|
||||
|
||||
### Final Status
|
||||
[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
- You are a SENIOR developer reviewing junior/mid-level work
|
||||
- You have the authority and responsibility to improve code directly
|
||||
- Always explain your changes for learning purposes
|
||||
- Balance between perfection and pragmatism
|
||||
- Focus on significant improvements, not nitpicks
|
||||
|
||||
## Blocking Conditions
|
||||
|
||||
Stop the review and request clarification if:
|
||||
- Story file is incomplete or missing critical sections
|
||||
- File List is empty or clearly incomplete
|
||||
- No tests exist when they were required
|
||||
- Code changes don't align with story requirements
|
||||
- Critical architectural issues that require discussion
|
||||
|
||||
## Completion
|
||||
|
||||
After review:
|
||||
1. If all items are checked and approved: Update story status to "Done"
|
||||
2. If unchecked items remain: Keep status as "Review" for dev to address
|
||||
3. Always provide constructive feedback and explanations for learning
|
||||
@@ -52,6 +52,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -59,3 +63,7 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
|
||||
@@ -42,7 +42,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
@@ -43,7 +43,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
@@ -50,7 +50,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
@@ -75,7 +75,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
@@ -51,7 +51,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
@@ -70,7 +70,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
244
dist/agents/analyst.txt
vendored
244
dist/agents/analyst.txt
vendored
@@ -1633,6 +1633,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -1647,7 +1691,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -1656,13 +1700,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -1679,6 +1732,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -1956,10 +2050,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -1973,19 +2071,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -2005,12 +2118,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -2091,12 +2219,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: utils#template-format ====================
|
||||
|
||||
284
dist/agents/bmad-master.txt
vendored
284
dist/agents/bmad-master.txt
vendored
@@ -2314,9 +2314,27 @@ Would you like to proceed with documentation indexing? Please provide the requir
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -2349,19 +2367,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -2371,7 +2389,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -2390,7 +2408,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
@@ -6720,6 +6738,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -6727,6 +6749,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#architect-checklist ====================
|
||||
@@ -8468,6 +8494,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -8482,7 +8552,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -8491,13 +8561,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -8514,6 +8593,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -8791,10 +8911,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -8808,19 +8932,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -8840,12 +8979,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -8926,12 +9080,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: data#technical-preferences ====================
|
||||
|
||||
244
dist/agents/bmad-orchestrator.txt
vendored
244
dist/agents/bmad-orchestrator.txt
vendored
@@ -431,6 +431,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -445,7 +489,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -454,13 +498,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -477,6 +530,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -754,10 +848,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -771,19 +869,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -803,12 +916,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -889,12 +1017,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: utils#workflow-management ====================
|
||||
|
||||
10
dist/agents/dev.txt
vendored
10
dist/agents/dev.txt
vendored
@@ -67,6 +67,7 @@ core_principles:
|
||||
- CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
|
||||
- Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
|
||||
- Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
|
||||
- Quality Gate Discipline - NEVER complete tasks with failing automated validations
|
||||
- Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix.
|
||||
- Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
|
||||
- Code Excellence - Clean, secure, maintainable code per loaded standards
|
||||
@@ -78,15 +79,16 @@ commands:
|
||||
- complete-story: Finalize to "Review"
|
||||
- exit: Say goodbye as the Developer, and then abandon inhabiting this persona
|
||||
task-execution:
|
||||
flow: Read task→Implement→Write tests→Pass tests→Update [x]→Next task
|
||||
flow: Read task→Implement→Write tests→Execute validations→Only if ALL pass→Update [x]→Next task
|
||||
updates-ONLY:
|
||||
- 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
|
||||
- 'Debug Log: | Task | File | Change | Reverted? |'
|
||||
- 'Completion Notes: Deviations only, <50 words'
|
||||
- 'Change Log: Requirement changes only'
|
||||
blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config
|
||||
done: Code matches reqs + Tests pass + Follows standards + No lint errors
|
||||
completion: All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT
|
||||
- 'File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation'
|
||||
blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations
|
||||
done: Code matches reqs + All validations pass + Follows standards + File List complete
|
||||
completion: All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Update File List→Mark Ready for Review→HALT
|
||||
dependencies:
|
||||
tasks:
|
||||
- execute-checklist
|
||||
|
||||
32
dist/agents/pm.txt
vendored
32
dist/agents/pm.txt
vendored
@@ -978,9 +978,27 @@ The LLM will:
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -1013,19 +1031,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -1035,7 +1053,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -1054,7 +1072,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
|
||||
40
dist/agents/po.txt
vendored
40
dist/agents/po.txt
vendored
@@ -210,9 +210,27 @@ The LLM will:
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -245,19 +263,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -267,7 +285,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -286,7 +304,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
@@ -821,6 +839,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -828,6 +850,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#po-master-checklist ====================
|
||||
|
||||
167
dist/agents/qa.txt
vendored
167
dist/agents/qa.txt
vendored
@@ -52,34 +52,35 @@ activation-instructions:
|
||||
agent:
|
||||
name: Quinn
|
||||
id: qa
|
||||
title: Quality Assurance Test Architect
|
||||
title: Senior Developer & QA Architect
|
||||
icon: 🧪
|
||||
whenToUse: Use for test planning, test case creation, quality assurance, bug reporting, and testing strategy
|
||||
whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
|
||||
customization: null
|
||||
persona:
|
||||
role: Test Architect & Automation Expert
|
||||
style: Methodical, detail-oriented, quality-focused, strategic
|
||||
identity: Senior quality advocate with expertise in test architecture and automation
|
||||
focus: Comprehensive testing strategies, automation frameworks, quality assurance at every phase
|
||||
role: Senior Developer & Test Architect
|
||||
style: Methodical, detail-oriented, quality-focused, mentoring, strategic
|
||||
identity: Senior developer with deep expertise in code quality, architecture, and test automation
|
||||
focus: Code excellence through review, refactoring, and comprehensive testing strategies
|
||||
core_principles:
|
||||
- Senior Developer Mindset - Review and improve code as a senior mentoring juniors
|
||||
- Active Refactoring - Don't just identify issues, fix them with clear explanations
|
||||
- Test Strategy & Architecture - Design holistic testing strategies across all levels
|
||||
- Automation Excellence - Build maintainable and efficient test automation frameworks
|
||||
- Code Quality Excellence - Enforce best practices, patterns, and clean code principles
|
||||
- Shift-Left Testing - Integrate testing early in development lifecycle
|
||||
- Performance & Security - Proactively identify and fix performance/security issues
|
||||
- Mentorship Through Action - Explain WHY and HOW when making improvements
|
||||
- Risk-Based Testing - Prioritize testing based on risk and critical areas
|
||||
- Performance & Load Testing - Ensure systems meet performance requirements
|
||||
- Security Testing Integration - Incorporate security testing into QA process
|
||||
- Test Data Management - Design strategies for realistic and compliant test data
|
||||
- Continuous Testing & CI/CD - Integrate tests seamlessly into pipelines
|
||||
- Quality Metrics & Reporting - Track meaningful metrics and provide insights
|
||||
- Cross-Browser & Cross-Platform Testing - Ensure comprehensive compatibility
|
||||
- Continuous Improvement - Balance perfection with pragmatism
|
||||
- Architecture & Design Patterns - Ensure proper patterns and maintainable code structure
|
||||
startup:
|
||||
- Greet the user with your name and role, and inform of the *help command.
|
||||
commands:
|
||||
- help: Show numbered list of the following commands to allow selection
|
||||
- chat-mode: (Default) QA consultation with advanced-elicitation for test strategy
|
||||
- create-doc {template}: Create doc (no template = show available templates)
|
||||
- exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
- review-story
|
||||
data:
|
||||
- technical-preferences
|
||||
utils:
|
||||
@@ -87,6 +88,144 @@ dependencies:
|
||||
```
|
||||
==================== END: agents#qa ====================
|
||||
|
||||
==================== START: tasks#review-story ====================
|
||||
# review-story
|
||||
|
||||
When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
|
||||
|
||||
[[LLM: QA Agent executing review-story task as Senior Developer]]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Story status must be "Review"
|
||||
- Developer has completed all tasks and updated the File List
|
||||
- All automated tests are passing
|
||||
|
||||
## Review Process
|
||||
|
||||
1. **Read the Complete Story**
|
||||
- Review all acceptance criteria
|
||||
- Understand the dev notes and requirements
|
||||
- Note any completion notes from the developer
|
||||
|
||||
2. **Focus on the File List**
|
||||
- Verify all files listed were actually created/modified
|
||||
- Check for any missing files that should have been updated
|
||||
|
||||
3. **Senior Developer Code Review**
|
||||
- Review code with the eye of a senior developer
|
||||
- If changes form a cohesive whole, review them together
|
||||
- If changes are independent, review incrementally file by file
|
||||
- Focus on:
|
||||
- Code architecture and design patterns
|
||||
- Refactoring opportunities
|
||||
- Code duplication or inefficiencies
|
||||
- Performance optimizations
|
||||
- Security concerns
|
||||
- Best practices and patterns
|
||||
|
||||
4. **Active Refactoring**
|
||||
- As a senior developer, you CAN and SHOULD refactor code where improvements are needed
|
||||
- When refactoring:
|
||||
- Make the changes directly in the files
|
||||
- Explain WHY you're making the change
|
||||
- Describe HOW the change improves the code
|
||||
- Ensure all tests still pass after refactoring
|
||||
- Update the File List if you modify additional files
|
||||
|
||||
5. **Standards Compliance Check**
|
||||
- Verify adherence to `docs/coding-standards.md`
|
||||
- Check compliance with `docs/unified-project-structure.md`
|
||||
- Validate testing approach against `docs/testing-strategy.md`
|
||||
- Ensure all guidelines mentioned in the story are followed
|
||||
|
||||
6. **Acceptance Criteria Validation**
|
||||
- Verify each AC is fully implemented
|
||||
- Check for any missing functionality
|
||||
- Validate edge cases are handled
|
||||
|
||||
7. **Test Coverage Review**
|
||||
- Ensure unit tests cover edge cases
|
||||
- Add missing tests if critical coverage is lacking
|
||||
- Verify integration tests (if required) are comprehensive
|
||||
- Check that test assertions are meaningful
|
||||
- Look for missing test scenarios
|
||||
|
||||
8. **Documentation and Comments**
|
||||
- Verify code is self-documenting where possible
|
||||
- Add comments for complex logic if missing
|
||||
- Ensure any API changes are documented
|
||||
|
||||
## Append Results to Story File
|
||||
|
||||
After review and any refactoring, append your results to the story file in the QA Results section:
|
||||
|
||||
```markdown
|
||||
## QA Results
|
||||
|
||||
### Review Date: [Date]
|
||||
### Reviewed By: Quinn (Senior Developer QA)
|
||||
|
||||
### Code Quality Assessment
|
||||
[Overall assessment of implementation quality]
|
||||
|
||||
### Refactoring Performed
|
||||
[List any refactoring you performed with explanations]
|
||||
- **File**: [filename]
|
||||
- **Change**: [what was changed]
|
||||
- **Why**: [reason for change]
|
||||
- **How**: [how it improves the code]
|
||||
|
||||
### Compliance Check
|
||||
- Coding Standards: [✓/✗] [notes if any]
|
||||
- Project Structure: [✓/✗] [notes if any]
|
||||
- Testing Strategy: [✓/✗] [notes if any]
|
||||
- All ACs Met: [✓/✗] [notes if any]
|
||||
|
||||
### Improvements Checklist
|
||||
[Check off items you handled yourself, leave unchecked for dev to address]
|
||||
|
||||
- [x] Refactored user service for better error handling (services/user.service.ts)
|
||||
- [x] Added missing edge case tests (services/user.service.test.ts)
|
||||
- [ ] Consider extracting validation logic to separate validator class
|
||||
- [ ] Add integration test for error scenarios
|
||||
- [ ] Update API documentation for new error codes
|
||||
|
||||
### Security Review
|
||||
[Any security concerns found and whether addressed]
|
||||
|
||||
### Performance Considerations
|
||||
[Any performance issues found and whether addressed]
|
||||
|
||||
### Final Status
|
||||
[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
- You are a SENIOR developer reviewing junior/mid-level work
|
||||
- You have the authority and responsibility to improve code directly
|
||||
- Always explain your changes for learning purposes
|
||||
- Balance between perfection and pragmatism
|
||||
- Focus on significant improvements, not nitpicks
|
||||
|
||||
## Blocking Conditions
|
||||
|
||||
Stop the review and request clarification if:
|
||||
- Story file is incomplete or missing critical sections
|
||||
- File List is empty or clearly incomplete
|
||||
- No tests exist when they were required
|
||||
- Code changes don't align with story requirements
|
||||
- Critical architectural issues that require discussion
|
||||
|
||||
## Completion
|
||||
|
||||
After review:
|
||||
1. If all items are checked and approved: Update story status to "Done"
|
||||
2. If unchecked items remain: Keep status as "Review" for dev to address
|
||||
3. Always provide constructive feedback and explanations for learning
|
||||
==================== END: tasks#review-story ====================
|
||||
|
||||
==================== START: data#technical-preferences ====================
|
||||
# User-Defined Preferred Patterns and Preferences
|
||||
|
||||
|
||||
8
dist/agents/sm.txt
vendored
8
dist/agents/sm.txt
vendored
@@ -499,6 +499,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -506,6 +510,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#story-draft-checklist ====================
|
||||
|
||||
@@ -101,7 +101,7 @@ This task guides you through creating a new BMAD agent following the standard te
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Agent template: `.bmad-core/templates/agent-tmpl.md`
|
||||
- Agent template: `../templates/agent-tmpl.md`
|
||||
- Target directory: `.bmad-core/agents/`
|
||||
|
||||
## Steps
|
||||
@@ -318,7 +318,7 @@ Every expansion pack MUST include a custom BMAD orchestrator agent with sophisti
|
||||
|
||||
1. **Create Planning Document First**: Before any implementation, create a comprehensive plan for user approval
|
||||
2. **Agent Architecture Standards**: Use YAML-in-Markdown structure with activation instructions, personas, and command systems
|
||||
3. **Character Consistency**: Every agent must have a persistent persona with name, communication style, and numbered options protocol
|
||||
3. **Character Consistency**: Every agent must have a persistent persona with name, communication style, and numbered options protocol similar to `expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md`
|
||||
4. **Custom Themed Orchestrator**: The orchestrator should embody the domain theme (e.g., Office Manager for medical, Project Lead for tech) for better user experience
|
||||
5. **Core Utilities Required**: ALWAYS include these core files in every expansion pack:
|
||||
- `tasks/create-doc.md` - Document creation from templates
|
||||
@@ -326,8 +326,8 @@ Every expansion pack MUST include a custom BMAD orchestrator agent with sophisti
|
||||
- `utils/template-format.md` - Template markup conventions
|
||||
- `utils/workflow-management.md` - Workflow orchestration
|
||||
6. **Team and Workflow Requirements**: If pack has >1 agent, MUST include:
|
||||
- At least one team configuration in `agent-teams/`
|
||||
- At least one workflow in `workflows/`
|
||||
- At least one team configuration in `expansion-packs/{new-expansion}/agent-teams/`
|
||||
- At least one workflow in `expansion-packs/{new-expansion}workflows/`
|
||||
7. **Template Sophistication**: Implement LLM instruction embedding with `[[LLM: guidance]]`, conditional content, and variable systems
|
||||
8. **Workflow Orchestration**: Include decision trees, handoff protocols, and validation loops
|
||||
9. **Quality Assurance Integration**: Multi-level checklists with star ratings and ready/not-ready frameworks
|
||||
@@ -1318,14 +1318,6 @@ Embedded knowledge (automatic):
|
||||
- [ ] Template conditional content tested with different scenarios
|
||||
- [ ] Workflow decision trees validated with sample use cases
|
||||
- [ ] Character interactions tested for consistency and professional authenticity
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
==================== END: tasks#generate-expansion-pack ====================
|
||||
|
||||
==================== START: tasks#advanced-elicitation ====================
|
||||
|
||||
683
dist/teams/team-all.txt
vendored
683
dist/teams/team-all.txt
vendored
@@ -335,6 +335,7 @@ core_principles:
|
||||
- CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
|
||||
- Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
|
||||
- Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
|
||||
- Quality Gate Discipline - NEVER complete tasks with failing automated validations
|
||||
- Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix.
|
||||
- Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
|
||||
- Code Excellence - Clean, secure, maintainable code per loaded standards
|
||||
@@ -346,15 +347,16 @@ commands:
|
||||
- complete-story: Finalize to "Review"
|
||||
- exit: Say goodbye as the Developer, and then abandon inhabiting this persona
|
||||
task-execution:
|
||||
flow: Read task→Implement→Write tests→Pass tests→Update [x]→Next task
|
||||
flow: Read task→Implement→Write tests→Execute validations→Only if ALL pass→Update [x]→Next task
|
||||
updates-ONLY:
|
||||
- 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
|
||||
- 'Debug Log: | Task | File | Change | Reverted? |'
|
||||
- 'Completion Notes: Deviations only, <50 words'
|
||||
- 'Change Log: Requirement changes only'
|
||||
blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config
|
||||
done: Code matches reqs + Tests pass + Follows standards + No lint errors
|
||||
completion: All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT
|
||||
- 'File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation'
|
||||
blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations
|
||||
done: Code matches reqs + All validations pass + Follows standards + File List complete
|
||||
completion: All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Update File List→Mark Ready for Review→HALT
|
||||
dependencies:
|
||||
tasks:
|
||||
- execute-checklist
|
||||
@@ -501,34 +503,35 @@ activation-instructions:
|
||||
agent:
|
||||
name: Quinn
|
||||
id: qa
|
||||
title: Quality Assurance Test Architect
|
||||
title: Senior Developer & QA Architect
|
||||
icon: 🧪
|
||||
whenToUse: Use for test planning, test case creation, quality assurance, bug reporting, and testing strategy
|
||||
whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
|
||||
customization: null
|
||||
persona:
|
||||
role: Test Architect & Automation Expert
|
||||
style: Methodical, detail-oriented, quality-focused, strategic
|
||||
identity: Senior quality advocate with expertise in test architecture and automation
|
||||
focus: Comprehensive testing strategies, automation frameworks, quality assurance at every phase
|
||||
role: Senior Developer & Test Architect
|
||||
style: Methodical, detail-oriented, quality-focused, mentoring, strategic
|
||||
identity: Senior developer with deep expertise in code quality, architecture, and test automation
|
||||
focus: Code excellence through review, refactoring, and comprehensive testing strategies
|
||||
core_principles:
|
||||
- Senior Developer Mindset - Review and improve code as a senior mentoring juniors
|
||||
- Active Refactoring - Don't just identify issues, fix them with clear explanations
|
||||
- Test Strategy & Architecture - Design holistic testing strategies across all levels
|
||||
- Automation Excellence - Build maintainable and efficient test automation frameworks
|
||||
- Code Quality Excellence - Enforce best practices, patterns, and clean code principles
|
||||
- Shift-Left Testing - Integrate testing early in development lifecycle
|
||||
- Performance & Security - Proactively identify and fix performance/security issues
|
||||
- Mentorship Through Action - Explain WHY and HOW when making improvements
|
||||
- Risk-Based Testing - Prioritize testing based on risk and critical areas
|
||||
- Performance & Load Testing - Ensure systems meet performance requirements
|
||||
- Security Testing Integration - Incorporate security testing into QA process
|
||||
- Test Data Management - Design strategies for realistic and compliant test data
|
||||
- Continuous Testing & CI/CD - Integrate tests seamlessly into pipelines
|
||||
- Quality Metrics & Reporting - Track meaningful metrics and provide insights
|
||||
- Cross-Browser & Cross-Platform Testing - Ensure comprehensive compatibility
|
||||
- Continuous Improvement - Balance perfection with pragmatism
|
||||
- Architecture & Design Patterns - Ensure proper patterns and maintainable code structure
|
||||
startup:
|
||||
- Greet the user with your name and role, and inform of the *help command.
|
||||
commands:
|
||||
- help: Show numbered list of the following commands to allow selection
|
||||
- chat-mode: (Default) QA consultation with advanced-elicitation for test strategy
|
||||
- create-doc {template}: Create doc (no template = show available templates)
|
||||
- exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
- review-story
|
||||
data:
|
||||
- technical-preferences
|
||||
utils:
|
||||
@@ -918,6 +921,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -932,7 +979,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -941,13 +988,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -964,6 +1020,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -1241,10 +1338,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -1258,19 +1359,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -1290,12 +1406,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -1376,12 +1507,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: utils#workflow-management ====================
|
||||
@@ -6948,9 +7161,27 @@ The story creation is successful when:
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -6983,19 +7214,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -7005,7 +7236,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -7024,7 +7255,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
@@ -8183,6 +8414,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -8190,6 +8425,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#po-master-checklist ====================
|
||||
@@ -8636,6 +8875,144 @@ After presenting the report, ask if the user wants:
|
||||
- **REJECTED**: The plan requires significant revision to address critical deficiencies.
|
||||
==================== END: checklists#po-master-checklist ====================
|
||||
|
||||
==================== START: tasks#review-story ====================
|
||||
# review-story
|
||||
|
||||
When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
|
||||
|
||||
[[LLM: QA Agent executing review-story task as Senior Developer]]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Story status must be "Review"
|
||||
- Developer has completed all tasks and updated the File List
|
||||
- All automated tests are passing
|
||||
|
||||
## Review Process
|
||||
|
||||
1. **Read the Complete Story**
|
||||
- Review all acceptance criteria
|
||||
- Understand the dev notes and requirements
|
||||
- Note any completion notes from the developer
|
||||
|
||||
2. **Focus on the File List**
|
||||
- Verify all files listed were actually created/modified
|
||||
- Check for any missing files that should have been updated
|
||||
|
||||
3. **Senior Developer Code Review**
|
||||
- Review code with the eye of a senior developer
|
||||
- If changes form a cohesive whole, review them together
|
||||
- If changes are independent, review incrementally file by file
|
||||
- Focus on:
|
||||
- Code architecture and design patterns
|
||||
- Refactoring opportunities
|
||||
- Code duplication or inefficiencies
|
||||
- Performance optimizations
|
||||
- Security concerns
|
||||
- Best practices and patterns
|
||||
|
||||
4. **Active Refactoring**
|
||||
- As a senior developer, you CAN and SHOULD refactor code where improvements are needed
|
||||
- When refactoring:
|
||||
- Make the changes directly in the files
|
||||
- Explain WHY you're making the change
|
||||
- Describe HOW the change improves the code
|
||||
- Ensure all tests still pass after refactoring
|
||||
- Update the File List if you modify additional files
|
||||
|
||||
5. **Standards Compliance Check**
|
||||
- Verify adherence to `docs/coding-standards.md`
|
||||
- Check compliance with `docs/unified-project-structure.md`
|
||||
- Validate testing approach against `docs/testing-strategy.md`
|
||||
- Ensure all guidelines mentioned in the story are followed
|
||||
|
||||
6. **Acceptance Criteria Validation**
|
||||
- Verify each AC is fully implemented
|
||||
- Check for any missing functionality
|
||||
- Validate edge cases are handled
|
||||
|
||||
7. **Test Coverage Review**
|
||||
- Ensure unit tests cover edge cases
|
||||
- Add missing tests if critical coverage is lacking
|
||||
- Verify integration tests (if required) are comprehensive
|
||||
- Check that test assertions are meaningful
|
||||
- Look for missing test scenarios
|
||||
|
||||
8. **Documentation and Comments**
|
||||
- Verify code is self-documenting where possible
|
||||
- Add comments for complex logic if missing
|
||||
- Ensure any API changes are documented
|
||||
|
||||
## Append Results to Story File
|
||||
|
||||
After review and any refactoring, append your results to the story file in the QA Results section:
|
||||
|
||||
```markdown
|
||||
## QA Results
|
||||
|
||||
### Review Date: [Date]
|
||||
### Reviewed By: Quinn (Senior Developer QA)
|
||||
|
||||
### Code Quality Assessment
|
||||
[Overall assessment of implementation quality]
|
||||
|
||||
### Refactoring Performed
|
||||
[List any refactoring you performed with explanations]
|
||||
- **File**: [filename]
|
||||
- **Change**: [what was changed]
|
||||
- **Why**: [reason for change]
|
||||
- **How**: [how it improves the code]
|
||||
|
||||
### Compliance Check
|
||||
- Coding Standards: [✓/✗] [notes if any]
|
||||
- Project Structure: [✓/✗] [notes if any]
|
||||
- Testing Strategy: [✓/✗] [notes if any]
|
||||
- All ACs Met: [✓/✗] [notes if any]
|
||||
|
||||
### Improvements Checklist
|
||||
[Check off items you handled yourself, leave unchecked for dev to address]
|
||||
|
||||
- [x] Refactored user service for better error handling (services/user.service.ts)
|
||||
- [x] Added missing edge case tests (services/user.service.test.ts)
|
||||
- [ ] Consider extracting validation logic to separate validator class
|
||||
- [ ] Add integration test for error scenarios
|
||||
- [ ] Update API documentation for new error codes
|
||||
|
||||
### Security Review
|
||||
[Any security concerns found and whether addressed]
|
||||
|
||||
### Performance Considerations
|
||||
[Any performance issues found and whether addressed]
|
||||
|
||||
### Final Status
|
||||
[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
- You are a SENIOR developer reviewing junior/mid-level work
|
||||
- You have the authority and responsibility to improve code directly
|
||||
- Always explain your changes for learning purposes
|
||||
- Balance between perfection and pragmatism
|
||||
- Focus on significant improvements, not nitpicks
|
||||
|
||||
## Blocking Conditions
|
||||
|
||||
Stop the review and request clarification if:
|
||||
- Story file is incomplete or missing critical sections
|
||||
- File List is empty or clearly incomplete
|
||||
- No tests exist when they were required
|
||||
- Code changes don't align with story requirements
|
||||
- Critical architectural issues that require discussion
|
||||
|
||||
## Completion
|
||||
|
||||
After review:
|
||||
1. If all items are checked and approved: Update story status to "Done"
|
||||
2. If unchecked items remain: Keep status as "Review" for dev to address
|
||||
3. Always provide constructive feedback and explanations for learning
|
||||
==================== END: tasks#review-story ====================
|
||||
|
||||
==================== START: tasks#create-next-story ====================
|
||||
# Create Next Story Task
|
||||
|
||||
@@ -9565,7 +9942,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9646,7 +10058,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9734,7 +10181,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9850,7 +10332,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9960,7 +10477,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -10079,7 +10631,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
506
dist/teams/team-fullstack.txt
vendored
506
dist/teams/team-fullstack.txt
vendored
@@ -765,6 +765,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -779,7 +823,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -788,13 +832,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -811,6 +864,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -1088,10 +1182,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -1105,19 +1203,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -1137,12 +1250,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -1223,12 +1351,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: utils#workflow-management ====================
|
||||
@@ -3322,9 +3532,27 @@ The LLM will:
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -3357,19 +3585,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -3379,7 +3607,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -3398,7 +3626,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
@@ -8396,6 +8624,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -8403,6 +8635,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#po-master-checklist ====================
|
||||
@@ -8894,7 +9130,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -8975,7 +9246,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9063,7 +9369,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9179,7 +9520,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9289,7 +9665,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -9408,7 +9819,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
461
dist/teams/team-ide-minimal.txt
vendored
461
dist/teams/team-ide-minimal.txt
vendored
@@ -319,6 +319,7 @@ core_principles:
|
||||
- CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
|
||||
- Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
|
||||
- Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
|
||||
- Quality Gate Discipline - NEVER complete tasks with failing automated validations
|
||||
- Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix.
|
||||
- Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
|
||||
- Code Excellence - Clean, secure, maintainable code per loaded standards
|
||||
@@ -330,15 +331,16 @@ commands:
|
||||
- complete-story: Finalize to "Review"
|
||||
- exit: Say goodbye as the Developer, and then abandon inhabiting this persona
|
||||
task-execution:
|
||||
flow: Read task→Implement→Write tests→Pass tests→Update [x]→Next task
|
||||
flow: Read task→Implement→Write tests→Execute validations→Only if ALL pass→Update [x]→Next task
|
||||
updates-ONLY:
|
||||
- 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
|
||||
- 'Debug Log: | Task | File | Change | Reverted? |'
|
||||
- 'Completion Notes: Deviations only, <50 words'
|
||||
- 'Change Log: Requirement changes only'
|
||||
blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config
|
||||
done: Code matches reqs + Tests pass + Follows standards + No lint errors
|
||||
completion: All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT
|
||||
- 'File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation'
|
||||
blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations
|
||||
done: Code matches reqs + All validations pass + Follows standards + File List complete
|
||||
completion: All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Update File List→Mark Ready for Review→HALT
|
||||
dependencies:
|
||||
tasks:
|
||||
- execute-checklist
|
||||
@@ -361,34 +363,35 @@ activation-instructions:
|
||||
agent:
|
||||
name: Quinn
|
||||
id: qa
|
||||
title: Quality Assurance Test Architect
|
||||
title: Senior Developer & QA Architect
|
||||
icon: 🧪
|
||||
whenToUse: Use for test planning, test case creation, quality assurance, bug reporting, and testing strategy
|
||||
whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
|
||||
customization: null
|
||||
persona:
|
||||
role: Test Architect & Automation Expert
|
||||
style: Methodical, detail-oriented, quality-focused, strategic
|
||||
identity: Senior quality advocate with expertise in test architecture and automation
|
||||
focus: Comprehensive testing strategies, automation frameworks, quality assurance at every phase
|
||||
role: Senior Developer & Test Architect
|
||||
style: Methodical, detail-oriented, quality-focused, mentoring, strategic
|
||||
identity: Senior developer with deep expertise in code quality, architecture, and test automation
|
||||
focus: Code excellence through review, refactoring, and comprehensive testing strategies
|
||||
core_principles:
|
||||
- Senior Developer Mindset - Review and improve code as a senior mentoring juniors
|
||||
- Active Refactoring - Don't just identify issues, fix them with clear explanations
|
||||
- Test Strategy & Architecture - Design holistic testing strategies across all levels
|
||||
- Automation Excellence - Build maintainable and efficient test automation frameworks
|
||||
- Code Quality Excellence - Enforce best practices, patterns, and clean code principles
|
||||
- Shift-Left Testing - Integrate testing early in development lifecycle
|
||||
- Performance & Security - Proactively identify and fix performance/security issues
|
||||
- Mentorship Through Action - Explain WHY and HOW when making improvements
|
||||
- Risk-Based Testing - Prioritize testing based on risk and critical areas
|
||||
- Performance & Load Testing - Ensure systems meet performance requirements
|
||||
- Security Testing Integration - Incorporate security testing into QA process
|
||||
- Test Data Management - Design strategies for realistic and compliant test data
|
||||
- Continuous Testing & CI/CD - Integrate tests seamlessly into pipelines
|
||||
- Quality Metrics & Reporting - Track meaningful metrics and provide insights
|
||||
- Cross-Browser & Cross-Platform Testing - Ensure comprehensive compatibility
|
||||
- Continuous Improvement - Balance perfection with pragmatism
|
||||
- Architecture & Design Patterns - Ensure proper patterns and maintainable code structure
|
||||
startup:
|
||||
- Greet the user with your name and role, and inform of the *help command.
|
||||
commands:
|
||||
- help: Show numbered list of the following commands to allow selection
|
||||
- chat-mode: (Default) QA consultation with advanced-elicitation for test strategy
|
||||
- create-doc {template}: Create doc (no template = show available templates)
|
||||
- exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
- review-story
|
||||
data:
|
||||
- technical-preferences
|
||||
utils:
|
||||
@@ -664,6 +667,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -678,7 +725,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -687,13 +734,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -710,6 +766,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -987,10 +1084,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -1004,19 +1105,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -1036,12 +1152,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -1122,12 +1253,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: utils#workflow-management ====================
|
||||
@@ -1494,9 +1707,27 @@ The LLM will:
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -1529,19 +1760,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -1551,7 +1782,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -1570,7 +1801,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
@@ -2105,6 +2336,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -2112,6 +2347,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#po-master-checklist ====================
|
||||
@@ -3261,6 +3500,144 @@ Be honest - it's better to flag issues now than have them discovered later.]]
|
||||
- [ ] I, the Developer Agent, confirm that all applicable items above have been addressed.
|
||||
==================== END: checklists#story-dod-checklist ====================
|
||||
|
||||
==================== START: tasks#review-story ====================
|
||||
# review-story
|
||||
|
||||
When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
|
||||
|
||||
[[LLM: QA Agent executing review-story task as Senior Developer]]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Story status must be "Review"
|
||||
- Developer has completed all tasks and updated the File List
|
||||
- All automated tests are passing
|
||||
|
||||
## Review Process
|
||||
|
||||
1. **Read the Complete Story**
|
||||
- Review all acceptance criteria
|
||||
- Understand the dev notes and requirements
|
||||
- Note any completion notes from the developer
|
||||
|
||||
2. **Focus on the File List**
|
||||
- Verify all files listed were actually created/modified
|
||||
- Check for any missing files that should have been updated
|
||||
|
||||
3. **Senior Developer Code Review**
|
||||
- Review code with the eye of a senior developer
|
||||
- If changes form a cohesive whole, review them together
|
||||
- If changes are independent, review incrementally file by file
|
||||
- Focus on:
|
||||
- Code architecture and design patterns
|
||||
- Refactoring opportunities
|
||||
- Code duplication or inefficiencies
|
||||
- Performance optimizations
|
||||
- Security concerns
|
||||
- Best practices and patterns
|
||||
|
||||
4. **Active Refactoring**
|
||||
- As a senior developer, you CAN and SHOULD refactor code where improvements are needed
|
||||
- When refactoring:
|
||||
- Make the changes directly in the files
|
||||
- Explain WHY you're making the change
|
||||
- Describe HOW the change improves the code
|
||||
- Ensure all tests still pass after refactoring
|
||||
- Update the File List if you modify additional files
|
||||
|
||||
5. **Standards Compliance Check**
|
||||
- Verify adherence to `docs/coding-standards.md`
|
||||
- Check compliance with `docs/unified-project-structure.md`
|
||||
- Validate testing approach against `docs/testing-strategy.md`
|
||||
- Ensure all guidelines mentioned in the story are followed
|
||||
|
||||
6. **Acceptance Criteria Validation**
|
||||
- Verify each AC is fully implemented
|
||||
- Check for any missing functionality
|
||||
- Validate edge cases are handled
|
||||
|
||||
7. **Test Coverage Review**
|
||||
- Ensure unit tests cover edge cases
|
||||
- Add missing tests if critical coverage is lacking
|
||||
- Verify integration tests (if required) are comprehensive
|
||||
- Check that test assertions are meaningful
|
||||
- Look for missing test scenarios
|
||||
|
||||
8. **Documentation and Comments**
|
||||
- Verify code is self-documenting where possible
|
||||
- Add comments for complex logic if missing
|
||||
- Ensure any API changes are documented
|
||||
|
||||
## Append Results to Story File
|
||||
|
||||
After review and any refactoring, append your results to the story file in the QA Results section:
|
||||
|
||||
```markdown
|
||||
## QA Results
|
||||
|
||||
### Review Date: [Date]
|
||||
### Reviewed By: Quinn (Senior Developer QA)
|
||||
|
||||
### Code Quality Assessment
|
||||
[Overall assessment of implementation quality]
|
||||
|
||||
### Refactoring Performed
|
||||
[List any refactoring you performed with explanations]
|
||||
- **File**: [filename]
|
||||
- **Change**: [what was changed]
|
||||
- **Why**: [reason for change]
|
||||
- **How**: [how it improves the code]
|
||||
|
||||
### Compliance Check
|
||||
- Coding Standards: [✓/✗] [notes if any]
|
||||
- Project Structure: [✓/✗] [notes if any]
|
||||
- Testing Strategy: [✓/✗] [notes if any]
|
||||
- All ACs Met: [✓/✗] [notes if any]
|
||||
|
||||
### Improvements Checklist
|
||||
[Check off items you handled yourself, leave unchecked for dev to address]
|
||||
|
||||
- [x] Refactored user service for better error handling (services/user.service.ts)
|
||||
- [x] Added missing edge case tests (services/user.service.test.ts)
|
||||
- [ ] Consider extracting validation logic to separate validator class
|
||||
- [ ] Add integration test for error scenarios
|
||||
- [ ] Update API documentation for new error codes
|
||||
|
||||
### Security Review
|
||||
[Any security concerns found and whether addressed]
|
||||
|
||||
### Performance Considerations
|
||||
[Any performance issues found and whether addressed]
|
||||
|
||||
### Final Status
|
||||
[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
- You are a SENIOR developer reviewing junior/mid-level work
|
||||
- You have the authority and responsibility to improve code directly
|
||||
- Always explain your changes for learning purposes
|
||||
- Balance between perfection and pragmatism
|
||||
- Focus on significant improvements, not nitpicks
|
||||
|
||||
## Blocking Conditions
|
||||
|
||||
Stop the review and request clarification if:
|
||||
- Story file is incomplete or missing critical sections
|
||||
- File List is empty or clearly incomplete
|
||||
- No tests exist when they were required
|
||||
- Code changes don't align with story requirements
|
||||
- Critical architectural issues that require discussion
|
||||
|
||||
## Completion
|
||||
|
||||
After review:
|
||||
1. If all items are checked and approved: Update story status to "Done"
|
||||
2. If unchecked items remain: Keep status as "Review" for dev to address
|
||||
3. Always provide constructive feedback and explanations for learning
|
||||
==================== END: tasks#review-story ====================
|
||||
|
||||
==================== START: data#technical-preferences ====================
|
||||
# User-Defined Preferred Patterns and Preferences
|
||||
|
||||
|
||||
358
dist/teams/team-no-ui.txt
vendored
358
dist/teams/team-no-ui.txt
vendored
@@ -697,6 +697,50 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
- **Quality Assurance**: Structured testing and validation
|
||||
- **Documentation**: Professional PRDs, architecture docs, user stories
|
||||
|
||||
## How BMAD Works
|
||||
|
||||
### The Core Method
|
||||
|
||||
BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
|
||||
|
||||
1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
|
||||
2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
|
||||
3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
|
||||
4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
|
||||
|
||||
### The Two-Phase Approach
|
||||
|
||||
**Phase 1: Planning (Web UI - Cost Effective)**
|
||||
- Use large context windows (Gemini's 1M tokens)
|
||||
- Generate comprehensive documents (PRD, Architecture)
|
||||
- Leverage multiple agents for brainstorming
|
||||
- Create once, use throughout development
|
||||
|
||||
**Phase 2: Development (IDE - Implementation)**
|
||||
- Shard documents into manageable pieces
|
||||
- Execute focused SM → Dev cycles
|
||||
- One story at a time, sequential progress
|
||||
- Real-time file operations and testing
|
||||
|
||||
### The Development Loop
|
||||
|
||||
```text
|
||||
1. SM Agent (New Chat) → Creates next story from sharded docs
|
||||
2. You → Review and approve story
|
||||
3. Dev Agent (New Chat) → Implements approved story
|
||||
4. QA Agent (New Chat) → Reviews and refactors code
|
||||
5. You → Verify completion
|
||||
6. Repeat until epic complete
|
||||
```
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Context Optimization**: Clean chats = better AI performance
|
||||
- **Role Clarity**: Agents don't context-switch = higher quality
|
||||
- **Incremental Progress**: Small stories = manageable complexity
|
||||
- **Human Oversight**: You validate each step = quality control
|
||||
- **Document-Driven**: Specs guide everything = consistency
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start Options
|
||||
@@ -711,7 +755,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
|
||||
5. Type `/help` to see available commands
|
||||
|
||||
#### Option 2: IDE Integration
|
||||
**Best for**: Cursor, Claude Code, Windsurf, VS Code users
|
||||
**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
|
||||
|
||||
```bash
|
||||
# Interactive installation (recommended)
|
||||
@@ -720,13 +764,22 @@ npx bmad-method install
|
||||
|
||||
**Installation Steps**:
|
||||
- Choose "Complete installation"
|
||||
- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
|
||||
- Select your IDE from supported options:
|
||||
- **Cursor**: Native AI integration
|
||||
- **Claude Code**: Anthropic's official IDE
|
||||
- **Windsurf**: Built-in AI capabilities
|
||||
- **Cline**: VS Code extension with AI features
|
||||
- **Roo Code**: Web-based IDE with agent support
|
||||
|
||||
**Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
|
||||
|
||||
**Verify Installation**:
|
||||
- `.bmad-core/` folder created with all agents
|
||||
- IDE-specific integration files created
|
||||
- All agent commands/rules/modes available
|
||||
|
||||
**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
|
||||
|
||||
### Environment Selection Guide
|
||||
|
||||
**Use Web UI for**:
|
||||
@@ -743,6 +796,47 @@ npx bmad-method install
|
||||
|
||||
**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
|
||||
|
||||
### IDE-Only Workflow Considerations
|
||||
|
||||
**Can you do everything in IDE?** Yes, but understand the tradeoffs:
|
||||
|
||||
**Pros of IDE-Only**:
|
||||
- Single environment workflow
|
||||
- Direct file operations from start
|
||||
- No copy/paste between environments
|
||||
- Immediate project integration
|
||||
|
||||
**Cons of IDE-Only**:
|
||||
- Higher token costs for large document creation
|
||||
- Smaller context windows (varies by IDE/model)
|
||||
- May hit limits during planning phases
|
||||
- Less cost-effective for brainstorming
|
||||
|
||||
**Using Web Agents in IDE**:
|
||||
- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
|
||||
- **Why it matters**: Dev agents are kept lean to maximize coding context
|
||||
- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
|
||||
|
||||
**About bmad-master and bmad-orchestrator**:
|
||||
- **bmad-master**: CAN do any task without switching agents, BUT...
|
||||
- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
|
||||
- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
|
||||
- **If using bmad-master/orchestrator**: Fine for planning phases, but...
|
||||
|
||||
**CRITICAL RULE for Development**:
|
||||
- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
|
||||
- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
|
||||
- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
|
||||
- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
|
||||
|
||||
**Best Practice for IDE-Only**:
|
||||
1. Use PM/Architect/UX agents for planning (better than bmad-master)
|
||||
2. Create documents directly in project
|
||||
3. Shard immediately after creation
|
||||
4. **MUST switch to SM agent** for story creation
|
||||
5. **MUST switch to Dev agent** for implementation
|
||||
6. Keep planning and coding in separate chat sessions
|
||||
|
||||
## Core Configuration (core-config.yml)
|
||||
|
||||
**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
|
||||
@@ -1020,10 +1114,14 @@ that can handle [specific requirements]."
|
||||
|
||||
**Prerequisites**: Planning documents must exist in `docs/` folder
|
||||
|
||||
1. **Document Sharding**:
|
||||
- `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
|
||||
- If architecture exists, shard to `docs/architecture/` folder
|
||||
- Results in multiple manageable documents and epic files
|
||||
1. **Document Sharding** (CRITICAL STEP):
|
||||
- Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
|
||||
- Two methods to shard:
|
||||
a) **Manual**: Drag `shard-doc` task + document file into chat
|
||||
b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
|
||||
- Shards `docs/prd.md` → `docs/prd/` folder
|
||||
- Shards `docs/architecture.md` → `docs/architecture/` folder
|
||||
- **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
|
||||
|
||||
2. **Verify Sharded Content**:
|
||||
- At least one `epic-n.md` file in `docs/prd/` with stories in development order
|
||||
@@ -1037,19 +1135,34 @@ that can handle [specific requirements]."
|
||||
|
||||
3. **Development Cycle** (Sequential, one story at a time):
|
||||
|
||||
**Step 1 - Story Creation**: New chat window → `@sm` → `*create`
|
||||
**CRITICAL CONTEXT MANAGEMENT**:
|
||||
- **Context windows matter!** Always use fresh, clean context windows
|
||||
- **Model selection matters!** Use most powerful thinking model for SM story creation
|
||||
- **ALWAYS start new chat between SM, Dev, and QA work**
|
||||
|
||||
**Step 1 - Story Creation**:
|
||||
- **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
|
||||
- SM executes create-next-story task
|
||||
- Review generated story in `docs/stories/`
|
||||
- Update status from "Draft" to "Approved"
|
||||
|
||||
**Step 2 - Story Implementation**: New chat window → `@dev`
|
||||
**Step 2 - Story Implementation**:
|
||||
- **NEW CLEAN CHAT** → `@dev`
|
||||
- Agent asks which story to implement
|
||||
- Include story file content to save dev agent lookup time
|
||||
- Dev follows tasks/subtasks, marking completion
|
||||
- Dev leaves notes for SM about any deviations
|
||||
- Update status to "Done"
|
||||
- Dev maintains File List of all changes
|
||||
- Dev marks story as "Review" when complete with all tests passing
|
||||
|
||||
**Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
|
||||
**Step 3 - Senior QA Review**:
|
||||
- **NEW CLEAN CHAT** → `@qa` → execute review-story task
|
||||
- QA performs senior developer code review
|
||||
- QA can refactor and improve code directly
|
||||
- QA appends results to story's QA Results section
|
||||
- If approved: Status → "Done"
|
||||
- If changes needed: Status stays "Review" with unchecked items for dev
|
||||
|
||||
**Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
|
||||
|
||||
**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
|
||||
|
||||
@@ -1069,12 +1182,27 @@ Each status change requires user verification and approval before proceeding.
|
||||
- Development execution
|
||||
- Testing and deployment
|
||||
|
||||
#### Brownfield Enhancement
|
||||
- Current system analysis
|
||||
- Enhancement planning
|
||||
- Impact assessment
|
||||
- Incremental development
|
||||
- Integration testing
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -1155,12 +1283,94 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
|
||||
- **Keep conversations focused** - One agent, one task per conversation
|
||||
- **Review everything** - Always review and approve before marking complete
|
||||
|
||||
## Contributing to BMAD-METHOD
|
||||
|
||||
### Quick Contribution Guidelines
|
||||
|
||||
For full details, see `CONTRIBUTING.md`. Key points:
|
||||
|
||||
**Fork Workflow**:
|
||||
1. Fork the repository
|
||||
2. Create feature branches
|
||||
3. Submit PRs to `next` branch (default) or `main` for critical fixes only
|
||||
4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
|
||||
5. One feature/fix per PR
|
||||
|
||||
**PR Requirements**:
|
||||
- Clear descriptions (max 200 words) with What/Why/How/Testing
|
||||
- Use conventional commits (feat:, fix:, docs:)
|
||||
- Atomic commits - one logical change per commit
|
||||
- Must align with guiding principles
|
||||
|
||||
**Core Principles** (from GUIDING-PRINCIPLES.md):
|
||||
- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
|
||||
- **Natural Language First**: Everything in markdown, no code in core
|
||||
- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
|
||||
- **Design Philosophy**: "Dev agents code, planning agents plan"
|
||||
|
||||
## Expansion Packs
|
||||
|
||||
### What Are Expansion Packs?
|
||||
|
||||
Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
|
||||
|
||||
### Why Use Expansion Packs?
|
||||
|
||||
1. **Keep Core Lean**: Dev agents maintain maximum context for coding
|
||||
2. **Domain Expertise**: Deep, specialized knowledge without bloating core
|
||||
3. **Community Innovation**: Anyone can create and share packs
|
||||
4. **Modular Design**: Install only what you need
|
||||
|
||||
### Available Expansion Packs
|
||||
|
||||
**Technical Packs**:
|
||||
- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
|
||||
- **Game Development**: Game designers, level designers, narrative writers
|
||||
- **Mobile Development**: iOS/Android specialists, mobile UX experts
|
||||
- **Data Science**: ML engineers, data scientists, visualization experts
|
||||
|
||||
**Non-Technical Packs**:
|
||||
- **Business Strategy**: Consultants, financial analysts, marketing strategists
|
||||
- **Creative Writing**: Plot architects, character developers, world builders
|
||||
- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
|
||||
- **Education**: Curriculum designers, assessment specialists
|
||||
- **Legal Support**: Contract analysts, compliance checkers
|
||||
|
||||
**Specialty Packs**:
|
||||
- **Expansion Creator**: Tools to build your own expansion packs
|
||||
- **RPG Game Master**: Tabletop gaming assistance
|
||||
- **Life Event Planning**: Wedding planners, event coordinators
|
||||
- **Scientific Research**: Literature reviewers, methodology designers
|
||||
|
||||
### Using Expansion Packs
|
||||
|
||||
1. **Browse Available Packs**: Check `expansion-packs/` directory
|
||||
2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
|
||||
3. **Install via CLI**:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Install expansion pack" option
|
||||
```
|
||||
4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
|
||||
|
||||
### Creating Custom Expansion Packs
|
||||
|
||||
Use the **expansion-creator** pack to build your own:
|
||||
|
||||
1. **Define Domain**: What expertise are you capturing?
|
||||
2. **Design Agents**: Create specialized roles with clear boundaries
|
||||
3. **Build Resources**: Tasks, templates, checklists for your domain
|
||||
4. **Test & Share**: Validate with real use cases, share with community
|
||||
|
||||
**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands**: Use `/help` in any environment to see available commands
|
||||
- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
|
||||
- **Documentation**: Check `docs/` folder for project-specific context
|
||||
- **Community**: Discord and GitHub resources available for support
|
||||
- **Contributing**: See `CONTRIBUTING.md` for full guidelines
|
||||
==================== END: data#bmad-kb ====================
|
||||
|
||||
==================== START: utils#workflow-management ====================
|
||||
@@ -3254,9 +3464,27 @@ The LLM will:
|
||||
- Create a folder structure to organize the sharded documents
|
||||
- Maintain all content integrity including code blocks, diagrams, and markdown formatting
|
||||
|
||||
## Recommended Method: @kayvan/markdown-tree-parser
|
||||
## Primary Method: Automatic with markdown-tree
|
||||
|
||||
[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
|
||||
[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
|
||||
|
||||
If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
|
||||
|
||||
If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
|
||||
|
||||
1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
2. Or set markdownExploder to false in bmad-core/core-config.yml
|
||||
|
||||
**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
|
||||
|
||||
If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
|
||||
|
||||
1. Set markdownExploder to true in bmad-core/core-config.yml
|
||||
2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
|
||||
|
||||
I will now proceed with the manual sharding process."
|
||||
|
||||
Then proceed with the manual method below ONLY if markdownExploder is false.]]
|
||||
|
||||
### Installation and Usage
|
||||
|
||||
@@ -3289,19 +3517,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
|
||||
---
|
||||
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available)
|
||||
## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
|
||||
|
||||
[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
|
||||
|
||||
### Task Instructions
|
||||
|
||||
### 1. Identify Document and Target Location
|
||||
1. Identify Document and Target Location
|
||||
|
||||
- Determine which document to shard (user-provided path)
|
||||
- Create a new folder under `docs/` with the same name as the document (without extension)
|
||||
- Example: `docs/prd.md` → create folder `docs/prd/`
|
||||
|
||||
### 2. Parse and Extract Sections
|
||||
2. Parse and Extract Sections
|
||||
|
||||
[[LLM: When sharding the document:
|
||||
|
||||
@@ -3311,7 +3539,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
|
||||
- Extract the section heading and ALL content until the next level 2 section
|
||||
- Include all subsections, code blocks, diagrams, lists, tables, etc.
|
||||
- Be extremely careful with:
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks
|
||||
- Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
|
||||
- Mermaid diagrams - preserve the complete diagram syntax
|
||||
- Nested markdown elements
|
||||
- Multi-line content that might contain ## inside code blocks
|
||||
@@ -3330,7 +3558,7 @@ For each extracted section:
|
||||
|
||||
2. **Adjust heading levels**:
|
||||
|
||||
- The level 2 heading becomes level 1 (# instead of ##)
|
||||
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
|
||||
- All subsection levels decrease by 1:
|
||||
|
||||
```txt
|
||||
@@ -7858,6 +8086,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
|
||||
[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
|
||||
|
||||
### File List
|
||||
|
||||
[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
|
||||
@@ -7865,6 +8097,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## QA Results
|
||||
|
||||
[[LLM: QA Agent Results]]
|
||||
==================== END: templates#story-tmpl ====================
|
||||
|
||||
==================== START: checklists#po-master-checklist ====================
|
||||
@@ -8365,7 +8601,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
@@ -8457,7 +8728,42 @@ workflow:
|
||||
|
||||
- workflow_end:
|
||||
action: move_to_ide
|
||||
notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
|
||||
notes: |
|
||||
Planning phase complete! Now transition to IDE Development:
|
||||
|
||||
1. ENSURE DOCUMENTS ARE IN PROJECT:
|
||||
- Copy final prd.md to project's docs/prd.md
|
||||
- Copy final architecture.md to project's docs/architecture.md
|
||||
- All documents must be in the project before proceeding
|
||||
|
||||
2. SHARD DOCUMENTS (in IDE):
|
||||
- Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
|
||||
- Option B: Manual: Drag shard-doc task + docs/prd.md into chat
|
||||
- This creates docs/prd/ and docs/architecture/ folders with sharded content
|
||||
|
||||
3. START DEVELOPMENT CYCLE:
|
||||
a. SM Agent (New Chat): @sm → *create
|
||||
- Creates next story from sharded docs
|
||||
- Review and approve story (Draft → Approved)
|
||||
|
||||
b. Dev Agent (New Chat): @dev
|
||||
- Implements approved story
|
||||
- Updates File List with all changes
|
||||
- Marks story as "Review" when complete
|
||||
|
||||
c. QA Agent (New Chat): @qa → review-story
|
||||
- Senior dev review with refactoring ability
|
||||
- Fixes small issues directly
|
||||
- Leaves checklist for remaining items
|
||||
- Updates story status (Review → Done or stays Review)
|
||||
|
||||
d. If QA left unchecked items:
|
||||
- Dev Agent (New Chat): Address remaining items
|
||||
- Return to QA for final approval
|
||||
|
||||
4. REPEAT: Continue cycle for all epic stories
|
||||
|
||||
Reference: data#bmad-kb:IDE Development Workflow
|
||||
|
||||
flow_diagram: |
|
||||
```mermaid
|
||||
|
||||
362
docs/working-in-the-brownfield.md
Normal file
362
docs/working-in-the-brownfield.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# Working in the Brownfield: A Complete Guide
|
||||
|
||||
> 🚀 **HIGHLY RECOMMENDED: Use Gemini Web for Brownfield Documentation!**
|
||||
>
|
||||
> Gemini Web's 1M+ token context window can analyze your ENTIRE codebase at once:
|
||||
>
|
||||
> - Upload via GitHub URL
|
||||
> - Upload up to 1000 files
|
||||
> - Upload zipped project
|
||||
>
|
||||
> This is MUCH more cost-effective than IDE analysis which reads files one by one!
|
||||
|
||||
## What is Brownfield Development?
|
||||
|
||||
Brownfield development refers to adding features, fixing bugs, or modernizing existing software projects. Unlike greenfield (new) projects, brownfield work requires understanding existing code, respecting constraints, and ensuring new changes integrate seamlessly without breaking existing functionality.
|
||||
|
||||
## When to Use BMAD for Brownfield
|
||||
|
||||
BMAD-METHOD excels at brownfield development when you need to:
|
||||
|
||||
- Add significant new features to existing applications
|
||||
- Modernize legacy codebases
|
||||
- Integrate new technologies or services
|
||||
- Refactor complex systems
|
||||
- Fix bugs that require architectural understanding
|
||||
- Document undocumented systems
|
||||
|
||||
## The Complete Brownfield Workflow
|
||||
|
||||
### Choose Your Approach
|
||||
|
||||
#### Approach A: PRD-First (Recommended for Large Codebases/Monorepos)
|
||||
|
||||
**Best for**: Large codebases, monorepos, or when you know exactly what you want to build
|
||||
|
||||
1. **Create PRD First** to define requirements
|
||||
2. **Document only relevant areas** based on PRD needs
|
||||
3. **More efficient** - avoids documenting unused code
|
||||
|
||||
#### Approach B: Document-First (Good for Smaller Projects)
|
||||
|
||||
**Best for**: Smaller codebases, unknown systems, or exploratory changes
|
||||
|
||||
1. **Document entire system** first
|
||||
2. **Create PRD** with full context
|
||||
3. **More thorough** - captures everything
|
||||
|
||||
### Approach A: PRD-First Workflow (Recommended)
|
||||
|
||||
#### Phase 1: Define Requirements First
|
||||
|
||||
**In Gemini Web (with your codebase uploaded):**
|
||||
|
||||
```bash
|
||||
@pm
|
||||
*create-doc brownfield-prd
|
||||
```
|
||||
|
||||
The PM will:
|
||||
|
||||
- **Ask about your enhancement** requirements
|
||||
- **Explore the codebase** to understand current state
|
||||
- **Identify affected areas** that need documentation
|
||||
- **Create focused PRD** with clear scope
|
||||
|
||||
**Key Advantage**: The PRD identifies which parts of your monorepo/large codebase actually need documentation!
|
||||
|
||||
#### Phase 2: Focused Documentation
|
||||
|
||||
**Still in Gemini Web, now with PRD context:**
|
||||
|
||||
```bash
|
||||
@analyst
|
||||
*document-project
|
||||
```
|
||||
|
||||
The analyst will:
|
||||
|
||||
- **Ask about your focus** if no PRD was provided
|
||||
- **Offer options**: Create PRD, provide requirements, or describe the enhancement
|
||||
- **Reference the PRD/description** to understand scope
|
||||
- **Focus on relevant modules** identified in PRD or your description
|
||||
- **Skip unrelated areas** to keep docs lean
|
||||
- **Generate ONE architecture document** for all environments
|
||||
|
||||
The analyst creates:
|
||||
|
||||
- **One comprehensive architecture document** following fullstack-architecture template
|
||||
- **Covers all system aspects** in a single file
|
||||
- **Easy to copy and save** as `docs/project-architecture.md`
|
||||
- **Can be sharded later** in IDE if desired
|
||||
|
||||
For example, if you say "Add payment processing to user service":
|
||||
|
||||
- Documents only: user service, API endpoints, database schemas, payment integrations
|
||||
- Creates focused source tree showing only payment-related code paths
|
||||
- Skips: admin panels, reporting modules, unrelated microservices
|
||||
|
||||
### Approach B: Document-First Workflow
|
||||
|
||||
#### Phase 1: Document the Existing System
|
||||
|
||||
**Best Approach - Gemini Web with 1M+ Context**:
|
||||
|
||||
1. **Go to Gemini Web** (gemini.google.com)
|
||||
2. **Upload your project**:
|
||||
- **Option A**: Paste your GitHub repository URL directly
|
||||
- **Option B**: Upload up to 1000 files from your src/project folder
|
||||
- **Option C**: Zip your project and upload the archive
|
||||
3. **Load the analyst agent**: Upload `dist/agents/analyst.txt`
|
||||
4. **Run documentation**: Type `*document-project`
|
||||
|
||||
The analyst will generate comprehensive documentation of everything.
|
||||
|
||||
#### Phase 2: Plan Your Enhancement
|
||||
|
||||
#### Option A: Full Brownfield Workflow (Recommended for Major Changes)
|
||||
|
||||
**1. Create Brownfield PRD**
|
||||
|
||||
```bash
|
||||
@pm
|
||||
*create-doc brownfield-prd
|
||||
```
|
||||
|
||||
The PM agent will:
|
||||
|
||||
- **Analyze existing documentation** from Phase 1
|
||||
- **Request specific enhancement details** from you
|
||||
- **Assess complexity** and recommend approach
|
||||
- **Create epic/story structure** for the enhancement
|
||||
- **Identify risks and integration points**
|
||||
|
||||
**How PM Agent Gets Project Context**:
|
||||
|
||||
- In Gemini Web: Already has full project context from Phase 1 documentation
|
||||
- In IDE: Will ask "Please provide the path to your existing project documentation"
|
||||
|
||||
**Key Prompts You'll Encounter**:
|
||||
|
||||
- "What specific enhancement or feature do you want to add?"
|
||||
- "Are there any existing systems or APIs this needs to integrate with?"
|
||||
- "What are the critical constraints we must respect?"
|
||||
- "What is your timeline and team size?"
|
||||
|
||||
**2. Create Brownfield Architecture**
|
||||
|
||||
```bash
|
||||
@architect
|
||||
*create-doc brownfield-architecture
|
||||
```
|
||||
|
||||
The architect will:
|
||||
|
||||
- **Review the brownfield PRD**
|
||||
- **Design integration strategy**
|
||||
- **Plan migration approach** if needed
|
||||
- **Identify technical risks**
|
||||
- **Define compatibility requirements**
|
||||
|
||||
#### Option B: Quick Enhancement (For Focused Changes)
|
||||
|
||||
**For Single Epic Without Full PRD**:
|
||||
|
||||
```bash
|
||||
@pm
|
||||
*brownfield-create-epic
|
||||
```
|
||||
|
||||
Use when:
|
||||
|
||||
- Enhancement is well-defined and isolated
|
||||
- Existing documentation is comprehensive
|
||||
- Changes don't impact multiple systems
|
||||
- You need quick turnaround
|
||||
|
||||
**For Single Story**:
|
||||
|
||||
```bash
|
||||
@pm
|
||||
*brownfield-create-story
|
||||
```
|
||||
|
||||
Use when:
|
||||
|
||||
- Bug fix or tiny feature
|
||||
- Very isolated change
|
||||
- No architectural impact
|
||||
- Clear implementation path
|
||||
|
||||
### Phase 3: Validate Planning Artifacts
|
||||
|
||||
```bash
|
||||
@po
|
||||
*execute-checklist po-master-checklist
|
||||
```
|
||||
|
||||
The PO ensures:
|
||||
|
||||
- Compatibility with existing system
|
||||
- No breaking changes planned
|
||||
- Risk mitigation strategies in place
|
||||
- Clear integration approach
|
||||
|
||||
### Phase 4: Transition to Development
|
||||
|
||||
Follow the enhanced IDE Development Workflow:
|
||||
|
||||
1. **Ensure documents are in project**:
|
||||
|
||||
- Copy `docs/prd.md` (or brownfield-prd.md)
|
||||
- Copy `docs/architecture.md` (or brownfield-architecture.md)
|
||||
|
||||
2. **Shard documents**:
|
||||
|
||||
```bash
|
||||
@po
|
||||
# Ask to shard docs/prd.md
|
||||
```
|
||||
|
||||
3. **Development cycle**:
|
||||
- **SM** creates stories with integration awareness
|
||||
- **Dev** implements with existing code respect
|
||||
- **QA** reviews for compatibility and improvements
|
||||
|
||||
## Brownfield Best Practices
|
||||
|
||||
### 1. Always Document First
|
||||
|
||||
Even if you think you know the codebase:
|
||||
|
||||
- Run `document-project` to capture current state
|
||||
- AI agents need this context
|
||||
- Discovers undocumented patterns
|
||||
|
||||
### 2. Respect Existing Patterns
|
||||
|
||||
The brownfield templates specifically look for:
|
||||
|
||||
- Current coding conventions
|
||||
- Existing architectural patterns
|
||||
- Technology constraints
|
||||
- Team preferences
|
||||
|
||||
### 3. Plan for Gradual Rollout
|
||||
|
||||
Brownfield changes should:
|
||||
|
||||
- Support feature flags
|
||||
- Plan rollback strategies
|
||||
- Include migration scripts
|
||||
- Maintain backwards compatibility
|
||||
|
||||
### 4. Test Integration Thoroughly
|
||||
|
||||
Focus testing on:
|
||||
|
||||
- Integration points
|
||||
- Existing functionality (regression)
|
||||
- Performance impact
|
||||
- Data migrations
|
||||
|
||||
### 5. Communicate Changes
|
||||
|
||||
Document:
|
||||
|
||||
- What changed and why
|
||||
- Migration instructions
|
||||
- New patterns introduced
|
||||
- Deprecation notices
|
||||
|
||||
## Common Brownfield Scenarios
|
||||
|
||||
### Scenario 1: Adding a New Feature
|
||||
|
||||
1. Document existing system
|
||||
2. Create brownfield PRD focusing on integration
|
||||
3. Architecture emphasizes compatibility
|
||||
4. Stories include integration tasks
|
||||
|
||||
### Scenario 2: Modernizing Legacy Code
|
||||
|
||||
1. Extensive documentation phase
|
||||
2. PRD includes migration strategy
|
||||
3. Architecture plans gradual transition
|
||||
4. Stories follow strangler fig pattern
|
||||
|
||||
### Scenario 3: Bug Fix in Complex System
|
||||
|
||||
1. Document relevant subsystems
|
||||
2. Use `brownfield-create-story` for focused fix
|
||||
3. Include regression test requirements
|
||||
4. QA validates no side effects
|
||||
|
||||
### Scenario 4: API Integration
|
||||
|
||||
1. Document existing API patterns
|
||||
2. PRD defines integration requirements
|
||||
3. Architecture ensures consistent patterns
|
||||
4. Stories include API documentation updates
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "The AI doesn't understand my codebase"
|
||||
|
||||
**Solution**: Re-run `document-project` with more specific paths to critical files
|
||||
|
||||
### "Generated plans don't fit our patterns"
|
||||
|
||||
**Solution**: Update generated documentation with your specific conventions before planning phase
|
||||
|
||||
### "Too much boilerplate for small changes"
|
||||
|
||||
**Solution**: Use `brownfield-create-story` instead of full workflow
|
||||
|
||||
### "Integration points unclear"
|
||||
|
||||
**Solution**: Provide more context during PRD creation, specifically highlighting integration systems
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Brownfield-Specific Commands
|
||||
|
||||
```bash
|
||||
# Document existing project
|
||||
@analyst → *document-project
|
||||
|
||||
# Create enhancement PRD
|
||||
@pm → *create-doc brownfield-prd
|
||||
|
||||
# Create architecture with integration focus
|
||||
@architect → *create-doc brownfield-architecture
|
||||
|
||||
# Quick epic creation
|
||||
@pm → *brownfield-create-epic
|
||||
|
||||
# Single story creation
|
||||
@pm → *brownfield-create-story
|
||||
```
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```text
|
||||
Do you have a large codebase or monorepo?
|
||||
├─ Yes → PRD-First Approach
|
||||
│ └─ Create PRD → Document only affected areas
|
||||
└─ No → Is the codebase well-known to you?
|
||||
├─ Yes → PRD-First Approach
|
||||
└─ No → Document-First Approach
|
||||
|
||||
Is this a major enhancement affecting multiple systems?
|
||||
├─ Yes → Full Brownfield Workflow
|
||||
└─ No → Is this more than a simple bug fix?
|
||||
├─ Yes → brownfield-create-epic
|
||||
└─ No → brownfield-create-story
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
Brownfield development with BMAD-METHOD provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
|
||||
|
||||
Remember: **Document First, Plan Carefully, Integrate Safely**
|
||||
Reference in New Issue
Block a user