Initial commit
This commit is contained in:
Zhongwei Li
317
commands/merge-tracks.md
Normal file
317
commands/merge-tracks.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# Merge Tracks Command
|
||||
|
||||
You are orchestrating the **parallel development tracks merging phase** to combine all completed tracks back into the main branch.
|
||||
|
||||
## Command Usage
|
||||
|
||||
```bash
|
||||
/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:**
|
||||
1. State file 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 file** (`docs/planning/.project-state.yaml`)
|
||||
|
||||
2. **Verify worktree mode:**
|
||||
```python
|
||||
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)
|
||||
```
|
||||
|
||||
3. **Verify all tracks complete:**
|
||||
```python
|
||||
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)
|
||||
```
|
||||
|
||||
4. **Check for uncommitted changes:**
|
||||
```bash
|
||||
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):**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
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:
|
||||
|
||||
```javascript
|
||||
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:
|
||||
|
||||
1. **Run final project review** (same as sprint-all completion):
|
||||
- Comprehensive code review across all languages
|
||||
- Security audit
|
||||
- Performance audit
|
||||
- Integration testing
|
||||
- Documentation review
|
||||
|
||||
2. **Update state file:**
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
3. **Generate completion report** in `docs/merge-completion-report.md`
|
||||
|
||||
## Report Formats
|
||||
|
||||
### Successful Merge
|
||||
|
||||
```markdown
|
||||
╔═══════════════════════════════════════════╗
|
||||
║ 🎉 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
|
||||
|
||||
```markdown
|
||||
⚠️ 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)
|
||||
Reference in New Issue
Block a user