@cloudkinetix/bmad-enhanced

# /parallel-dev Command - Your Gateway to Parallel Development > 🤖 **LLM-Native** - Works with any LLM platform using intelligent semantic analysis ## The Single Entry Point The `/parallel-dev` command is your **sole entry point** for parallel development. You don't need to know about individual agents or complex orchestration - just describe what work needs to be done, and the system handles everything else. ### What Happens Behind the Scenes When you use `/parallel-dev`, it automatically: 1. **Semantic Analysis** - Uses LLM to understand deep dependencies beyond file names 2. **Intelligent Planning** - Creates risk-optimized execution waves 3. **Comprehensive Validation** - Checks architectural, business, and technical conflicts 4. **Platform Adaptation** - Generates execution patterns for your LLM platform 5. **Real-time Monitoring** - Tracks progress with predictive analytics 6. **Dynamic Optimization** - Adjusts plans based on execution reality 7. **Quality Assurance** - Integrated gates ensure standards are maintained ## Usage ``` /parallel-dev "work description 1" worktree1 ["work description 2" worktree2] ... ``` ## Description Orchestrate intelligent parallel development using LLM-native semantic analysis. The system understands your work at a deep level - analyzing code purpose, business logic, architectural impacts, and hidden dependencies to create optimal execution plans for any LLM platform. ## Simple Examples ### Basic Parallel Work ```bash # Two agents working simultaneously /parallel-dev "Fix login bug in auth.js" bg-login "Add dashboard charts" ft-dash # Three agents with smart naming /parallel-dev "Investigate performance issue" inv-perf "Update API docs" docs "Fix CSS responsiveness" bg-css ``` ### Mixed Work Types ```bash # Bug fix, feature, and task /parallel-dev "Fix payment timeout bug" bg-pay "Add user profiles feature" ft-profiles "Clean up deprecated code" tk-cleanup ``` ## How It Works ### 1. **LLM-Native Dependency Analysis** - **Semantic Understanding**: Analyzes what code does, not just where it lives - **Hidden Dependencies**: Finds API contracts, data flows, business logic interactions - **Risk Assessment**: Evaluates merge probability, integration complexity, quality impact - **Intelligent Grouping**: Creates waves based on semantic boundaries, not just files ### 2. **Wave Execution** ``` Wave 1: bg-login + ft-dash (no file conflicts) Wave 2: bg-css (conflicts with bg-login on shared styles) ``` ### 3. **Platform-Agnostic Execution** - **Claude**: Concurrent Task tool calls in single message - **GPT**: Parallel function calling with thread management - **Gemini**: Batch processing with correlation IDs - **Open Source**: Numbered agent prompts with coordination - **Generic**: Clear instructions for any LLM platform ## Command Options ### Basic Execution ```bash # Simple parallel development /parallel-dev "description1" wt1 "description2" wt2 # With smart prefixes /parallel-dev "Fix bug" bg-auth "Add feature" ft-api ``` ### Advanced Options ```bash # Force single wave (all parallel, ignore conflicts) /parallel-dev --single-wave "work1" wt1 "work2" wt2 # Custom branch prefix /parallel-dev --branch-prefix "feature/" "work1" wt1 "work2" wt2 # Dry run (analyze only, don't execute) /parallel-dev --dry-run "work1" wt1 "work2" wt2 # Skip pre-execution report (not recommended) /parallel-dev --skip-report "work1" wt1 "work2" wt2 # Use existing execution plan /parallel-dev --use-plan .bmad-workspace/ck-parallel-dev/runs/20250703-151230-abc123/execution-plan.json ``` ### Workflow Integration ```bash # Create a workflow plan first /parallel-dev:plan feature-development # Execute according to workflow plan /parallel-dev --follow-plan # Start a specific workflow /parallel-dev:workflow parallel-story-execution # Check workflow status /parallel-dev:workflow-status ``` ## Intelligent Conflict Detection ### Semantic Analysis Approach 1. **Deep Understanding**: LLM analyzes code purpose and interactions 2. **Multi-Dimensional Detection**: - **File Conflicts**: Direct code overlaps - **API Conflicts**: Contract changes affecting consumers - **Data Conflicts**: Schema or state management issues - **Logic Conflicts**: Business rule interactions 3. **Risk-Based Planning**: Prioritizes based on conflict severity 4. **Adaptive Execution**: Adjusts strategy based on detected risks ### Example Semantic Conflict Resolution ```bash # Input /parallel-dev "Fix auth.js login bug" bg-1 "Add auth.js 2FA" ft-2 "Style dashboard.css" ui-3 # Semantic Analysis bg-1: Modifies authentication flow, affects user sessions ft-2: Extends authentication with 2FA, changes auth API contract ui-3: Pure UI changes, no backend dependencies # Intelligent Resolution Wave 1: ui-3 + bg-1 (parallel safe) - UI-3: Independent styling - BG-1: Core auth fix provides foundation Wave 2: ft-2 (depends on fixed auth) - Builds on corrected auth flow - Clean API extension # Reasoning System: "While bg-1 and ft-2 both touch auth.js, semantic analysis shows bg-1 fixes core auth issues that ft-2's 2FA implementation depends on. Sequencing them prevents integration conflicts while allowing ui-3 to run in parallel." ``` ## Worktree Management ### Smart Naming The system uses your specified worktree names directly: - `bg-login` → creates worktree at `../bg-login` - `ft-dashboard` → creates worktree at `../ft-dashboard` - `inv-perf` → creates worktree at `../inv-perf` ### Branch Creation - Worktree `bg-login` → branch `parallel/bg-login` - Worktree `ft-api` → branch `parallel/ft-api` - Worktree `docs` → branch `parallel/docs` ### Cleanup ```bash # Automatic cleanup after completion # Or manual cleanup git worktree remove ../bg-login git worktree remove ../ft-dashboard ``` ## Platform Execution Patterns ### Claude Execution Pattern ``` CONCURRENT TASK DEPLOYMENT - WAVE 1 Deploy 3 agents simultaneously using Task tool: Task 1: AUTH_FIX - Work: Fix login validation bug - Scope: auth.js, validation logic - Isolation: No conflicts with other agents Task 2: UI_STYLE - Work: Style dashboard.css - Scope: UI components only - Isolation: Frontend only Task 3: LOG_SYSTEM - Work: Add structured logging - Scope: logging service - Isolation: Infrastructure layer ``` ### Generic LLM Pattern ``` PARALLEL AGENT INSTRUCTIONS [AGENT-1: AUTH_FIX] Task: Fix login validation bug in authentication service Scope: Focus on auth.js validation logic Coordination: Report progress every 30 minutes Quality: Ensure all auth tests pass [AGENT-2: UI_STYLE] Task: Update dashboard styling Scope: Work only in CSS and UI components Coordination: No dependencies on other agents Quality: Verify responsive design [AGENT-3: LOG_SYSTEM] Task: Implement structured logging Scope: Create new logging service Coordination: Independent infrastructure work Quality: Add comprehensive tests Begin all tasks simultaneously and report [STATUS: COMPLETE] when done. ``` ## Pre-Execution Reports ### What Gets Generated When you run `/parallel-dev`, the system generates: 1. **Pre-Execution Report** (`.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/pre-execution-report.md`) - Executive summary with Go/No-Go recommendation - Risk assessment and mitigation strategies - Wave planning with conflict analysis - Pre-flight checklist 2. **Execution Plan** (`.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/execution-plan.json`) - Machine-readable plan for execution - Pre-computed Task prompts - Wave sequencing logic 3. **Rollback Guide** (`.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/rollback-guide.md`) - Step-by-step rollback instructions - Automated and manual options - Recovery procedures 4. **Dependency Analysis** (`.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/dependency-analysis.json`) - Semantic dependency matrix - Risk assessments - Conflict predictions 5. **Progress Dashboard** (`.bmad-workspace/ck-parallel-dev/runs/{{run-id}}/progress.md`) - Real-time status updates - Quality metrics - Predictive analytics ### Report Review Process ``` 📄 Pre-Execution Report Generated ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Go/No-Go Recommendation: PROCEED ✅ Risk Level: MEDIUM ⚠️ Estimated Duration: 45 minutes 2 warnings require your attention: - Missing dev notes (overridden) - High complexity work item Review full report at: .bmad-workspace/ck-parallel-dev/runs/20250703-151230-abc123/pre-execution-report.md Proceed with execution? (y/N): ``` ## Status and Results ### Check Execution Status ```bash # Check current run status /parallel-dev:status # View execution logs cat .bmad-workspace/ck-parallel-dev/runs/*/execution.log # Check worktree status git worktree list # Check individual worktree cd ../bg-login && git status ``` ### Access Reports ```bash # List all runs ls -la .bmad-workspace/ck-parallel-dev/runs/ # View latest pre-execution report cat .bmad-workspace/ck-parallel-dev/runs/latest/pre-execution-report.md # View rollback guide cat .bmad-workspace/ck-parallel-dev/runs/latest/rollback-guide.md ``` ## Error Handling ### Agent Failure - Failed agent stops, others continue - Worktree preserved for manual inspection - Can restart failed work: `/parallel-dev "same description" failed-worktree` ### Merge Conflicts - System detects potential conflicts during analysis - Suggests alternative sequencing - User can override with `--force-parallel` ### Cleanup on Failure ```bash # Automatic cleanup of completed work # Manual cleanup if needed /parallel-dev:cleanup ``` ## Example Workflows ### Bug Fix Sprint ```bash # Multiple unrelated bugs /parallel-dev \ "Fix login validation bug" bg-login \ "Fix payment timeout issue" bg-payment \ "Fix responsive layout on mobile" bg-mobile # Result: All run in parallel (no file conflicts) ``` ### Feature Development ```bash # Feature with potential conflicts /parallel-dev \ "Add user authentication system" ft-auth \ "Add user profile management" ft-profile \ "Add user settings page" ft-settings # System analyzes and may sequence if they share user-related files ``` ### Mixed Sprint Work ```bash # Bugs, features, and tasks /parallel-dev \ "Investigate performance bottleneck" inv-perf \ "Fix critical security issue" hf-security \ "Add API rate limiting" ft-rate \ "Update deployment documentation" tk-docs # System groups based on file conflicts and executes in optimal waves ``` ## Configuration ### Optional `.claude/parallel-dev.json` ```json { "defaultBranchPrefix": "parallel/", "worktreeBaseDir": "../", "maxConcurrentAgents": 4, "conflictDetection": true, "autoCleanup": true } ``` ## Best Practices 1. **Leverage Semantic Analysis**: Let the LLM understand your code deeply 2. **Trust Risk Assessment**: The system identifies hidden dependencies 3. **Review Execution Plans**: Understand the reasoning behind wave composition 4. **Monitor Progress**: Use real-time tracking for insights 5. **Iterate and Learn**: Each run improves future predictions 6. **Platform Flexibility**: Adapt patterns to your LLM's strengths ## Troubleshooting ### "Worktree already exists" ```bash # Remove existing worktree git worktree remove ../bg-login # Or force remove git worktree remove --force ../bg-login ``` ### "Conflicts detected" - Review the conflict analysis output - Consider splitting conflicting work - Or use `--single-wave` to force parallel execution ### "Agent failed" - Inspect the worktree manually: `cd ../[worktree]` - Restart with same command if needed - Check Task output for specific error details ## Workflow Plans ### Creating a Workflow Plan For complex parallel work, create a structured workflow plan: ```bash # Create a plan for feature development /parallel-dev:plan feature-development # Create a plan for bug fixing sprint /parallel-dev:plan bug-fixing # Create a plan for story execution /parallel-dev:plan story-execution ``` ### Following a Workflow Plan Once you have a workflow plan, execute it: ```bash # Follow the active workflow plan /parallel-dev --follow-plan # Check plan status /parallel-dev:workflow-status # Update plan progress manually /parallel-dev:update-plan --step 3.1 --status complete ``` ### Benefits of Workflow Plans - **Structured Approach**: Phases, waves, and decision points - **Progress Tracking**: Know exactly where you are - **Team Coordination**: Clear communication framework - **Metrics Collection**: Efficiency and quality tracking - **Risk Management**: Identified and mitigated upfront ## Summary The `/parallel-dev` command provides simple, flexible parallel development: - **User-Controlled**: You specify exactly what each agent does - **Conflict-Aware**: Smart dependency analysis prevents merge conflicts - **Git Worktree Based**: Isolated development environments - **Concurrent Execution**: True parallelism using Claude's multi-tool capability (multiple Task calls in single message) - **Workflow Support**: Structured plans for complex parallel work Perfect for sprint work, bug fixes, feature development, and any scenario where multiple independent tasks can be done simultaneously.