Parallel Workflows with Git Worktrees > Research basis: Claude Code git worktrees pattern, Anthropic "One Feature at a Time" harness, HN production patterns on context isolation. --- ## Why Worktree-Based Parallelism The Problem: - Single Claude session = sequential work - Feature A blocks Feature B - Testing waits for development to finish - Documentation waits for everything - Context bloats with unrelated work The Solution: - Git worktrees = isolated working directories - Multiple Claude sessions = true parallelism - Each stream has fresh context - Work merges back when complete `` Main Worktree (orchestrator) | +-- ../project-feature-auth (Claude session 1) +-- ../project-feature-api (Claude session 2) +-- ../project-testing (Claude session 3) +-- ../project-docs (Claude session 4) ` --- ## Parallel Work Streams | Stream | Purpose | Worktree | Triggers | |--------|---------|----------|----------| | **feature-N** | Implement features | ../project-feature-{name} | PRD task breakdown | | **testing** | Unit, integration, E2E | ../project-testing | After feature checkpoint | | **qa-validation** | UAT, accessibility | ../project-qa | After tests pass | | **documentation** | Docs, changelog | ../project-docs | After feature merge | | **blog** | Blog posts (if site has blog) | ../project-blog | After significant releases | --- ## Worktree Management Commands ### Create Feature Worktree `bash # From main worktree git worktree add ../project-feature-auth -b feature/auth # Initialize environment cd ../project-feature-auth npm install # or pip install, cargo build, etc. ` ### Create Testing Worktree (based on main) `bash # Testing always runs against latest main via a dedicated branch # NOTE: git worktree cannot checkout the same branch in two worktrees, # so we create a parallel-testing branch based on main git worktree add ../project-testing -b parallel-testing main # Pull latest before each test run cd ../project-testing git pull origin main ` ### Merge Completed Work `bash # Feature complete, merge back cd /path/to/main/worktree git merge feature/auth --no-ff -m "feat: User authentication" # Remove worktree git worktree remove ../project-feature-auth git branch -d feature/auth ` ### List and Clean Worktrees `bash # List all worktrees git worktree list # Prune stale worktrees git worktree prune ` --- ## Orchestrator Workflow The main orchestrator manages parallel streams: `yaml orchestrator_workflow: 1_plan: - Analyze PRD for parallelizable features - Create task breakdown with dependencies - Identify independent streams 2_spawn: - Create worktrees for independent features - Launch Claude session per worktree - Start testing worktree (tracks main) 3_coordinate: - Watch .loki/state/ in each worktree - Detect feature completion signals - Trigger testing on checkpoints - Queue documentation on merges 4_merge: - Validate tests pass on feature branch - Merge to main - Update testing worktree (git pull) - Trigger documentation stream 5_cleanup: - Remove completed worktrees - Archive session logs - Update main orchestrator state ` --- ## Claude Session Per Worktree Each worktree runs an independent Claude session: `bash # Feature development session cd ../project-feature-auth claude --dangerously-skip-permissions -p "Loki Mode: Implement user authentication. Read .loki/CONTINUITY.md for context." # Testing session (continuous) cd ../project-testing claude --dangerously-skip-permissions -p "Loki Mode: Run all tests. Watch for changes. Report failures to .loki/state/test-results.json" # Documentation session cd ../project-docs claude --dangerously-skip-permissions -p "Loki Mode: Update documentation for recent changes. Check git log for what changed." ` --- ## Inter-Stream Communication Streams communicate via .loki/signals/ and shared git history: ### Signal Files ` .loki/signals/ FEATURE_READY_{name} # Feature ready for testing TESTS_PASSED # All tests green DOCS_NEEDED # Documentation required BLOG_POST_QUEUED # Blog post should be written MERGE_REQUESTED_{branch} # Request merge to main ` ### Workflow Triggers `yaml feature_complete: signal: "Create .loki/signals/FEATURE_READY_{name}" triggers: - Testing stream pulls feature branch - Testing stream runs full suite - On pass: create TESTS_PASSED + MERGE_REQUESTED merge_complete: signal: "Merge commit on main" triggers: - Documentation stream updates docs - If significant: create BLOG_POST_QUEUED - Testing stream pulls latest main blog_trigger: signal: "BLOG_POST_QUEUED exists" triggers: - Blog stream creates post about changes - Removes signal when published ` --- ## Parallel Testing Strategy ### Continuous Testing Worktree ``bash # Testing worktree watches for chang