3af3d33d4a
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.
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# BMAD Method Guiding Principles
|
|
|
|
The BMAD Method is a natural language framework for AI-assisted software development. These principles ensure contributions maintain the method's effectiveness.
|
|
|
|
## Core Principles
|
|
|
|
### 1. Dev Agents Must Be Lean
|
|
|
|
- **Minimize dev agent dependencies**: Development agents that work in IDEs must have minimal context overhead
|
|
- **Save context for code**: Every line counts - dev agents should focus on coding, not documentation
|
|
- **Web agents can be larger**: Planning agents (PRD Writer, Architect) used in web UI can have more complex tasks and dependencies
|
|
- **Small files, loaded on demand**: Multiple small, focused files are better than large files with many branches
|
|
|
|
### 2. Natural Language First
|
|
|
|
- **Everything is markdown**: Agents, tasks, templates - all written in plain English
|
|
- **No code in core**: The framework itself contains no programming code, only natural language instructions
|
|
- **Self-contained templates**: Templates include their own generation instructions using `[[LLM: ...]]` markup
|
|
|
|
### 3. Agent and Task Design
|
|
|
|
- **Agents define roles**: Each agent is a persona with specific expertise (e.g., Frontend Developer, API Developer)
|
|
- **Tasks are procedures**: Step-by-step instructions an agent follows to complete work
|
|
- **Templates are outputs**: Structured documents with embedded instructions for generation
|
|
- **Dependencies matter**: Explicitly declare only what's needed
|
|
|
|
## Practical Guidelines
|
|
|
|
### When to Add to Core
|
|
|
|
- Universal software development needs only
|
|
- Doesn't bloat dev agent contexts
|
|
- Follows existing agent/task/template patterns
|
|
|
|
### When to Create Expansion Packs
|
|
|
|
- Domain-specific needs beyond software development
|
|
- Non-technical domains (business, wellness, education, creative)
|
|
- Specialized technical domains (games, infrastructure, mobile)
|
|
- Heavy documentation or knowledge bases
|
|
- Anything that would bloat core agents
|
|
|
|
See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples and ideas.
|
|
|
|
### Agent Design Rules
|
|
|
|
1. **Web/Planning Agents**: Can have richer context, multiple tasks, extensive templates
|
|
2. **Dev Agents**: Minimal dependencies, focused on code generation, lean task sets
|
|
3. **All Agents**: Clear persona, specific expertise, well-defined capabilities
|
|
|
|
### Task Writing Rules
|
|
|
|
1. Write clear step-by-step procedures
|
|
2. Use markdown formatting for readability
|
|
3. Keep dev agent tasks focused and concise
|
|
4. Planning tasks can be more elaborate
|
|
5. **Prefer multiple small tasks over one large branching task**
|
|
- Instead of one task with many conditional paths
|
|
- Create multiple focused tasks the agent can choose from
|
|
- This keeps context overhead minimal
|
|
6. **Reuse common tasks** - Don't create new document creation tasks
|
|
- Use the existing `create-doc` task
|
|
- Pass the appropriate template with embedded LLM instructions
|
|
- This maintains consistency and reduces duplication
|
|
|
|
### Template Rules
|
|
|
|
1. Include generation instructions with `[[LLM: ...]]` markup
|
|
2. Provide clear structure for output
|
|
3. Make templates reusable across agents
|
|
4. Use standardized markup elements:
|
|
- `{{placeholders}}` for variables to be replaced
|
|
- `[[LLM: instructions]]` for AI-only processing (never shown to users)
|
|
- `REPEAT` sections for repeatable content blocks
|
|
- `^^CONDITION^^` blocks for conditional content
|
|
- `@{examples}` for guidance examples (never output to users)
|
|
5. NEVER display template markup or LLM instructions to users
|
|
6. Focus on clean output - all processing instructions stay internal
|
|
|
|
## Remember
|
|
|
|
- The power is in natural language orchestration, not code
|
|
- Dev agents code, planning agents plan
|
|
- Keep dev agents lean for maximum coding efficiency
|
|
- Expansion packs handle specialized domains
|