From 5d6086e01280dd3203d7c5ea77bd1828c989e374 Mon Sep 17 00:00:00 2001 From: "James (Claude Code)" Date: Wed, 23 Jul 2025 20:50:39 -0400 Subject: [PATCH] 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 --- getting-started-guide.md | 339 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 339 insertions(+) create mode 100644 getting-started-guide.md diff --git a/getting-started-guide.md b/getting-started-guide.md new file mode 100644 index 00000000..036fdb67 --- /dev/null +++ b/getting-started-guide.md @@ -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.* \ No newline at end of file