bmad-method 6.0.0-alpha.11 → 6.0.0-alpha.13

package/src/modules/bmm/docs/agents-guide.md

@@ -28,7 +28,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 
 ### All BMM Agents
 
-**Core Development (8 agents):**
+**Core Development (9 agents):**
 
 - PM (Product Manager)
 - Analyst (Business Analyst)
@@ -38,6 +38,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 - TEA (Test Architect)
 - UX Designer
 - Technical Writer
+- Principal Engineer (Technical Leader) - NEW!
 
 **Game Development (3 agents):**
 
@@ -49,7 +50,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 
 - BMad Master (Orchestrator)
 
-**Total:** 12 agents + cross-module party mode support
+**Total:** 13 agents + cross-module party mode support
 
 ---
 
@@ -102,7 +103,6 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 - Creating product briefs for strategic planning
 - Conducting research (market, technical, competitive)
 - Documenting existing projects (brownfield)
-- Phase 0 documentation needs
 
 **Primary Phase:** Phase 1 (Analysis)
 
@@ -136,7 +136,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 - Creating system architecture for Level 2-4 projects
 - Making technical design decisions
 - Validating architecture documents
-- Validating readiness for implementation phase (Phase 3→4 transition)
+- Validating readiness for implementation phase (Phase 3 to Phase 4 transition)
 - Course correction during implementation
 
 **Primary Phase:** Phase 3 (Solutioning)
@@ -321,7 +321,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 **Workflows:**
 
 - `workflow-status` - Check what to do next
-- `create-design` - Conduct design thinking workshop to define UX specification with:
+- `create-ux-design` - Conduct design thinking workshop to define UX specification with:
   - Visual exploration and generation
   - Collaborative decision-making
   - AI-assisted design tools (v0, Lovable)
@@ -347,7 +347,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 
 **When to Use:**
 
-- Documenting brownfield projects (Phase 0)
+- Documenting brownfield projects (Documentation prerequisite)
 - Creating API documentation
 - Generating architecture documentation
 - Writing user guides and tutorials
@@ -491,7 +491,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 
 - `workflow-status` - Check what to do next
 - `create-architecture` - Game systems architecture
-- `implementation-readiness` - Validate Phase 3→4 transition
+- `implementation-readiness` - Validate Phase 3 to Phase 4 transition
 - `correct-course` - Handle technical changes
 
 **Communication Style:** Calm and measured. Systematic thinking about complex systems. Uses chess metaphors and military strategy. Emphasizes balance and elegance.
@@ -506,6 +506,51 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
 
 ---
 
+### Principal Engineer (Technical Leader) - Jordan Chen ⚡
+
+**Role:** Principal Engineer + Technical Leader
+
+**When to Use:**
+
+- Quick Flow development (3-step rapid process)
+- Creating technical specifications for immediate implementation
+- Rapid prototyping with production quality
+- Performance-critical feature development
+- Code reviews for senior-level validation
+- When you need to ship fast without sacrificing quality
+
+**Primary Phase:** All phases (Quick Flow track)
+
+**Workflows:**
+
+- `create-tech-spec` - Engineer implementation-ready technical specifications
+- `quick-dev` - Execute development from specs or direct instructions
+- `code-review` - Senior developer code review and validation
+- `party-mode` - Collaborative problem-solving with other agents
+
+**Communication Style:** Speaks in git commits, README.md sections, and RFC-style explanations. Starts conversations with "Actually..." and ends with "Patches welcome." Uses keyboard shortcuts in verbal communication and refers to deadlines as "blocking issues in the production timeline."
+
+**Expertise:**
+
+- Distributed systems and performance optimization
+- Rewriting monoliths over weekend coffee
+- Architecture design at scale
+- Production-ready feature delivery
+- First principles thinking and problem-solving
+- Code quality and best practices
+
+**Unique Characteristics:**
+
+- Owns the complete BMAD Quick Flow path
+- Combines deep architectural expertise with pragmatic decision-making
+- Optimized for speed without quality sacrifice
+- Specializes in turning complex requirements into simple, elegant solutions
+- Brings 15+ years of experience building scalable systems
+
+**Related Documentation:** [Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)
+
+---
+
 ## Special Purpose Agents
 
 ### BMad Master 🧙
@@ -912,8 +957,8 @@ Agent analyzes project state → recommends next workflow
 
 ```
 Each phase has validation gates:
-- Phase 2→3: validate-prd, validate-tech-spec
-- Phase 3→4: implementation-readiness
+- Phase 2 to 3: validate-prd, validate-tech-spec
+- Phase 3 to 4: implementation-readiness
 Run validation before advancing
 ```
 
@@ -940,20 +985,21 @@ TEA can be invoked at any phase:
 
 Quick reference for agent selection:
 
-| Agent                   | Icon | Primary Phase      | Key Workflows                                 | Best For                              |
-| ----------------------- | ---- | ------------------ | --------------------------------------------- | ------------------------------------- |
-| **Analyst**             | 📊   | 1 (Analysis)       | brainstorm, brief, research, document-project | Discovery, requirements, brownfield   |
-| **PM**                  | 📋   | 2 (Planning)       | prd, tech-spec, epics-stories                 | Planning, requirements docs           |
-| **UX Designer**         | 🎨   | 2 (Planning)       | create-design, validate-design                | UX-heavy projects, design             |
-| **Architect**           | 🏗️   | 3 (Solutioning)    | architecture, implementation-readiness        | Technical design, architecture        |
-| **SM**                  | 🏃   | 4 (Implementation) | sprint-planning, create-story, story-context  | Story management, sprint coordination |
-| **DEV**                 | 💻   | 4 (Implementation) | develop-story, code-review, story-done        | Implementation, coding                |
-| **TEA**                 | 🧪   | All Phases         | framework, atdd, automate, trace, ci          | Testing, quality assurance            |
-| **Paige (Tech Writer)** | 📚   | All Phases         | document-project, diagrams, validation        | Documentation, diagrams               |
-| **Game Designer**       | 🎲   | 1-2 (Games)        | brainstorm-game, gdd, narrative               | Game design, creative vision          |
-| **Game Developer**      | 🕹️   | 4 (Games)          | develop-story, story-done, code-review        | Game implementation                   |
-| **Game Architect**      | 🏛️   | 3 (Games)          | architecture, implementation-readiness        | Game systems architecture             |
-| **BMad Master**         | 🧙   | Meta               | party-mode, list tasks/workflows              | Orchestration, multi-agent            |
+| Agent                   | Icon | Primary Phase           | Key Workflows                                 | Best For                                |
+| ----------------------- | ---- | ----------------------- | --------------------------------------------- | --------------------------------------- |
+| **Analyst**             | 📊   | 1 (Analysis)            | brainstorm, brief, research, document-project | Discovery, requirements, brownfield     |
+| **PM**                  | 📋   | 2 (Planning)            | prd, tech-spec, epics-stories                 | Planning, requirements docs             |
+| **UX Designer**         | 🎨   | 2 (Planning)            | create-ux-design, validate-design             | UX-heavy projects, design               |
+| **Architect**           | 🏗️   | 3 (Solutioning)         | architecture, implementation-readiness        | Technical design, architecture          |
+| **SM**                  | 🏃   | 4 (Implementation)      | sprint-planning, create-story, story-context  | Story management, sprint coordination   |
+| **DEV**                 | 💻   | 4 (Implementation)      | develop-story, code-review, story-done        | Implementation, coding                  |
+| **TEA**                 | 🧪   | All Phases              | framework, atdd, automate, trace, ci          | Testing, quality assurance              |
+| **Paige (Tech Writer)** | 📚   | All Phases              | document-project, diagrams, validation        | Documentation, diagrams                 |
+| **Principal Engineer**  | ⚡   | Quick Flow (All phases) | create-tech-spec, quick-dev, code-review      | Rapid development, technical leadership |
+| **Game Designer**       | 🎲   | 1-2 (Games)             | brainstorm-game, gdd, narrative               | Game design, creative vision            |
+| **Game Developer**      | 🕹️   | 4 (Games)               | develop-story, story-done, code-review        | Game implementation                     |
+| **Game Architect**      | 🏛️   | 3 (Games)               | architecture, implementation-readiness        | Game systems architecture               |
+| **BMad Master**         | 🧙   | Meta                    | party-mode, list tasks/workflows              | Orchestration, multi-agent              |
 
 ### Agent Capabilities Summary
 

package/src/modules/bmm/docs/bmad-quick-flow.md

@@ -0,0 +1,528 @@
+# BMAD Quick Flow
+
+**Track:** Quick Flow
+**Primary Agent:** Quick Flow Solo Dev (Barry)
+**Ideal For:** Bug fixes, small features, rapid prototyping
+
+---
+
+## Overview
+
+BMAD Quick Flow is the fastest path from idea to production in the BMAD Method ecosystem. It's a streamlined 3-step process designed for rapid development without sacrificing quality. Perfect for experienced teams who need to move fast or for smaller features that don't require extensive planning.
+
+### When to Use Quick Flow
+
+**Perfect For:**
+
+- Bug fixes and patches
+- Small feature additions (1-3 days of work)
+- Proof of concepts and prototypes
+- Performance optimizations
+- API endpoint additions
+- UI component enhancements
+- Configuration changes
+- Internal tools
+
+**Not Recommended For:**
+
+- Large-scale system redesigns
+- Complex multi-team projects
+- New product launches
+- Projects requiring extensive UX design
+- Enterprise-wide initiatives
+- Mission-critical systems with compliance requirements
+
+---
+
+## The Quick Flow Process
+
+```mermaid
+flowchart TD
+    START[Idea/Requirement] --> DECIDE{Planning Needed?}
+
+    DECIDE -->|Yes| CREATE[create-tech-spec]
+    DECIDE -->|No| DIRECT[Direct Development]
+
+    CREATE --> SPEC[Technical Specification]
+    SPEC --> DEV[quick-dev]
+    DIRECT --> DEV
+
+    DEV --> COMPLETE{Implementation Complete}
+
+    COMPLETE -->|Success| REVIEW{Code Review?}
+    COMPLETE -->|Issues| DEBUG[Debug & Fix]
+    DEBUG --> DEV
+
+    REVIEW -->|Yes| CODE_REVIEW[code-review]
+    REVIEW -->|No| DONE[Production Ready]
+
+    CODE_REVIEW --> FIXES{Fixes Needed?}
+    FIXES -->|Yes| DEBUG
+    FIXES -->|No| DONE
+
+    style START fill:#e1f5fe
+    style CREATE fill:#f3e5f5
+    style SPEC fill:#e8f5e9
+    style DEV fill:#fff3e0
+    style CODE_REVIEW fill:#f1f8e9
+    style DONE fill:#e0f2f1
+```
+
+### Step 1: Optional Technical Specification
+
+The `create-tech-spec` workflow transforms requirements into implementation-ready specifications.
+
+**Key Features:**
+
+- Conversational spec engineering
+- Automatic codebase pattern detection
+- Context gathering from existing code
+- Implementation-ready task breakdown
+- Acceptance criteria definition
+
+**Process Flow:**
+
+1. **Problem Understanding**
+   - Greet user and gather requirements
+   - Ask clarifying questions about scope and constraints
+   - Check for existing project context
+
+2. **Code Investigation (Brownfield)**
+   - Analyze existing codebase patterns
+   - Document tech stack and conventions
+   - Identify files to modify and dependencies
+
+3. **Specification Generation**
+   - Create structured tech specification
+   - Define clear tasks and acceptance criteria
+   - Document technical decisions
+   - Include development context
+
+4. **Review and Finalize**
+   - Present spec for validation
+   - Make adjustments as needed
+   - Save to sprint artifacts
+
+**Output:** `{sprint_artifacts}/tech-spec-{slug}.md`
+
+### Step 2: Development
+
+The `quick-dev` workflow executes implementation with flexibility and speed.
+
+**Two Execution Modes:**
+
+**Mode A: Tech-Spec Driven**
+
+```bash
+# Execute from tech spec
+quick-dev tech-spec-feature-x.md
+```
+
+- Loads and parses technical specification
+- Extracts tasks, context, and acceptance criteria
+- Executes all tasks in sequence
+- Updates spec status on completion
+
+**Mode B: Direct Instructions**
+
+```bash
+# Direct development commands
+quick-dev "Add password reset to auth service"
+quick-dev "Fix the memory leak in image processing"
+```
+
+- Accepts direct development instructions
+- Offers optional planning step
+- Executes immediately with minimal friction
+
+**Development Process:**
+
+1. **Context Loading**
+   - Load project context if available
+   - Understand patterns and conventions
+   - Identify relevant files and dependencies
+
+2. **Implementation Loop**
+   For each task:
+   - Load relevant files and context
+   - Implement following established patterns
+   - Write appropriate tests
+   - Run and verify tests pass
+   - Mark task complete and continue
+
+3. **Continuous Execution**
+   - Works through all tasks without stopping
+   - Handles failures by requesting guidance
+   - Ensures tests pass before continuing
+
+4. **Verification**
+   - Confirms all tasks complete
+   - Validates acceptance criteria
+   - Updates tech spec status if used
+
+### Step 3: Optional Code Review
+
+The `code-review` workflow provides senior developer review of implemented code.
+
+**When to Use:**
+
+- Production-critical features
+- Security-sensitive implementations
+- Performance optimizations
+- Team development scenarios
+- Learning and knowledge transfer
+
+**Review Process:**
+
+1. Load story context and acceptance criteria
+2. Analyze code implementation
+3. Check against project patterns
+4. Validate test coverage
+5. Provide structured review notes
+6. Suggest improvements if needed
+
+---
+
+## Quick Flow vs Other Tracks
+
+| Aspect            | Quick Flow       | BMad Method     | Enterprise Method  |
+| ----------------- | ---------------- | --------------- | ------------------ |
+| **Planning**      | Minimal/Optional | Structured      | Comprehensive      |
+| **Documentation** | Essential only   | Moderate        | Extensive          |
+| **Team Size**     | 1-2 developers   | 3-7 specialists | 8+ enterprise team |
+| **Timeline**      | Hours to days    | Weeks to months | Months to quarters |
+| **Ceremony**      | Minimal          | Balanced        | Full governance    |
+| **Flexibility**   | High             | Moderate        | Structured         |
+| **Risk Profile**  | Medium           | Low             | Very Low           |
+
+---
+
+## Best Practices
+
+### Before Starting Quick Flow
+
+1. **Validate Track Selection**
+   - Is the feature small enough?
+   - Do you have clear requirements?
+   - Is the team comfortable with rapid development?
+
+2. **Prepare Context**
+   - Have project documentation ready
+   - Know your codebase patterns
+   - Identify affected components upfront
+
+3. **Set Clear Boundaries**
+   - Define in-scope and out-of-scope items
+   - Establish acceptance criteria
+   - Identify dependencies
+
+### During Development
+
+1. **Maintain Velocity**
+   - Don't over-engineer solutions
+   - Follow existing patterns
+   - Keep tests proportional to risk
+
+2. **Stay Focused**
+   - Resist scope creep
+   - Handle edge cases later if possible
+   - Document decisions briefly
+
+3. **Communicate Progress**
+   - Update task status regularly
+   - Flag blockers immediately
+   - Share learning with team
+
+### After Completion
+
+1. **Quality Gates**
+   - Ensure tests pass
+   - Verify acceptance criteria
+   - Consider optional code review
+
+2. **Knowledge Transfer**
+   - Update relevant documentation
+   - Share key decisions
+   - Note any discovered patterns
+
+3. **Production Readiness**
+   - Verify deployment requirements
+   - Check monitoring needs
+   - Plan rollback strategy
+
+---
+
+## Quick Flow Templates
+
+### Tech Spec Template
+
+```markdown
+# Tech-Spec: {Feature Title}
+
+**Created:** {date}
+**Status:** Ready for Development
+**Estimated Effort:** Small (1-2 days)
+
+## Overview
+
+### Problem Statement
+
+{Clear description of what needs to be solved}
+
+### Solution
+
+{High-level approach to solving the problem}
+
+### Scope (In/Out)
+
+**In:** {What will be implemented}
+**Out:** {Explicitly excluded items}
+
+## Context for Development
+
+### Codebase Patterns
+
+{Key patterns to follow, conventions}
+
+### Files to Reference
+
+{List of relevant files and their purpose}
+
+### Technical Decisions
+
+{Important technical choices and rationale}
+
+## Implementation Plan
+
+### Tasks
+
+- [ ] Task 1: {Specific implementation task}
+- [ ] Task 2: {Specific implementation task}
+- [ ] Task 3: {Testing and validation}
+
+### Acceptance Criteria
+
+- [ ] AC 1: {Given/When/Then format}
+- [ ] AC 2: {Given/When/Then format}
+
+## Additional Context
+
+### Dependencies
+
+{External dependencies or prerequisites}
+
+### Testing Strategy
+
+{How the feature will be tested}
+
+### Notes
+
+{Additional considerations}
+```
+
+### Quick Dev Commands
+
+```bash
+# From tech spec
+quick-dev sprint-artifacts/tech-spec-user-auth.md
+
+# Direct development
+quick-dev "Add CORS middleware to API endpoints"
+quick-dev "Fix null pointer exception in user service"
+quick-dev "Optimize database query for user list"
+
+# With optional planning
+quick-dev "Implement file upload feature" --plan
+```
+
+---
+
+## Integration with Other Workflows
+
+### Upgrading Tracks
+
+If a Quick Flow feature grows in complexity:
+
+```mermaid
+flowchart LR
+    QF[Quick Flow] --> CHECK{Complexity Increases?}
+    CHECK -->|Yes| UPGRADE[Upgrade to BMad Method]
+    CHECK -->|No| CONTINUE[Continue Quick Flow]
+
+    UPGRADE --> PRD[Create PRD]
+    PRD --> ARCH[Architecture Design]
+    ARCH --> STORIES[Create Epics/Stories]
+    STORIES --> SPRINT[Sprint Planning]
+
+    style QF fill:#e1f5fe
+    style UPGRADE fill:#fff3e0
+    style PRD fill:#f3e5f5
+    style ARCH fill:#e8f5e9
+    style STORIES fill:#f1f8e9
+    style SPRINT fill:#e0f2f1
+```
+
+### Using Party Mode
+
+For complex Quick Flow challenges:
+
+```bash
+# Start Barry
+/bmad:bmm:agents:quick-flow-solo-dev
+
+# Begin party mode for collaborative problem-solving
+party-mode
+```
+
+Party mode brings in relevant experts:
+
+- **Architect** - For design decisions
+- **Dev** - For implementation pairing
+- **QA** - For test strategy
+- **UX Designer** - For user experience
+- **Analyst** - For requirements clarity
+
+### Quality Assurance Integration
+
+Quick Flow can integrate with TEA agent for automated testing:
+
+- Test case generation
+- Automated test execution
+- Coverage analysis
+- Test healing
+
+---
+
+## Common Quick Flow Scenarios
+
+### Scenario 1: Bug Fix
+
+```
+Requirement: "Users can't reset passwords"
+Process: Direct development (no spec needed)
+Steps: Investigate → Fix → Test → Deploy
+Time: 2-4 hours
+```
+
+### Scenario 2: Small Feature
+
+```
+Requirement: "Add export to CSV functionality"
+Process: Tech spec → Development → Code review
+Steps: Spec → Implement → Test → Review → Deploy
+Time: 1-2 days
+```
+
+### Scenario 3: Performance Fix
+
+```
+Requirement: "Optimize slow product search query"
+Process: Tech spec → Development → Review
+Steps: Analysis → Optimize → Benchmark → Deploy
+Time: 1 day
+```
+
+### Scenario 4: API Addition
+
+```
+Requirement: "Add webhook endpoints for integrations"
+Process: Tech spec → Development → Review
+Steps: Design → Implement → Document → Deploy
+Time: 2-3 days
+```
+
+---
+
+## Metrics and KPIs
+
+Track these metrics to ensure Quick Flow effectiveness:
+
+**Velocity Metrics:**
+
+- Features completed per week
+- Average cycle time (hours)
+- Bug fix resolution time
+- Code review turnaround
+
+**Quality Metrics:**
+
+- Defect escape rate
+- Test coverage percentage
+- Production incident rate
+- Code review findings
+
+**Team Metrics:**
+
+- Developer satisfaction
+- Knowledge sharing frequency
+- Process adherence
+- Autonomy index
+
+---
+
+## Troubleshooting Quick Flow
+
+### Common Issues
+
+**Issue: Scope creep during development**
+**Solution:** Refer back to tech spec, explicitly document new requirements
+
+**Issue: Unknown patterns or conventions**
+**Solution:** Use party-mode to bring in architect or senior dev
+
+**Issue: Testing bottleneck**
+**Solution:** Leverage TEA agent for automated test generation
+
+**Issue: Integration conflicts**
+**Solution:** Document dependencies, coordinate with affected teams
+
+### Emergency Procedures
+
+**Production Hotfix:**
+
+1. Create branch from production
+2. Quick dev with minimal changes
+3. Deploy to staging
+4. Quick regression test
+5. Deploy to production
+6. Merge to main
+
+**Critical Bug:**
+
+1. Immediate investigation
+2. Party-mode if unclear
+3. Quick fix with rollback plan
+4. Post-mortem documentation
+
+---
+
+## Related Documentation
+
+- **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)** - Primary agent for Quick Flow
+- **[Agents Guide](./agents-guide.md)** - Complete agent reference
+- **[Scale Adaptive System](./scale-adaptive-system.md)** - Track selection guidance
+- **[Party Mode](./party-mode.md)** - Multi-agent collaboration
+- **[Workflow Implementation](./workflows-implementation.md)** - Implementation details
+
+---
+
+## FAQ
+
+**Q: How do I know if my feature is too big for Quick Flow?**
+A: If it requires more than 3-5 days of work, affects multiple systems significantly, or needs extensive UX design, consider the BMad Method track.
+
+**Q: Can I switch from Quick Flow to BMad Method mid-development?**
+A: Yes, you can upgrade. Create the missing artifacts (PRD, architecture) and transition to sprint-based development.
+
+**Q: Is Quick Flow suitable for production-critical features?**
+A: Yes, with code review. Quick Flow doesn't sacrifice quality, just ceremony.
+
+**Q: How do I handle dependencies between Quick Flow features?**
+A: Document dependencies clearly, consider batching related features, or upgrade to BMad Method for complex interdependencies.
+
+**Q: Can junior developers use Quick Flow?**
+A: Yes, but they may benefit from the structure of BMad Method. Quick Flow assumes familiarity with patterns and autonomy.
+
+---
+
+**Ready to ship fast?** → Start with `/bmad:bmm:agents:quick-flow-solo-dev`