9.2 KiB
9.2 KiB
Merge Tracks Command
You are orchestrating the parallel development tracks merging phase to combine all completed tracks back into the main branch.
Command Usage
/multi-agent:merge-tracks # Merge all tracks, create PR, cleanup worktrees (default)
/multi-agent:merge-tracks --manual-merge # Merge all tracks, skip PR, cleanup worktrees
/multi-agent:merge-tracks --keep-worktrees # Merge, create PR, keep worktrees
/multi-agent:merge-tracks --delete-branches # Merge, create PR, cleanup worktrees & branches
/multi-agent: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:
- State file must exist with worktree mode enabled
- All tracks must be complete (all sprints in all tracks marked "completed")
- No uncommitted changes in any worktree
- 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
-
Load state file (
docs/planning/.project-state.yaml) -
Verify worktree mode:
if state.parallel_tracks.mode != "worktrees": error("This project was not planned with worktrees. Nothing to merge.") suggest("/multi-agent:sprint all # All work already in main branch") exit(1) -
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"/multi-agent:sprint all {incomplete_tracks[0]:02d} # Complete remaining tracks") exit(1) -
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 -
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:
/multi-agent:merge-tracks
Exit without merging.
Step 4: Launch Track Merger Agent
If not dry-run, launch the track-merger agent:
Task(
subagent_type="multi-agent:orchestration:track-merger",
model="sonnet",
description="Merge all development tracks intelligently",
prompt=`Merge all development tracks back to main branch.
State file: docs/planning/.project-state.yaml
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 state file 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:
-
Run final project review (same as sprint-all completion):
- Comprehensive code review across all languages
- Security audit
- Performance audit
- Integration testing
- Documentation review
-
Update state file:
merge_info: merged_at: "2025-11-03T15:30:00Z" tracks_merged: [1, 2, 3] merge_commit: "abc123def456" conflicts_resolved: 2 worktrees_cleaned: true branches_deleted: false -
Generate completion report in
docs/merge-completion-report.md
Report Formats
Successful Merge
╔═══════════════════════════════════════════╗
║ 🎉 TRACK MERGE SUCCESSFUL 🎉 ║
╚═══════════════════════════════════════════╝
Parallel Development Complete!
Tracks Merged: 3
- Track 1 (Backend): dev-track-01 → main
- Track 2 (Frontend): dev-track-02 → main
- Track 3 (Infrastructure): dev-track-03 → main
Merge Statistics:
- Total commits merged: 16
- Files changed: 35
- Conflicts resolved: 2
- Merge strategy: Sequential
- Merge commit: abc123def456
Quality Checks:
✅ Code review: PASS
✅ Security audit: PASS
✅ Performance audit: PASS
✅ Integration tests: PASS
✅ Documentation: Complete
Cleanup:
✅ Worktrees removed: .multi-agent/track-01/, track-02/, track-03/
⚠️ Branches kept: dev-track-01, dev-track-02, dev-track-03
(Use --delete-branches to remove)
Final state:
- Working branch: main
- All parallel work now integrated
- Backup tag: pre-merge-backup-20251103-153000
Ready for deployment! 🚀
Full report: docs/merge-completion-report.md
Merge with Conflicts
⚠️ MERGE COMPLETED WITH MANUAL RESOLUTION REQUIRED
Tracks Merged: 2/3
- ✅ Track 1 (Backend): Merged successfully
- ✅ Track 2 (Frontend): Merged successfully
- ⚠️ Track 3 (Infrastructure): Conflicts detected
Conflicts in Track 3:
1. src/config.yaml (lines 45-52)
- Track 01 changes: Database connection settings
- Track 03 changes: Deployment configuration
- Resolution needed: Combine both changes
2. package.json (line 23)
- Track 01 changes: Added express dependency
- Track 03 changes: Added docker dependency
- Resolution needed: Include both dependencies
To resolve:
1. Edit the conflicted files manually
2. Run tests to verify
3. Commit the resolution: git commit
4. Re-run: /multi-agent:merge-tracks
Backup available: pre-merge-backup-20251103-153000
Error Handling
Incomplete tracks:
Error: Cannot merge - incomplete tracks detected
Track 2 status: 1/2 sprints complete
Track 3 status: 0/2 sprints complete
Complete all tracks before merging:
/multi-agent:sprint all 02
/multi-agent:sprint all 03
Then retry: /multi-agent:merge-tracks
Not worktree mode:
Error: This project was not planned with git worktrees
Your project uses state-only mode for track separation.
All work is already in the main branch - no merge needed.
Project is complete! Run final review if needed:
/multi-agent:sprint all
Uncommitted changes:
Error: Uncommitted changes in worktree .multi-agent/track-02/
Please commit or stash changes before merging:
cd .multi-agent/track-02/
git status
git add .
git commit -m "Final changes before merge"
Then retry: /multi-agent:merge-tracks
Important Notes
- Always creates backup tag before merge (safety)
- Merges tracks sequentially (not all at once)
- Intelligently resolves conflicts using PRD/task context
- Runs full quality checks after merge
- Default: deletes worktrees, keeps branches
- Use --delete-branches carefully (branches are lightweight and provide history)
- Can be re-run if interrupted (idempotent after conflicts resolved)