Parallel Mission Development with Worktrees

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, the kanban dashboard shows every mission at once, and git checkout disappears from your daily loop.

The Problem Without Worktrees

Traditional Branch Switching

# Working on Feature A
git 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 simultaneously
cd .worktrees/001-auth          # Feature A
cd .worktrees/002-dashboard     # Feature B
cd .worktrees/003-api-v2        # Feature C

# Each has own:
- Working directory
- IDE window
- Build artifacts
- Node_modules/venv
- Shell history

Benefits:

• No context switching
• Side-by-side development
• Parallel testing
• No branch confusion
• Dashboard shows all missions

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 claude
cd ecommerce-platform
claude

2. 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 responses

Mission A: User Authentication

Terminal 1 (Week 1, Monday)

cd ~/ecommerce-platform
claude

/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 worktree
cd .worktrees/001-auth
claude  # Restart in worktree

/spec-kitty.plan
Use 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 repo
claude  # New agent instance

/spec-kitty.specify

Build product dashboard showing:
- Product catalog with search/filter
- Inventory management
- Sales analytics graphs
- Low stock alerts

Result: Creates .worktrees/002-dashboard/

cd .worktrees/002-dashboard
claude  # Restart in worktree

/spec-kitty.plan
Use 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 repo
claude  # Another new agent instance

/spec-kitty.specify

Integrate payment processing with:
- Stripe checkout
- Subscription management
- Invoice generation
- Refund handling

Result: Creates .worktrees/003-payment/

cd .worktrees/003-payment
claude  # Restart in worktree

/spec-kitty.plan
Use Stripe API v2024, webhook handlers,
idempotency keys, PCI-compliant data handling.

/spec-kitty.tasks
# Creates 7 work packages

/spec-kitty.implement
# Start implementing...

Dashboard View: All Three Missions

Open dashboard in browser:

open http://localhost:3000

You 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: WP01

All visible at once!

Working Across Missions

Switch Context Instantly

# Terminal 1: Working on auth
cd .worktrees/001-auth
vim src/auth/jwt.py
pytest tests/test_jwt.py

# Terminal 2: Working on dashboard (simultaneously!)
cd .worktrees/002-dashboard
vim components/ProductCard.tsx
npm test

# Terminal 3: Working on payments (simultaneously!)
cd .worktrees/003-payment
vim api/stripe_webhooks.py
pytest tests/test_webhooks.py

All 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 another
cp .worktrees/001-auth/tests/conftest.py .worktrees/002-dashboard/tests/

IDE Setup

# VS Code: Open three windows
code .worktrees/001-auth
code .worktrees/002-dashboard
code .worktrees/003-payment

# Or use split panes in one window

Each IDE window maintains state independently!

Merge Order: Mission Completion

Mission A Completes First (Week 1, Friday)

# Terminal 1
cd .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-auth

Terminal 1 now free for new work!

Mission B Completes Second (Week 2, Wednesday)

# Terminal 2
cd .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 3
cd .worktrees/003-payment

/spec-kitty.accept
/spec-kitty.merge
# Merged to main

Sprint complete - all three missions shipped!

Benefits Realized

1. No Context Switching

Without Worktrees:

git checkout 001-auth      # 5 seconds + mental load
# Work for 30 minutes
git checkout 002-dashboard # 5 seconds + mental load
# Where was I? Check notes...

With Worktrees:

cd .worktrees/001-auth     # Instant
# Work for 30 minutes
cd .worktrees/002-dashboard # Instant
# IDE state preserved, exactly where you left off

2. Parallel Testing

Without Worktrees:

# Can't test both features simultaneously
git checkout feature-a
pytest  # Must wait...
git checkout feature-b
pytest  # More waiting...

With Worktrees:

# Terminal 1
cd .worktrees/001-auth && pytest &

# Terminal 2
cd .worktrees/002-dashboard && npm test &

# Terminal 3
cd .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~1
git checkout correct-branch
git cherry-pick abc123

With Worktrees:

# Impossible to commit to wrong branch
# Each terminal IS the branch
# Directory name reminds you which mission

4. Side-by-Side Comparison

# Compare auth and payment error handling
diff .worktrees/001-auth/src/errors.py \
     .worktrees/003-payment/api/errors.py

# View both in VS Code side-by-side
code --diff .worktrees/001-auth/README.md \
             .worktrees/002-dashboard/README.md

5. Dashboard Coordination

One screen shows all missions:

• PM sees progress on all three
• Bottlenecks visible (Mission B stuck in review)
• Rebalance work based on dashboard
• Export single report for all missions

Advanced: Shared Code Between Missions

Problem: Both missions need same util

# Mission A creates utility
cd .worktrees/001-auth
vim src/utils/validation.py  # Email validator

# Mission B needs it too
cd .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 it
cd .worktrees/002-dashboard
git pull origin main  # Get the utility
from utils.validation import validate_email  # Use it!

Solution 2: Create a Shared Utilities Mission

cd ~/ecommerce-platform
/spec-kitty.specify
Create 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 use

Common Patterns

Pattern 1: Dependent Missions

Week 1: Mission A (Auth) → Merge
Week 2: Mission B (Dashboard - needs auth) → Use merged A

Pattern 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 & Merge
Mission B → Complete & Merge
Mission C → Complete & Merge
(But all worktrees exist simultaneously for easy comparison)

Tips for Parallel Development

1. Name terminals clearly

   # Set terminal title
   echo -e "\033]0;Feature A: Auth\007"
   

2. Use tmux/screen for persistence

   tmux new -s auth
   tmux new -s dashboard
   tmux new -s payment
   

3. Dashboard as coordination hub

   • Daily standup: Show dashboard
   • Identify blocked missions
   • Rebalance work across missions

4. Merge frequently

   • Don't let features diverge for weeks
   • Merge completed features immediately
   • Reduces integration conflicts

5. 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 worktrees
git worktree list

# Remove completed worktree
git worktree remove .worktrees/001-auth

# Remove branch
git branch -d 001-auth

But /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
Dashboard View	N/A	All missions visible
Mental Overhead	High	Low

Worktrees + Spec Kitty = parallel mission development without the pain!