Parallel Mission Development with Worktrees
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Develop three or more missions at once — no branch-switching churn, no lost IDE state.
At a glance: each mission lives in its own git worktree, so three agents (or three terminals) run in parallel, spec-kitty agent tasks status --mission <slug> reports each mission’s lanes, and git checkout disappears from your daily loop.
The Problem Without Worktrees
Traditional Branch Switching
# Working on Feature Agit checkout feature-a# Implement, test, commit...
# Context switch to Feature B (loses IDE state)git checkout feature-b# Implement, test, commit...
# Back to Feature A (loses IDE state again)git checkout feature-a# What was I doing? 🤔Pain Points:
- Lost IDE state on every switch
- Rebuilds/reinstalls on context switch
- Can’t compare missions side-by-side
- Accidental commits to wrong branch
- Mental overhead tracking current branch
Worktree Solution
# All missions available simultaneouslycd .worktrees/001-auth # Feature Acd .worktrees/002-dashboard # Feature Bcd .worktrees/003-api-v2 # Feature C
# Each has own:- Working directory- IDE window- Build artifacts- Node_modules/venv- Shell historyBenefits:
- No context switching
- Side-by-side development
- Parallel testing
- No branch confusion
- Status for every mission from one terminal
Scenario: Three Parallel Missions
Project: E-commerce platform Timeline: 2-week sprint Missions:
- Mission A: User Authentication (Week 1-2)
- Mission B: Product Dashboard (Week 1-2)
- Mission C: Payment Integration (Week 2)
Setup: Initial Project
1. Initialize Project (One-time)
spec-kitty init ecommerce-platform --ai claudecd ecommerce-platformclaude2. Create Charter (One-time)
/spec-kitty.charter
Create principles for:- Security: PCI compliance for payments, secure auth- Testing: 80% coverage, integration tests required- Performance: <200ms API responsesMission A: User Authentication
Terminal 1 (Week 1, Monday)
cd ~/ecommerce-platformclaude/spec-kitty.specify
Build user authentication with:- Email/password registration- JWT-based sessions- Password reset via email- OAuth integration (Google, GitHub)Result: Creates .worktrees/001-auth/
# Switch to mission worktreecd .worktrees/001-authclaude # Restart in worktree/spec-kitty.planUse Python FastAPI, PostgreSQL, Redis for sessions,SendGrid for email, JWT tokens with refresh rotation.
/spec-kitty.tasks# Creates 6 work packages
/spec-kitty.implement# Start implementing...Keep Terminal 1 open - you’ll come back to it!
Mission B: Product Dashboard
Terminal 2 (Week 1, Tuesday - While Feature A is in progress)
cd ~/ecommerce-platform # Back to main repoclaude # New agent instance/spec-kitty.specify
Build product dashboard showing:- Product catalog with search/filter- Inventory management- Sales analytics graphs- Low stock alertsResult: Creates .worktrees/002-dashboard/
cd .worktrees/002-dashboardclaude # Restart in worktree/spec-kitty.planUse Next.js frontend, Chart.js for graphs,TanStack Query for data fetching, Tailwind CSS.
/spec-kitty.tasks# Creates 8 work packages
/spec-kitty.implement# Start implementing...Keep Terminal 2 open too!
Mission C: Payment Integration
Terminal 3 (Week 2, Monday - Both A and B still in progress)
cd ~/ecommerce-platform # Back to main repoclaude # Another new agent instance/spec-kitty.specify
Integrate payment processing with:- Stripe checkout- Subscription management- Invoice generation- Refund handlingResult: Creates .worktrees/003-payment/
cd .worktrees/003-paymentclaude # Restart in worktree/spec-kitty.planUse Stripe API v2024, webhook handlers,idempotency keys, PCI-compliant data handling.
/spec-kitty.tasks# Creates 7 work packages
/spec-kitty.implement# Start implementing...Status View: All Three Missions
Check each mission’s status from the repository root:
for m in 001-auth 002-dashboard 003-payment; do spec-kitty agent tasks status --mission "$m"doneYou see:
Mission: 001-auth (Progress: 60%)├─ Planned: WP04, WP05├─ Doing: WP03 (Agent: claude, PID: 12345)├─ Review: WP02└─ Done: WP01
Mission: 002-dashboard (Progress: 40%)├─ Planned: WP05, WP06, WP07, WP08├─ Doing: WP04 (Agent: claude, PID: 12346)├─ Review: WP03└─ Done: WP01, WP02
Mission: 003-payment (Progress: 25%)├─ Planned: WP03, WP04, WP05, WP06, WP07├─ Doing: WP02 (Agent: claude, PID: 12347)├─ Review: —└─ Done: WP01All visible from one terminal!
Working Across Missions
Switch Context Instantly
# Terminal 1: Working on authcd .worktrees/001-authvim src/auth/jwt.pypytest tests/test_jwt.py
# Terminal 2: Working on dashboard (simultaneously!)cd .worktrees/002-dashboardvim components/ProductCard.tsxnpm test
# Terminal 3: Working on payments (simultaneously!)cd .worktrees/003-paymentvim api/stripe_webhooks.pypytest tests/test_webhooks.pyAll running at the same time - no git checkout!
Compare Implementations
# Want to see how auth handles errors vs payments?diff .worktrees/001-auth/src/errors.py .worktrees/003-payment/api/errors.py
# Copy pattern from one mission to anothercp .worktrees/001-auth/tests/conftest.py .worktrees/002-dashboard/tests/IDE Setup
# VS Code: Open three windowscode .worktrees/001-authcode .worktrees/002-dashboardcode .worktrees/003-payment
# Or use split panes in one windowEach IDE window maintains state independently!
Merge Order: Mission Completion
Mission A Completes First (Week 1, Friday)
# Terminal 1cd .worktrees/001-auth/spec-kitty.accept# ✓ All tasks in done/# ✓ Coverage: 84%# ✓ Security validation passed
/spec-kitty.merge# Consolidated into local main# Cleaned up .worktrees/001-auth# Deleted branch 001-authTerminal 1 now free for new work!
Mission B Completes Second (Week 2, Wednesday)
# Terminal 2cd .worktrees/002-dashboard/spec-kitty.accept/spec-kitty.merge# Merged to local main (no conflicts with Mission A - already integrated!)Mission C Completes Last (Week 2, Friday)
# Terminal 3cd .worktrees/003-payment/spec-kitty.accept/spec-kitty.merge# Merged to mainSprint complete - all three missions shipped!
Benefits Realized
1. No Context Switching
Without Worktrees:
git checkout 001-auth # 5 seconds + mental load# Work for 30 minutesgit checkout 002-dashboard # 5 seconds + mental load# Where was I? Check notes...With Worktrees:
cd .worktrees/001-auth # Instant# Work for 30 minutescd .worktrees/002-dashboard # Instant# IDE state preserved, exactly where you left off2. Parallel Testing
Without Worktrees:
# Can't test both features simultaneouslygit checkout feature-apytest # Must wait...git checkout feature-bpytest # More waiting...With Worktrees:
# Terminal 1cd .worktrees/001-auth && pytest &
# Terminal 2cd .worktrees/002-dashboard && npm test &
# Terminal 3cd .worktrees/003-payment && pytest &
# All running in parallel!3. No Branch Confusion
Without Worktrees:
git branch # Which am I on again?git commit # Oh no, wrong branch!git reset HEAD~1git checkout correct-branchgit cherry-pick abc123With Worktrees:
# Impossible to commit to wrong branch# Each terminal IS the branch# Directory name reminds you which mission4. Side-by-Side Comparison
# Compare auth and payment error handlingdiff .worktrees/001-auth/src/errors.py \ .worktrees/003-payment/api/errors.py
# View both in VS Code side-by-sidecode --diff .worktrees/001-auth/README.md \ .worktrees/002-dashboard/README.md5. Status Coordination
One status sweep covers all missions:
- PM sees progress on all three
- Bottlenecks visible (Mission B stuck in review)
- Rebalance work based on status output
- Export single report for all missions
Advanced: Shared Code Between Missions
Problem: Both missions need same util
# Mission A creates utilitycd .worktrees/001-authvim src/utils/validation.py # Email validator
# Mission B needs it toocd .worktrees/002-dashboard# How to share?Solution 1: Merge Mission A First
cd .worktrees/001-auth/spec-kitty.accept/spec-kitty.merge
# Now Mission B can use itcd .worktrees/002-dashboardgit pull origin main # Get the utilityfrom utils.validation import validate_email # Use it!Solution 2: Create a Shared Utilities Mission
cd ~/ecommerce-platform/spec-kitty.specifyCreate shared utilities for email validation, date formatting, etc.
cd .worktrees/000-shared-utils# Implement quickly/spec-kitty.accept && /spec-kitty.merge
# Now both A and B can useCommon Patterns
Pattern 1: Dependent Missions
Week 1: Mission A (Auth) → MergeWeek 2: Mission B (Dashboard - needs auth) → Use merged APattern 2: Independent Missions
Week 1-2: Mission A (Auth) || Mission B (Dashboard) → Merge both (Developed in parallel, no dependencies)Pattern 3: Sequential Missions
Mission A → Complete & MergeMission B → Complete & MergeMission C → Complete & Merge(But all worktrees exist simultaneously for easy comparison)Tips for Parallel Development
-
Name terminals clearly
Terminal window # Set terminal titleecho -e "\033]0;Feature A: Auth\007" -
Use tmux/screen for persistence
Terminal window tmux new -s authtmux new -s dashboardtmux new -s payment -
Status as coordination hub
- Daily standup: Show
spec-kitty agent tasks statusfor each mission - Identify blocked missions
- Rebalance work across missions
- Daily standup: Show
-
Merge frequently
- Don’t let features diverge for weeks
- Merge completed features immediately
- Reduces integration conflicts
-
Shared dependencies
- Create “000-shared-X” missions for common code
- Merge these first
- Other missions pull and use
Cleanup
Manual Cleanup (if needed)
# List all worktreesgit worktree list
# Remove completed worktreegit worktree remove .worktrees/001-auth
# Remove branchgit branch -d 001-authBut /spec-kitty.merge does this automatically!
Summary
| Aspect | Branch Switching | Worktrees |
|---|---|---|
| Context Switch Time | 5-10 seconds | Instant (cd) |
| IDE State | Lost on switch | Preserved |
| Parallel Work | No | Yes |
| Branch Confusion | Common | Impossible |
| Side-by-Side Compare | Difficult | Easy |
| Status View | Per branch | All missions visible |
| Mental Overhead | High | Low |
Worktrees + Spec Kitty = parallel mission development without the pain!