TDD Cycles with Worktrees

The worktree-first approach to parallel development in SEA-Forge™.

This guide covers the complete TDD cycle workflow, from starting a cycle to cleanup after merge.

Why Worktrees?

Git worktrees allow multiple working directories attached to the same repository, each checked out to a different branch. This enables:

Benefit Description
True parallelism Wave 1 cycles run in separate directories simultaneously
No context switching Just cd to another worktree, no stash/checkout
Agent isolation Each agent works in its own directory
IDE independence Multiple IDE windows, one per cycle
Clean merges Physical separation prevents cross-contamination

Concepts

Cycle Naming Convention

1
2
3
4
5
6

cycle/p{phase}-c{cycle}{agent}-{slug}
       │       │      │       │
       │       │      │       └── Human-readable description
       │       │      └────────── Agent letter (A, B, AA, AB...)
       │       └───────────────── Cycle number within phase
       └───────────────────────── Phase number (maps to ENGINEERING.SOP.md)

Examples:

Waves

Waves indicate dependency order:

Wave Agent Pattern Meaning
1 Single letter (A, B, C) Can run in parallel
2 Double letter (AA, AB, BA) Depends on Wave 1
3 Triple letter (AAA, AAB) Depends on Wave 2

The number of letters = Wave number.

Worktree Directory Naming

1

../SEA-p{phase}-c{cycle}{agent}

Examples:

Complete Lifecycle

1. Start a Cycle

1
2
3
4
5
6
7

# From main repo directory
just cycle-start 9 1 A order-entity

# This creates:
#   Branch: cycle/p9-c1A-order-entity
#   Worktree: ../SEA-p9-c1A
#   GitHub Issue (if gh configured)

The command will output:

1
2
3
4
5
6
7

🚀 Starting TDD Cycle
   Branch: cycle/p9-c1A-order-entity
   Worktree: ../SEA-p9-c1A
   Phase: 9, Cycle: 1, Agent: A, Wave: 1

✅ Cycle ready!
   cd ../SEA-p9-c1A

2. Work in the Worktree

1
2
3
4
5
6
7
8
9
10
11
12
13

cd ../SEA-p9-c1A

# The worktree has full access to just commands
just setup          # If needed
just pipeline <ctx> # Run spec pipeline
just test           # Run tests

# Make your changes
# ... implement the vertical slice ...

# Commit regularly
git add .
git commit -m "feat(orders): implement Order entity"

3. Complete the Cycle

1
2
3
4
5
6
7

# Still in the worktree directory
just cycle-complete 9 1 A

# This will:
#   1. Check for uncommitted changes (fails if dirty)
#   2. Push to origin
#   3. Print next steps

4. Create Pull Request

1
2

# From the worktree
gh pr create --base dev --title "feat(orders): implement Order entity" --body "Implements C1A from Plan P###"

Or use the GitHub web UI.

5. After Merge — Cleanup

1
2
3
4
5
6
7
8

# Return to main repo
cd /path/to/SEA™

# Remove specific worktree
just cycle-worktree-remove 9 1 A

# Or clean all merged worktrees at once
just worktrees-clean

Just Commands Reference

Cycle Lifecycle

Command Purpose
just cycle-start <phase> <cycle> <agent> <slug> Create branch + worktree
just cycle-complete <phase> <cycle> <agent> Push and prepare for PR
just cycle-worktree <phase> <cycle> <agent> <slug> Create worktree for existing branch
just cycle-worktree-remove <phase> <cycle> <agent> Remove specific worktree

Worktree Management

Command Purpose
just worktrees List all worktrees with helpful commands
just worktrees-status Show merge status of each worktree
just worktrees-clean Remove worktrees whose branches are merged
just worktrees-clean-all Remove ALL worktrees (nuclear option)

Parallel Development Example

Running three Wave 1 cycles simultaneously:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Terminal 1
just cycle-start 9 1 A order-entity
cd ../SEA-p9-c1A
# ... work on Order entity ...

# Terminal 2
just cycle-start 9 1 B order-repository-port
cd ../SEA-p9-c1B
# ... work on repository port ...

# Terminal 3
just cycle-start 9 1 C place-order-handler
cd ../SEA-p9-c1C
# ... work on command handler ...

After all three PRs merge, start Wave 2:

1
2
3
4

# Terminal 1
just cycle-start 9 2 AA postgres-order-adapter
cd ../SEA-p9-c2AA
# ... work on real adapter (depends on C1A + C1B) ...

Troubleshooting

“Worktree already exists”

1
2
3
4
5
6

# Check if worktree is still in use
just worktrees

# If you need to recreate it
just cycle-worktree-remove 9 1 A
just cycle-start 9 1 A new-slug

“Uncommitted changes” on cycle-complete

1
2
3
4
5
6
7

# Commit or stash your changes first
git status
git add .
git commit -m "wip: checkpoint"

# Then complete
just cycle-complete 9 1 A

Worktree out of sync with origin

1
2
3

# From the worktree
git fetch origin dev
git rebase origin/dev

Orphaned worktree (branch deleted)

1
2
3

# From main repo
git worktree prune
just worktrees-clean-all

Best Practices

  1. One cycle = one vertical slice — Don’t mix concerns
  2. Commit early, commit often — Worktrees are isolated, no risk
  3. Complete cycles promptly — Don’t let worktrees accumulate
  4. Run worktrees-clean after merge batches — Keep filesystem tidy
  5. Use wave parallelism — Start independent cycles simultaneously
  6. Name slugs descriptively — order-entity not fix-stuff

Integration with Plan Template

The plan-template.md documents cycles in the “Proposed Cycles (Worktree-First)” section:

1
2
3

| Cycle | Worktree | Branch | Wave | Implements |
|-------|----------|--------|------|------------|
| C1A | `../SEA-p9-c1A` | `cycle/p9-c1A-<slug>` | 1 | SDS: Entity X |

Each cycle maps to a worktree, making execution straightforward.

Document Purpose
develop-software.md Full development workflow
plan-template.md Implementation plan format
ENGINEERING.SOP.md Phase definitions
branching.sop.md Branch strategy