# /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.