ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: enhance QA agent as senior developer with code review capabilities and major brownfield improvements

Browse Source 
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
2025-06-24 23:56:57 -05:00
parent fb0be544ad
commit 3af3d33d4a
29 changed files with 4091 additions and 658 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
dist/agents/analyst.txt vendored
View File

@@ -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 ====================