# 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