zishuo/myclaude
1
0
Fork 0
mirror of https://github.com/cexll/myclaude.git synced 2025-12-24 13:47:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add v6 BMAD-METHOD workflow analysis

Browse Source 
- Comprehensive comparison of v6 vs current workflow
- Identified 7 key innovations with priority rankings
- Created 4-phase implementation roadmap
- Recommended adoptable practices and what to keep

Generated by swe-agent
This commit is contained in:
swe-agent[bot]
2025-10-20 13:18:10 +00:00
parent 9c2c91bb1a
commit 5a23f62ec5
1 changed files with 563 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

563
docs/V6-WORKFLOW-ANALYSIS.md Normal file
View File

@@ -0,0 +1,563 @@
# v6 BMAD-METHOD Workflow Analysis
## Executive Summary
This document analyzes the v6 BMAD-METHOD workflow from [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD/blob/v6-alpha/src/modules/bmm/workflows/README.md) and provides recommendations for adopting its key innovations into our current workflow system.
**Analysis Date**: 2025-10-20
**Current System**: myclaude multi-agent workflow (v3.2)
**Comparison Target**: BMAD-METHOD v6-alpha
---
## Key v6 Innovations
### 1. Scale-Adaptive Planning (★★★★★)
**What it is**: Projects automatically route through different workflows based on complexity levels (0-4).
**v6 Approach**:
```
Level 0: Single atomic change → tech-spec only + 1 story
Level 1: 1-10 stories, 1 epic → tech-spec + 2-3 stories
Level 2: 5-15 stories, 1-2 epics → PRD + tech-spec
Level 3: 12-40 stories, 2-5 epics → PRD + architecture + JIT tech-specs
Level 4: 40+ stories, 5+ epics → PRD + architecture + JIT tech-specs
```
**Current System**: Fixed workflow - always runs PO → Architect → SM → Dev → Review → QA regardless of project size.
**Gap**: We waste effort on small changes by requiring full PRD and architecture docs.
**Recommendation**: **HIGH PRIORITY - Adopt Level System**
Implementation plan:
1. Create `workflow-classifier` agent to assess project complexity
2. Route to appropriate workflow based on level:
- Level 0-1: Skip PRD, go straight to tech-spec
- Level 2: Current workflow minus architecture
- Level 3-4: Current full workflow
3. Add `--level` flag to bmad-pilot for manual override
**Benefits**:
- 80% faster for simple changes (Level 0-1)
- More appropriate documentation overhead
- Better resource allocation
---
### 2. Universal Entry Point - workflow-status (★★★★☆)
**What it is**: Single command that checks project status, guides workflow selection, and recommends next steps.
**v6 Approach**:
```bash
bmad analyst workflow-status
# Checks for existing status file
# If exists: Shows current phase, progress, next action
# If not: Guides to appropriate workflow based on context
```
**Current System**: Users must know which command to run (`/bmad-pilot` vs `/requirements-pilot` vs `/code`).
**Gap**: No centralized status tracking or workflow guidance.
**Recommendation**: **MEDIUM PRIORITY - Create Workflow Hub**
Implementation plan:
1. Create `/workflow-status` command
2. Implement status file at `.claude/workflow-status.md`
3. Auto-detect:
- Project context (greenfield vs brownfield)
- Existing artifacts
- Current workflow phase
4. Provide smart recommendations
**Benefits**:
- Eliminates workflow confusion
- Better onboarding for new users
- Clear progress visibility
---
### 3. Just-In-Time (JIT) Technical Specifications (★★★★★)
**What it is**: Create tech specs one epic at a time during implementation, not all upfront.
**v6 Approach**:
```
FOR each epic in sequence:
WHEN ready to implement epic:
Architect: Run tech-spec workflow for THIS epic only
→ Creates tech-spec-epic-N.md
IMPLEMENT epic completely
THEN move to next epic
```
**Current System**: Architecture doc created upfront for entire project (Phase 2).
**Gap**: Over-engineering risk - we design everything before learning from implementation.
**Recommendation**: **HIGH PRIORITY - Adopt JIT Architecture**
Implementation plan:
1. Phase 2: Create high-level architecture.md only (system overview, major components)
2. Phase 3 (new): JIT tech-spec generation per epic
- Command: `/bmad-architect-epic <epic-number>`
- Input: architecture.md + epic details + learnings from previous epics
- Output: tech-spec-epic-N.md
3. Update bmad-dev to read current epic's tech spec
**Benefits**:
- Prevents over-engineering
- Incorporates learnings from previous epics
- More adaptive to changes
- Reduces upfront planning paralysis
---
### 4. 4-State Story State Machine (★★★★☆)
**What it is**: Explicit story lifecycle tracking in workflow status file.
**v6 State Machine**:
```
BACKLOG → TODO → IN PROGRESS → DONE
BACKLOG: Ordered list of stories to be drafted
TODO: Single story ready for drafting (or drafted, awaiting approval)
IN PROGRESS: Single story approved for development
DONE: Completed stories with dates and points
```
**Current System**: Sprint plan has stories but no state tracking mechanism.
**Gap**: No visibility into which stories are being worked on, completed, or blocked.
**Recommendation**: **HIGH PRIORITY - Implement State Machine**
Implementation plan:
1. Enhance `03-sprint-plan.md` with state sections:
```markdown
## Story Backlog
### BACKLOG
- [ ] Story-001: User login
- [ ] Story-002: Password reset
### TODO
- [ ] Story-003: Profile edit (Status: Draft)
### IN PROGRESS
- [~] Story-004: Dashboard (Status: Ready)
### DONE
- [x] Story-005: Setup (Status: Done) [2025-10-15, 3 points]
```
2. Create workflow commands:
- `/bmad-sm-draft-story` - Moves BACKLOG → TODO, creates story file
- `/bmad-sm-approve-story` - Moves TODO → IN PROGRESS (after user review)
- `/bmad-dev-complete-story` - Moves IN PROGRESS → DONE (after DoD check)
3. Agents read status file instead of searching for "next story"
**Benefits**:
- Clear progress visibility
- No ambiguity on what to work on next
- Prevents duplicate work
- Historical tracking with dates and points
---
### 5. Dynamic Expertise Injection - story-context (★★★☆☆)
**What it is**: Generate targeted technical guidance XML per story before implementation.
**v6 Approach**:
```bash
bmad sm story-context # Generates expertise injection XML
bmad dev dev-story # Implements with context
```
**Current System**: Dev reads all previous artifacts (PRD, architecture, sprint plan) directly.
**Gap**: Dev agent must parse large documents to find relevant info for current story.
**Recommendation**: **MEDIUM PRIORITY - Add Context Generator**
Implementation plan:
1. Create `/bmad-sm-context` command (runs before dev-story)
2. Input: Current story + PRD + architecture
3. Output: `story-{id}-context.xml` with:
- Relevant technical constraints
- Integration points for this story
- Security considerations
- Performance requirements
- Example implementations
4. bmad-dev reads context file first, then implements
**Benefits**:
- Reduces context window usage
- More focused implementation guidance
- Consistent technical patterns
- Faster dev agent reasoning
---
### 6. Continuous Learning - Retrospectives (★★★☆☆)
**What it is**: Capture learnings after each epic and feed improvements back into workflows.
**v6 Approach**:
```bash
bmad sm retrospective # After epic complete
# Documents:
# - What went well
# - What could improve
# - Action items for next epic
# - Workflow adjustments
```
**Current System**: No retrospective mechanism.
**Gap**: We don't learn from successes/failures across epics.
**Recommendation**: **LOW PRIORITY - Add Retrospective Workflow**
Implementation plan:
1. Create `/bmad-retrospective` command (triggered after epic complete)
2. Generate `.claude/specs/{feature}/retrospective-epic-N.md`
3. Sections:
- Epic summary (planned vs actual)
- What went well
- What didn't work
- Learnings for next epic
- Workflow improvements
4. Next epic's planning reads previous retrospectives
**Benefits**:
- Continuous improvement
- Team learning capture
- Better estimations over time
- Process optimization
---
### 7. Workflow Phase Structure (★★★★☆)
**v6 Four-Phase Model**:
```
Phase 1: Analysis (Optional) - Brainstorming, research, briefs
Phase 2: Planning (Required) - Scale-adaptive routing, PRD/GDD, epics
Phase 3: Solutioning (L3-4 only) - Architecture, JIT tech-specs
Phase 4: Implementation (Iterative) - Story state machine loop
```
**Current System**:
```
Phase 0: Repository Scan
Phase 1: Product Requirements (PO)
Phase 2: System Architecture (Architect)
Phase 3: Sprint Planning (SM)
Phase 4: Development (Dev)
Phase 5: Code Review (Review)
Phase 6: QA Testing (QA)
```
**Key Differences**:
- v6 has optional analysis phase (we don't)
- v6 has scale-adaptive routing (we don't)
- v6 treats implementation as iterative loop (we treat as linear)
- v6 has solutioning phase only for complex projects (we always architect)
**Recommendation**: **MEDIUM PRIORITY - Restructure Phases**
Proposed new structure:
```
Phase 0: Status Check (workflow-status) - NEW
Phase 1: Analysis (Optional) - NEW - brainstorming, research
Phase 2: Planning (Scale-Adaptive) - ENHANCED
- Level 0-1: Tech-spec only
- Level 2: PRD + tech-spec
- Level 3-4: PRD + epics
Phase 3: Solutioning (L2-4 only) - ENHANCED
- Level 2: Lightweight architecture
- Level 3-4: Full architecture + JIT tech-specs
Phase 4: Implementation (Iterative) - ENHANCED
- Story state machine
- Dev → Review → Approve loop
Phase 5: QA Testing (Optional) - KEEP
- Can be skipped with --skip-tests
```
---
## Comparison Matrix
| Feature | v6 BMAD-METHOD | Current System | Priority | Effort |
|---------|----------------|----------------|----------|--------|
| Scale-adaptive planning | ✅ Level 0-4 routing | ❌ Fixed workflow | HIGH | Medium |
| Universal entry point | ✅ workflow-status | ❌ Manual selection | MEDIUM | Low |
| JIT tech specs | ✅ One per epic | ❌ All upfront | HIGH | Medium |
| Story state machine | ✅ 4-state tracking | ❌ No tracking | HIGH | Medium |
| Story context injection | ✅ Per-story XML | ❌ Read all docs | MEDIUM | Low |
| Retrospectives | ✅ After each epic | ❌ None | LOW | Low |
| Brownfield support | ✅ Docs-first approach | ⚠️ No special handling | MEDIUM | High |
| Quality gates | ⚠️ Implicit | ✅ Explicit scoring | - | - |
| Code review phase | ❌ Not separate | ✅ Dedicated phase | - | - |
| Repository scan | ❌ Not mentioned | ✅ Phase 0 | - | - |
**Legend**:
- ✅ Fully supported
- ⚠️ Partially supported
- ❌ Not supported
---
## Adoptable Practices - Prioritized Roadmap
### Phase 1: Quick Wins (1-2 weeks)
**Goal**: Add high-value features with low implementation effort
1. **Universal Entry Point** (2 days)
- Create `/workflow-status` command
- Implement `.claude/workflow-status.md` tracking file
- Auto-detect project context and recommend workflow
2. **Story Context Injection** (2 days)
- Create `/bmad-sm-context` command
- Generate story-specific context XMLs
- Update bmad-dev to read context files
3. **Retrospectives** (1 day)
- Create `/bmad-retrospective` command
- Simple template for epic learnings
- Store in `.claude/specs/{feature}/retrospective-epic-N.md`
**Expected Impact**: Better workflow guidance, focused dev context, learning capture
---
### Phase 2: Core Improvements (2-3 weeks)
**Goal**: Implement scale-adaptive planning and state machine
1. **Scale-Adaptive Planning** (1 week)
- Create workflow classifier agent
- Implement Level 0-4 routing logic
- Add shortcuts:
- Level 0: `/code-spec` (tech-spec only)
- Level 1: `/mini-sprint` (tech-spec + few stories)
- Level 2-4: `/bmad-pilot` (current workflow, enhanced)
2. **Story State Machine** (1 week)
- Enhance sprint plan with 4-state sections
- Create state transition commands:
- `/bmad-sm-draft-story`
- `/bmad-sm-approve-story`
- `/bmad-dev-complete-story`
- Update agents to read state file
**Expected Impact**: 80% faster for small changes, clear story tracking
---
### Phase 3: Architectural Changes (3-4 weeks)
**Goal**: Implement JIT architecture and brownfield support
1. **JIT Technical Specifications** (2 weeks)
- Split architecture phase:
- Phase 2: High-level architecture.md
- Phase 3: Epic-specific tech-spec-epic-N.md (JIT)
- Create `/bmad-architect-epic <epic-num>` command
- Update dev workflow to request tech specs as needed
2. **Brownfield Support** (1 week)
- Create `/bmad-analyze-codebase` command
- Check for documentation before planning
- Generate baseline docs for existing code
**Expected Impact**: Better architecture decisions, existing codebase support
---
### Phase 4: Workflow Restructuring (4-5 weeks)
**Goal**: Align with v6 phase model
1. **Phase Restructure** (2 weeks)
- Add optional Analysis phase (brainstorming, research)
- Make Solutioning phase conditional (L2-4 only)
- Convert Implementation to iterative loop
2. **Integration & Testing** (2 weeks)
- Test all new workflows end-to-end
- Update documentation
- Create migration guide
**Expected Impact**: More flexible, efficient workflows
---
## What NOT to Adopt
### 1. Remove Quality Scoring ❌ NOT RECOMMENDED
**v6**: No explicit quality gates with numeric scores
**Current**: 90/100 threshold for PRD and Architecture
**Reasoning**: Our quality scoring system provides objective feedback and clear improvement targets. v6's implicit quality checks are less transparent. **Keep our scoring system.**
### 2. Remove Code Review Phase ❌ NOT RECOMMENDED
**v6**: No separate review phase (incorporated into dev-story)
**Current**: Dedicated bmad-review agent between Dev and QA
**Reasoning**: Separation of concerns improves quality. Independent reviewer catches issues dev might miss. **Keep review phase.**
### 3. Remove Repository Scan ❌ NOT RECOMMENDED
**v6**: No automatic codebase analysis
**Current**: Phase 0 repository scan
**Reasoning**: Understanding existing codebase is critical. Our scan provides valuable context. **Keep repository scan.**
---
## Implementation Strategy
### Incremental Adoption Approach
**Week 1-2: Quick Wins**
```bash
# Add new commands (parallel to existing workflow)
/workflow-status # Universal entry point
/bmad-sm-context # Story context injection
/bmad-retrospective # Epic learnings
```
**Week 3-5: Core Features**
```bash
# Enhance existing workflow
/bmad-pilot --level 0 # Scale-adaptive routing
# Story state machine in sprint plan
```
**Week 6-9: Architecture**
```bash
# Split architecture phase
/bmad-architect # High-level (Phase 2)
/bmad-architect-epic 1 # JIT tech-spec (Phase 3)
```
**Week 10-14: Full Integration**
```bash
# New phase structure with all enhancements
```
### Backward Compatibility
- Keep existing commands working (`/bmad-pilot` without flags)
- Maintain current artifact structure (`.claude/specs/`)
- Gradual migration - old and new workflows coexist
- Clear migration documentation for users
---
## Success Metrics
### Quantitative Goals
1. **Workflow Efficiency**
- 80% reduction in time for Level 0-1 changes
- 50% reduction in context window usage via story-context
- 30% reduction in architecture rework via JIT approach
2. **User Experience**
- 100% of users understand current workflow phase (workflow-status)
- 90% reduction in "which command do I run?" confusion
- Zero manual story selection (state machine handles it)
3. **Code Quality**
- Maintain 90/100 quality gate threshold
- Increase epic-to-epic estimation accuracy by 20% (via retrospectives)
- Zero regression in review/QA effectiveness
### Qualitative Goals
- More adaptive workflows (right-sized for task)
- Clearer progress visibility
- Better learning capture across epics
- Improved brownfield project support
---
## Risks & Mitigation
| Risk | Impact | Mitigation |
|------|--------|------------|
| User confusion from workflow changes | High | Gradual rollout, clear docs, backward compatibility |
| Implementation complexity | Medium | Incremental phases, thorough testing |
| State machine bugs | Medium | Comprehensive state transition testing |
| JIT architecture quality issues | Medium | Keep quality gates, provide good context |
| Migration effort for existing users | Low | Both old and new workflows work side-by-side |
---
## Conclusion
The v6 BMAD-METHOD workflow introduces several powerful innovations that address real pain points in our current system:
**Must Adopt** (HIGH Priority):
1. ✅ Scale-adaptive planning - Eliminates workflow overhead for simple changes
2. ✅ JIT technical specifications - Prevents over-engineering, incorporates learning
3. ✅ Story state machine - Clear progress tracking, eliminates ambiguity
**Should Adopt** (MEDIUM Priority):
4. ✅ Universal entry point - Better user experience, workflow guidance
5. ✅ Phase restructure - More flexible, efficient workflows
6. ✅ Story context injection - Reduces context usage, focused implementation
**Nice to Have** (LOW Priority):
7. ✅ Retrospectives - Continuous improvement, learning capture
**Keep Our Innovations**:
- ✅ Quality scoring system (90/100 gates)
- ✅ Dedicated code review phase
- ✅ Repository scan automation
### Recommended Action Plan
**Immediate** (This sprint):
- Create `/workflow-status` command
- Implement story-context injection
- Add retrospective support
**Next Sprint**:
- Build scale-adaptive classifier
- Implement story state machine
- Add Level 0-1 fast paths
**Next Month**:
- Implement JIT architecture
- Add brownfield support
- Full phase restructure
**Timeline**: 10-14 weeks for complete v6 feature parity while preserving our quality innovations.
---
## References
- **v6 Source**: https://github.com/bmad-code-org/BMAD-METHOD/blob/v6-alpha/src/modules/bmm/workflows/README.md
- **Current Workflow**: `docs/BMAD-WORKFLOW.md`
- **Current Agents**: `bmad-agile-workflow/agents/`
- **Current Commands**: `bmad-agile-workflow/commands/`
---
*Analysis completed: 2025-10-20*
*Analyst: SWE Agent*
*Next Review: After Phase 1 implementation (2 weeks)*