docs: Add missing getting-started-guide.md referenced in enhancements.md
- Complete user-friendly guide with step-by-step workflows - Agent selection guide with optimization settings - Advanced techniques and troubleshooting - Practical examples for all enhanced features - Fixes broken link in enhancements.md line 133
This commit is contained in:
James (Claude Code)
parent
ff6d3bf3aa
commit
5d6086e012
|
|
@ -0,0 +1,339 @@
|
|||
# 🚀 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**
|
||||
```bash
|
||||
*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**
|
||||
```bash
|
||||
*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:
|
||||
|
||||
```bash
|
||||
*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)
|
||||
```bash
|
||||
*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)
|
||||
```bash
|
||||
*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
|
||||
```bash
|
||||
*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](enhancements.md)** - Complete feature reference
|
||||
- **[README.md](README.md)** - Full BMAD Method documentation
|
||||
- **[workspace-utils/docs/](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.*
|
||||
Loading…
Reference in New Issue