trax/.claude/docs/parallel-development-workflow.md

# Parallel Development with Git Worktrees

## Overview

Git worktrees enable parallel development across multiple features without branch switching overhead. Each worktree is an independent working directory with its own:
- Branch checkout
- Virtual environment
- File modifications
- Development state

## Worktree Structure

```
apps/
├── trax/                       # Main repository (main branch)
└── trax-worktrees/            # Parallel development worktrees
    ├── trax-features/         # Feature development (feature/development)
    ├── trax-testing/          # Testing & QA (testing/qa)
    ├── trax-docs/             # Documentation (docs/updates)
    ├── trax-performance/      # Performance optimization (perf/optimization)
    ├── trax-bugfix/          # Bug fixes (fix/current)
    ├── switch.sh             # Quick worktree switcher
    └── status.sh             # Status overview script
```

## Quick Start

### Setup Worktrees (One-Time)
```bash
cd apps/trax
.claude/scripts/setup_worktrees.sh
```

### Check Status
```bash
# See all worktrees and their status
/Users/enias/projects/my-ai-projects/apps/trax-worktrees/status.sh

# Or use git directly
git worktree list
```

### Switch Between Worktrees
```bash
# Interactive switcher
/Users/enias/projects/my-ai-projects/apps/trax-worktrees/switch.sh

# Or navigate directly
cd ../trax-worktrees/trax-features
source .venv/bin/activate
```

## Multi-Claude Workflow

Open separate Claude Code sessions for parallel work:

### Terminal 1: Feature Development
```bash
cd apps/trax-worktrees/trax-features
source .venv/bin/activate
claude
# Work on new features
```

### Terminal 2: Testing
```bash
cd apps/trax-worktrees/trax-testing
source .venv/bin/activate
claude
# Write and run tests
```

### Terminal 3: Documentation
```bash
cd apps/trax-worktrees/trax-docs
source .venv/bin/activate
claude
# Update documentation
```

## Workflow Patterns

### 1. Feature Development Pattern
```bash
# In trax-features worktree
git checkout -b feature/whisper-integration
# Implement feature
git add .
git commit -m "feat: add Whisper transcription service"
git push origin feature/whisper-integration
# Create PR on Gitea
```

### 2. Bug Fix Pattern
```bash
# In trax-bugfix worktree
git checkout -b fix/memory-leak
# Fix bug
git add .
git commit -m "fix: resolve memory leak in batch processor"
git push origin fix/memory-leak
# Create PR for quick merge
```

### 3. Testing Pattern
```bash
# In trax-testing worktree
# Pull latest changes from feature branch
git fetch origin
git checkout feature/whisper-integration
# Write comprehensive tests
uv run pytest tests/ -v
# Push test improvements
git push origin feature/whisper-integration
```

### 4. Documentation Pattern
```bash
# In trax-docs worktree
# Update docs for new features
git checkout -b docs/whisper-api
# Update documentation
git add docs/
git commit -m "docs: add Whisper API documentation"
git push origin docs/whisper-api
```

## Best Practices

### 1. Branch Naming Convention
- Features: `feature/description`
- Fixes: `fix/issue-description`
- Docs: `docs/what-updated`
- Performance: `perf/optimization-target`
- Testing: `test/what-testing`

### 2. Worktree Hygiene
```bash
# Clean up finished worktrees
git worktree remove ../trax-worktrees/trax-features

# Prune stale worktree info
git worktree prune

# Re-create if needed
git worktree add ../trax-worktrees/trax-features feature/new-work
```

### 3. Syncing Changes
```bash
# In any worktree, pull latest main
git fetch origin
git merge origin/main

# Or rebase for cleaner history
git rebase origin/main
```

### 4. Virtual Environment Management
Each worktree has its own `.venv`:
```bash
# Activate worktree's venv
source .venv/bin/activate

# Install new dependencies
uv pip install package-name

# Sync with pyproject.toml
uv pip install -e ".[dev]"
```

## Common Commands

### Worktree Management
```bash
# List all worktrees
git worktree list

# Add new worktree
git worktree add ../trax-worktrees/trax-experimental experimental/ai-agents

# Remove worktree
git worktree remove ../trax-worktrees/trax-experimental

# Clean up
git worktree prune
```

### Branch Operations
```bash
# Push new branch to remote
git push -u origin branch-name

# Delete remote branch after merge
git push origin --delete branch-name

# Clean up local branches
git branch -d branch-name
```

## Integration with Gitea

### Creating Pull Requests
```bash
# After pushing branch
gh pr create --title "Feature: Description" --body "Details"

# Or use Gitea web UI
open https://eniasgit.zeabur.app/demo/trax
```

### CI/CD Triggers
Each worktree push triggers Gitea workflows:
- Linting and formatting checks
- Test suite execution
- Type checking
- Build validation

## Troubleshooting

### Issue: Worktree locked
```bash
# Remove lock file
rm .git/worktrees/*/locked

# Or force remove
git worktree remove --force <path>
```

### Issue: Branch conflicts
```bash
# In worktree with conflicts
git fetch origin
git rebase origin/main
# Resolve conflicts
git rebase --continue
```

### Issue: Venv issues
```bash
# Recreate virtual environment
rm -rf .venv
python3.11 -m venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

## Advanced Patterns

### 1. Experimental Features
Create isolated worktree for experiments:
```bash
git worktree add ../trax-experiment experimental/crazy-idea
cd ../trax-experiment
# Experiment freely without affecting other work
```

### 2. Release Preparation
Dedicated worktree for releases:
```bash
git worktree add ../trax-release release/v1.0.0
cd ../trax-release
# Prepare release: version bumps, changelog, etc.
```

### 3. Hotfix Workflow
Quick fixes on production:
```bash
git worktree add ../trax-hotfix main
cd ../trax-hotfix
git checkout -b hotfix/critical-bug
# Fix and push immediately
```

## Performance Benefits

1. **No context switching**: Each worktree maintains its state
2. **Parallel testing**: Run tests in one worktree while developing in another
3. **Instant branch access**: No need to stash/commit to switch branches
4. **Independent dependencies**: Each worktree can have different package versions
5. **Multiple Claude sessions**: Each worktree can have its own Claude Code instance

## Summary

Git worktrees provide a powerful parallel development environment:
- 🚀 **5 default worktrees** for common workflows
- 🔧 **Convenience scripts** for management
- 🐍 **Independent Python environments** per worktree
- 📝 **Clear branch organization** by purpose
- 🤖 **Multi-Claude capability** for parallel AI assistance

Use worktrees to maintain development velocity while keeping clean separation between different work streams.