/merge-tracks

Merge Tracks Command

**Debug/Expert Command** - Manually merge parallel development tracks.

> **Note:** This command is rarely needed. Track merging happens automatically when all tracks complete via `/devteam:implement`. Use this only if automatic merge failed or you need manual control over the merge process.

You are orchestrating the **parallel development tracks merging phase** to combine all completed tracks back into the main branch.

Command Usage

/devteam:merge-tracks                      # Merge all tracks, create PR, cleanup worktrees (default)
/devteam:merge-tracks --manual-merge       # Merge all tracks, skip PR, cleanup worktrees
/devteam:merge-tracks --keep-worktrees     # Merge, create PR, keep worktrees
/devteam:merge-tracks --delete-branches    # Merge, create PR, cleanup worktrees & branches
/devteam:merge-tracks --dry-run            # Show what would be merged without doing it

**Flags:**

• `--manual-merge`: Skip automatic PR creation after merge, allow manual PR creation
• `--keep-worktrees`: Keep worktrees after merge (default: delete)
• `--delete-branches`: Delete track branches after merge (default: keep)
• `--dry-run`: Preview merge plan without executing

Prerequisites

This command only works for projects planned with git worktrees (`--use-worktrees` flag).

**Pre-flight checks:** 1. SQLite state database must exist with worktree mode enabled 2. All tracks must be complete (all sprints in all tracks marked "completed") 3. No uncommitted changes in any worktree 4. All worktrees should have pushed to remote (optional but recommended)

Your Process

Step 0: Parse Parameters

Extract flags from command:

• `--manual-merge`: Skip PR creation after merge (default: false)
• `--keep-worktrees`: Do not delete worktrees after merge (default: false)
• `--delete-branches`: Delete track branches after merge (default: false)
• `--dry-run`: Show merge plan without executing (default: false)

Step 1: Load State and Validate

1. **Load state from SQLite** (`.devteam/devteam.db` via `source scripts/state.sh`)

2. **Verify worktree mode:**

   if state.parallel_tracks.mode != "worktrees":
       error("This project was not planned with worktrees. Nothing to merge.")
       suggest("/devteam:implement --sprint all  # All work already in main branch")
       exit(1)

3. **Verify all tracks complete:**

   incomplete_tracks = []
   for track_id, track_info in state.parallel_tracks.track_info.items():
       track_sprints = filter(s for s in state.sprints if s.track == track_id)
       if any(sprint.status != "completed" for sprint in track_sprints):
           incomplete_tracks.append(track_id)

   if incomplete_tracks:
       error(f"Cannot merge: Tracks {incomplete_tracks} not complete")
       suggest(f"/devteam:implement --sprint all {incomplete_tracks[0]:02d}  # Complete remaining tracks")
       exit(1)

4. **Check for uncommitted changes:**

   for track in tracks:
       cd $worktree_path
       if [ -n "$(git status --porcelain)" ]; then
           error("Uncommitted changes in $worktree_path")
           suggest("Commit or stash changes before merging")
           exit(1)
       fi

5. **Check remote push status (warning only):**

   for track in tracks:
       cd $worktree_path
       if git status | grep "Your branch is ahead"; then
           warn("Track $track has unpushed commits - recommend pushing for backup")
       fi

Step 2: Create Pre-Merge Backup

**Safety measure:**

# Return to main directory
cd $MAIN_REPO

# Create backup tag
git tag pre-merge-backup-$(date +%Y%m%d-%H%M%S)

echo "✓ Created backup tag: pre-merge-backup-YYYYMMDD-HHMMSS"
echo "  (To restore: git reset --hard <tag-name>)"

Step 3: Show Merge Plan (Dry-Run)

If `--dry-run` flag:

Merge Plan
═══════════════════════════════════════

Tracks to merge: 3
- Track 1 (dev-track-01): 7 commits, 15 files changed
- Track 2 (dev-track-02): 5 commits, 12 files changed
- Track 3 (dev-track-03): 4 commits, 8 files changed

Merge strategy: Sequential merge (track-01 → track-02 → track-03)
Target branch: main (or current branch)

Potential conflicts: 2 files
- src/config.yaml (modified in tracks 01 and 02)
- package.json (modified in tracks 01 and 03)

After merge:
- Delete worktrees: YES (default)
- Delete branches: NO (use --delete-branches to enable)

To proceed with merge:
/devteam:merge-tracks

Exit without merging.

Step 4: Launch Track Merger Agent

If not dry-run, launch the **track-merger** agent:

Task(
  subagent_type="orchestration:track-merger",
  model="opus",
  description="Merge all development tracks intelligently",
  prompt=`Merge all development tracks back to main branch.

State database: .devteam/devteam.db (via source scripts/state.sh)

Your responsibilities:
1. Verify all pre-flight checks passed
2. Ensure we're on the correct base branch (main or specified)
3. Merge each track branch sequentially:
   - Track 1: dev-track-01
   - Track 2: dev-track-02
   - Track 3: dev-track-03
4. Handle merge conflicts intelligently (use context from PRD and tasks)
5. Run integration tests after each merge
6. Create merge commit messages that reference track work
7. Tag the final merged state
8. Create pull request (unless --manual-merge)
9. Clean up worktrees (unless --keep-worktrees)
10. Optionally delete track branches (if --delete-branches)
11. Update SQLite state database to mark merge complete
12. Generate merge completion report

Flags:
- manual_merge: ${manual_merge}
- keep_worktrees: ${keep_worktrees}
- delete_branches: ${delete_branches}

Provide detailed progress updates and final summary.`
)

Step 5: Post-Merge Verification

After track-merger completes:

1. **Run final project review** (same as sprint-all completion):

• Comprehensive code review across all languages
• Security audit
• Performance audit
• Integration t