@cloudkinetix/bmad-enhanced

# Parallel Development Best Practices ## Core Principles ### 1. Dependency Isolation - **Principle**: Minimize shared file modifications across parallel stories - **Practice**: Analyze dependencies before execution - **Benefit**: Reduces merge conflicts and integration issues ### 2. Wave-Based Execution - **Principle**: Group non-conflicting stories into waves - **Practice**: Execute stories with no dependencies simultaneously - **Benefit**: Maximizes parallelization efficiency ### 3. Innovation Through Diversity - **Principle**: Each parallel agent focuses on different quality dimensions - **Practice**: Assign unique innovation dimensions to agents - **Benefit**: Produces varied, high-quality implementations ### 4. Progressive Sophistication - **Principle**: Build complexity incrementally across waves - **Practice**: Start with core functionality, add enhancements in later waves - **Benefit**: Ensures solid foundation with room for innovation ## Technical Guidelines ### Git Worktree Management ```bash # Create worktree for story git worktree add -b feature/story-1-1 worktrees/story-1-1 # List all worktrees git worktree list # Remove worktree after merge git worktree remove worktrees/story-1-1 ``` ### Branch Naming Conventions - Feature branches: `feature/story-X-Y` - Worktree directories: `worktrees/story-X-Y` or `ck-story-X-Y` - Keep names consistent and descriptive ### Commit Message Standards ``` feat(story-1.1): implement user authentication - Add login endpoint - Implement JWT token generation - Add password hashing - Include unit tests Story: 1.1 Tasks: 1-3 complete ``` ## Coordination Strategies ### Progress Tracking - Use centralized orchestrator file - Update progress every task completion - Include blocker information immediately - Monitor quality metrics continuously ### Communication Protocols - Blocking issues: Immediate notification - Progress updates: Every 30 minutes - Quality gate results: As completed - Merge readiness: When all tasks done ### Context Management - Minimize context per agent - Share only essential information - Use summaries for large contexts - Prune unnecessary history ## Quality Assurance ### Testing Strategy - Unit tests: Alongside implementation - Integration tests: After each wave - E2E tests: Before final merge - Performance tests: On completed features ### Code Quality Standards - Linting: Must pass before wave completion - Coverage: Minimum 80% per story - Complexity: Monitor and refactor if needed - Documentation: Update as you code ### DoD Enforcement - Check after each task - Validate at wave boundaries - Final verification before merge - No exceptions to quality standards ## Conflict Resolution ### Merge Conflict Prevention 1. Analyze dependencies upfront 2. Assign clear boundaries 3. Communicate file ownership 4. Merge frequently to detect early ### Conflict Resolution Process 1. Identify conflict source 2. Understand both changes 3. Preserve business logic 4. Test thoroughly after resolution 5. Document resolution decisions ## Performance Optimization ### Parallel Efficiency Metrics - **Ideal**: Linear speedup with agent count - **Reality**: 60-80% efficiency typical - **Factors**: Dependencies, conflicts, coordination overhead ### Optimization Techniques - Minimize shared dependencies - Balance story complexity across waves - Use async operations where possible - Cache shared resources ## Story Validation Philosophy ### Balance Over Enforcement The 3-tier validation system respects developer judgment while providing guardrails: 1. **Critical (Block)**: Only for issues that guarantee failure 2. **Warning (Override)**: Present risks, allow informed decisions 3. **Suggestion (Info)**: Share best practices without friction ### Learning System - Every override is logged with justification - Patterns analyzed monthly - Rules evolve based on real usage - Teams can customize validation levels ### Risk Communication When warnings are found, the system: - Explains specific risks for parallel development - Shows why risks are amplified vs sequential work - Provides clear remediation steps - Respects the decision to proceed ### Story Type Awareness Different validation for different work: - **Features**: Full validation suite - **Spikes**: Relaxed rules focused on goals - **Bugs**: Emphasis on reproduction steps - **Tech Debt**: Focus on impact assessment ## Common Pitfalls ### Over-Parallelization - **Problem**: Too many agents cause coordination overhead - **Solution**: Optimal wave size is 3-5 stories - **Metric**: Efficiency drops below 50% ### Under-Specification - **Problem**: Vague stories lead to conflicts - **Solution**: Detailed Dev Notes and clear boundaries - **Prevention**: 3-tier validation system with override capability - **New Approach**: - Critical issues block execution - Warnings can be overridden with justification - Learn from override patterns to improve rules ### Quality Degradation - **Problem**: Rush to complete sacrifices quality - **Solution**: Enforce quality gates between waves - **Practice**: No progression without passing gates ## Innovation Dimensions Guide ### 1. Efficiency Patterns - Algorithm optimization - Resource utilization - Caching strategies - Query optimization ### 2. Code Organization - Module structure - Design patterns - Dependency injection - Service architecture ### 3. Testing Strategies - Test structure - Mocking approaches - Test data management - Coverage strategies ### 4. Error Handling - Exception hierarchies - Recovery mechanisms - User feedback - Logging strategies ### 5. Documentation Quality - Code comments - API documentation - Usage examples - Architecture decisions ## Measurement and Metrics ### Success Metrics - Parallel efficiency: >60% - Quality gate pass rate: >90% - Merge conflict rate: <10% - Story completion rate: 100% ### Performance Indicators - Time saved vs sequential - Resource utilization - Context switching frequency - Agent productivity ## Continuous Improvement ### Retrospective Focus Areas 1. What parallelization worked well? 2. Where did conflicts occur? 3. Which innovation dimensions were most valuable? 4. How can we improve efficiency? ### Process Refinements - Adjust wave sizes based on results - Refine dependency analysis - Improve coordination protocols - Enhance quality gates ## Tools and Utilities ### Monitoring Commands ```bash # Check parallel progress /stories:status # View dependency analysis /stories:analyze # Monitor specific story cat /tmp/parallel-stories/story-1-1.json ``` ### Debugging Techniques - Check orchestrator logs - Review git worktree status - Analyze merge conflicts - Trace coordination files ## Scaling Considerations ### Large Project Handling - Break into smaller chunks - Use context optimization - Implement progressive waves - Monitor resource usage ### Team Coordination - Clear role definitions - Established communication channels - Regular sync points - Documented procedures