BMAD-METHOD/getting-started-guide.md

🚀 BMAD Quality Framework Enhancement Guide

Master all enhanced features with step-by-step workflows, agent selection guide, and advanced techniques.

---

🎯 Quick Start Overview

The BMAD Quality Framework transforms basic AI agent orchestration into enterprise-grade quality engineering. This guide provides practical examples and workflows to get you productive immediately.

---

📋 Step-by-Step Workflows

🔄 Core Development Cycle

1. Start Your Story Development

*develop-story

What happens:

• Systematic story implementation with dual-track progress
• Automatic story file checkbox updates [x]
• Real-time File List maintenance
• TodoWrite tool integration for transparency

Example Output:

✅ Task 1: Create user authentication component [x]
✅ Task 2: Add login validation logic [x] 
⏳ Task 3: Implement session management [ ]

📁 Files Modified:
- src/components/AuthComponent.tsx (new)
- src/utils/validation.ts (modified)
- src/types/auth.ts (new)

2. Validate Your Work Quality

*reality-audit

What happens:

• 10-phase comprehensive quality audit
• Automatic A-F grading with composite scoring
• Zero-touch remediation execution
• Automatic options presentation

Example Output:

🔍 Reality Audit Results: Grade B (Score: 82/100)

📊 Breakdown:
- Reality Score: 88/100 (35.2 points)
- Regression Prevention: 78/100 (27.3 points) 
- Technical Debt: 80/100 (20.0 points)

✅ Automatic Actions Taken:
- Generated remediation story for TypeScript strict mode
- Split oversized authentication story into 3 focused stories
- Updated architectural compliance documentation

📋 Your Options:
A. [5 min] Fix TypeScript issues and re-audit → Grade A eligible
B. [15 min] Refactor for better pattern compliance → Comprehensive improvement
C. [2 min] Proceed with current quality → Acceptable for development

3. Handle Issues Automatically

When quality issues are detected:

🤖 Automatic Remediation (Zero Commands Required):

• Quality issues → Remediation stories generated automatically
• Oversized stories → Auto-split into manageable pieces
• Mixed concerns → Surgical fix stories created immediately

Example:

🤖 AUTO-REMEDIATION EXECUTED:

Issue Detected: Authentication story contains 12 tasks (>8 limit)
📋 Auto-Generated Stories:
1. "Auth-Core: Login/logout functionality" (4 tasks)
2. "Auth-Validation: Input validation and error handling" (3 tasks)  
3. "Auth-Session: Session management and persistence" (5 tasks)

✅ Original story updated with cross-references
✅ New stories added to backlog with proper context
✅ No manual commands required - ready to continue development

🆘 When You Get Stuck

Loop Detection & External Collaboration

After 3 failed attempts on the same issue:

*escalate

What happens:

• Automatic generation of collaboration prompts
• Copy-paste ready for external LLMs (Gemini, GPT-4, Claude)
• Context preservation for seamless handoffs

Example Output:

🔄 LOOP DETECTED: 3 failed attempts on TypeScript integration

🤝 COLLABORATION PROMPT GENERATED:
Copy this to Gemini/GPT-4/Claude for additional perspective:

---
COLLABORATION REQUEST: TypeScript Integration Challenge

CONTEXT: Working on authentication system integration with strict TypeScript requirements.

FAILED ATTEMPTS:
1. Generic type definitions - caused circular dependencies
2. Interface-based approach - broke existing validation logic  
3. Utility type solution - increased complexity without solving core issue

SPECIFIC CHALLENGE: Need to integrate new auth types with existing validation system without breaking current implementations or introducing circular dependencies.

CONSTRAINTS:
- Must maintain backward compatibility
- Cannot modify existing validation interfaces
- TypeScript strict mode required

QUESTION: What alternative TypeScript patterns could solve this integration challenge while maintaining clean architecture?
---

💡 This prompt contains all necessary context for effective collaboration.

---

🎛️ Agent Selection Guide

👨‍💻 Development Agents

James (Developer Agent)

When to use: Implementation, debugging, code reviews Optimized for: Precision and technical accuracy (temp=0.4)

*develop-story    # Systematic implementation
*reality-audit    # Quality validation  
*build-context    # Pre-fix investigation
*escalate        # When stuck after 3 attempts

Best for:

• Feature implementation
• Bug fixing with context analysis
• Code quality improvements
• Technical debt resolution

Quinn (QA Agent)

When to use: Quality validation, testing, compliance Optimized for: Systematic analysis (temp=0.3)

*reality-audit        # Manual quality audit
*audit-validation     # Auto-remediation audit
*create-remediation   # Generate fix stories
*story-code-audit     # Cross-reference implementation

Best for:

• Quality gate enforcement
• Regression testing validation
• Compliance checking
• Remediation story generation

🎨 Creative & Strategic Agents

Business Analyst

When to use: Requirements analysis, stakeholder needs Optimized for: Creative ideation (temp=0.8)

Best for:

• Requirements gathering
• Stakeholder interview analysis
• Business process optimization
• User story refinement

Architect

When to use: System design, technical decisions Optimized for: Balanced creativity (temp=0.6)

Best for:

• System architecture design
• Technology stack decisions
• Integration planning
• Technical roadmap creation

UX Expert

When to use: User interface design, experience optimization Optimized for: High creativity (temp=0.75)

Best for:

• Interface design
• User experience flows
• Accessibility compliance
• Design system creation

---

🚀 Advanced Techniques

🎯 Quality Score Optimization

Understanding Composite Scoring:

• Reality Score (40%): Actual vs simulated implementation
• Regression Prevention (35%): Consistency with existing patterns
• Technical Debt (25%): Long-term maintainability

Pro Tips for Grade A (90-100):

1. Perfect Reality Score:

   • No mock implementations
   • Full functional code
   • Comprehensive integration testing

2. Excellent Regression Prevention:

   • Follow existing architectural patterns
   • Maintain API consistency
   • Comprehensive backward compatibility

3. Minimal Technical Debt:

   • Clear, self-documenting code
   • Proper error handling
   • Scalable design patterns

🔧 Workspace Collaboration Features

Cross-IDE Session Management

*workspace-init      # Initialize collaborative session
*workspace-status    # Check collaboration context
*workspace-handoff   # Context-aware agent transitions
*workspace-cleanup   # Automated maintenance
*workspace-sync      # Synchronize context

IDE-Optimized Commands

Auto-detected environments:

• Cursor, Claude Code, Windsurf, Trae, Roo, Cline, Gemini, GitHub Copilot

What happens automatically:

• Uses IDE-native tools instead of bash commands
• Eliminates approval prompts
• Batches CLI operations when needed
• Leverages integrated panels and runners

📊 Token Efficiency Strategies

Smart Resource Management:

• 78-86% token reduction through intelligent routing
• Lightweight operations for routine tasks (300-800 tokens vs 2,000-5,000)
• Session-based caching eliminates repeated analysis

Optimization Techniques:

1. Use targeted commands: *reality-audit vs generic analysis
2. Leverage caching: Repeated operations use cached results
3. Context-aware execution: Complexity matched to task requirements
4. Pattern reuse: Proven approaches over custom solutions

---

🛠️ Troubleshooting Common Scenarios

📋 "What should I do next?"

Solution: Automatic options presentation after every audit

📋 Your Options:
A. [5 min] Quick fix for immediate progress
B. [15 min] Comprehensive improvement  
C. [2 min] Proceed with current state

🔄 "Stuck in debugging loop"

Solution: Automatic escalation after 3 failed attempts

• Copy-paste prompts generated automatically
• External LLM collaboration ready
• Context preservation maintained

📈 "Low quality scores"

Solution: Automatic remediation execution

• Issues detected → Fix stories generated automatically
• No manual command requirements
• Zero-touch resolution process

🗂️ "Story getting too complex"

Solution: Automatic story splitting

• Oversized stories (>8 tasks) split automatically
• Surgical focus stories created
• Cross-references maintained

---

🎯 Success Patterns

✅ Effective Development Flow:

1. *develop-story → Systematic implementation
2. *reality-audit → Quality validation
3. Automatic remediation → Zero manual fixes
4. Grade A achievement → Auto-push eligible

✅ Quality-First Approach:

• Never accept simulation patterns
• Always validate against existing patterns
• Leverage automatic remediation
• Trust the composite scoring system

✅ Collaborative Problem-Solving:

• Let loop detection trigger external collaboration
• Use workspace handoffs for complex scenarios
• Leverage IDE-specific optimizations
• Maintain context across sessions

---

🎉 Next Steps

🚀 Ready to Transform Your Workflow?

1. Start with a simple story: *develop-story
2. Experience automatic quality validation: *reality-audit
3. See zero-touch remediation in action
4. Leverage collaborative features when needed

📚 Additional Resources:

• enhancements.md - Complete feature reference
• README.md - Full BMAD Method documentation
• workspace-utils/docs/ - Cross-IDE setup guides

---

🎯 Transform from basic agent orchestration to enterprise-grade quality engineering. Every feature designed for systematic accountability, automated workflows, and collaborative intelligence.