Worktree Merge
Merge parallel worktrees into unified branch after parallel implementation.
You MUST:
- ALWAYS perform 3-way analysis - no exceptions, no shortcuts
- Respect interface contracts - parallel work was built against explicit contracts
- Document reasoning - every resolution decision must be justified
- Verify everything - tests are mandatory after each round
Skipping steps = lost features. Rushing = broken integrations. Undocumented decisions = confusion.
Invariant Principles
- Interface contracts are law - Parallel work built against explicit contracts. Violations block merge.
- 3-way analysis mandatory - Base vs ours vs theirs. No blind ours/theirs acceptance.
- Test after each round - Catch integration failures immediately. No "test at end" batching.
- Dependency order prevents cascading conflicts - Merge foundations first.
- Document every decision - Reasoning trail for each conflict resolution.
Pre-Conflict Gate
When dispatching a conflict resolution subagent:
- The subagent prompt MUST instruct it to invoke
resolving-merge-conflicts via the Skill tool
- The subagent prompt MUST include interface contract context from the implementation plan
- Do NOT resolve conflicts inline in the orchestrator context
If you catch yourself resolving a conflict without having loaded the skill: STOP. Dispatch a subagent that loads it.
Inputs/Outputs
| Input |
Required |
Description |
base_branch |
Yes |
Branch all worktrees branched from |
worktrees |
Yes |
List: worktree paths, purposes, dependencies |
interface_contracts |
Yes |
Path to implementation plan defining contracts |
test_command |
No |
Defaults to project standard |
| Output |
Type |
Description |
unified_branch |
Git branch |
All worktree changes merged |
merge_log |
Inline |
Decision trail for each conflict |
verification_report |
Inline |
Test results and contract status |
Pre-Flight
If NO to any: STOP and address before proceeding.
Workflow
Phase 1: Merge Order
Build dependency graph:
| Round |
Criteria |
Example |
| 1 |
No dependencies (foundations) |
setup-worktree |
| 2 |
Depends only on Round 1 |
api-worktree, ui-worktree |
| N |
Depends only on prior rounds |
integration-worktree |
Create merge plan:
## Merge Order
### Round 1 (no dependencies)
- [ ] setup-worktree -> base-branch
### Round 2 (depends on Round 1)
- [ ] api-worktree -> base-branch (parallel)
- [ ] ui-worktree -> base-branch (parallel)
### Round 3 (depends on Round 2)
- [ ] integration-worktree -> base-branch
ALWAYS create checklist via TodoWrite before starting merge operations.
Phase 2: Sequential Round Merging
Dispatch: /merge-worktree-execute
Phase 3: Conflict Resolution
Dispatch: /merge-worktree-resolve
Phases 4-5: Final Verification + Cleanup
Dispatch: /merge-worktree-verify
Conflict Synthesis Patterns
| Pattern |
Scenario |
Resolution |
| Same Interface |
Both implemented a shared interface method |
Check contract for expected behavior. Choose contract-compliant version. If both match, synthesize best parts. If neither matches, fix to match. |
| Overlapping Utilities |
Both added similar helper functions |
Same purpose: keep one, update callers. Different purposes: rename to clarify, keep both. |
| Import Conflicts |
Both added imports |
Merge all imports, remove duplicates, sort per project conventions. |
| Test Conflicts |
Both added tests |
Keep ALL tests from both. Ensure no duplicate test names. Verify no conflicting shared fixtures. |
Error Handling
| Error |
Response |
| Uncommitted changes in worktree |
AskUserQuestion: "Worktree [path] has uncommitted changes. Options: (1) Commit with message '[suggested]', (2) Stash and proceed, (3) Abort for manual handling" |
| Tests fail after merge |
STOP. Do NOT proceed to next round. Invoke systematic-debugging. Fix. Retest. Only continue when passing. |
| Interface contract violation |
CRITICAL: "Contract violation detected. Contract: [spec]. Expected: [X]. Actual: [Y]. Location: [file:line]. MUST fix before merge proceeds." |
Rollback Procedure
If merge goes wrong after commit:
# Identify pre-merge commit
git log --oneline -5
# Reset to before merge (preserve working tree)
git reset --soft HEAD~1
# Or hard reset if working tree also corrupted
git reset --hard [pre-merge-commit-sha]
# Re-attempt with lessons learned
Self-Check
Before completing worktree merge, verify ALL items. If ANY unchecked: STOP and fix.
Success Criteria
- All worktrees merged into base branch
- All interface contracts verified
- All tests passing
- Code review passes
- All worktrees cleaned up
- Single unified branch ready for next steps
1---2name: merging-worktrees3description: Use when merging parallel worktrees back together after parallel implementation, combining parallel development tracks, or unifying branches from dispatched parallel agents. Triggers: 'merge worktrees', 'combine parallel branches', 'integrate parallel work', 'all tracks complete', 'bring everything together'.4---5
6# Worktree Merge
7
8Merge parallel worktrees into unified branch after parallel implementation.
9
10<ROLE>
11Integration Architect trained in version control precision and interconnectivity analysis. Your reputation depends on merging parallel work without losing features or introducing bugs. Every conflict demands 3-way analysis. Every round demands testing. No feature left behind, no bug introduced.
12</ROLE>
13
14<ARH_INTEGRATION>
15This skill uses Adaptive Response Handler pattern for conflict resolution:
16- RESEARCH_REQUEST ("research", "check", "verify") -> Dispatch subagent to analyze git history
17- UNKNOWN ("don't know", "not sure") -> Dispatch analysis subagent to show context
18- CLARIFICATION (ends with ?) -> Answer, then re-ask original question
19- SKIP ("skip", "move on") -> Mark as manual resolution needed
20</ARH_INTEGRATION>
21
22<CRITICAL>
23Take a deep breath. This is very important to my career.
24
25You MUST:
261. ALWAYS perform 3-way analysis - no exceptions, no shortcuts
272. Respect interface contracts - parallel work was built against explicit contracts
283. Document reasoning - every resolution decision must be justified
294. Verify everything - tests are mandatory after each round
30
31Skipping steps = lost features. Rushing = broken integrations. Undocumented decisions = confusion.
32</CRITICAL>
33
34## Invariant Principles
35
361. **Interface contracts are law** - Parallel work built against explicit contracts. Violations block merge.
372. **3-way analysis mandatory** - Base vs ours vs theirs. No blind ours/theirs acceptance.
383. **Test after each round** - Catch integration failures immediately. No "test at end" batching.
394. **Dependency order prevents cascading conflicts** - Merge foundations first.
405. **Document every decision** - Reasoning trail for each conflict resolution.
41
42## Pre-Conflict Gate
43
44<CRITICAL>
45Before resolving ANY merge conflict, the subagent handling resolution MUST have the `resolving-merge-conflicts` skill loaded in its context. Conflicts resolved without the skill loaded will default to the LLM's base-model bias toward "pick the simpler option," which maps to ours/theirs selection, not synthesis.
46
47When dispatching a conflict resolution subagent:
481. The subagent prompt MUST instruct it to invoke `resolving-merge-conflicts` via the Skill tool
492. The subagent prompt MUST include interface contract context from the implementation plan
503. Do NOT resolve conflicts inline in the orchestrator context
51
52If you catch yourself resolving a conflict without having loaded the skill: STOP. Dispatch a subagent that loads it.
53</CRITICAL>
54
55## Inputs/Outputs
56
57| Input | Required | Description |
58|-------|----------|-------------|
59| `base_branch` | Yes | Branch all worktrees branched from |
60| `worktrees` | Yes | List: worktree paths, purposes, dependencies |
61| `interface_contracts` | Yes | Path to implementation plan defining contracts |
62| `test_command` | No | Defaults to project standard |
63
64| Output | Type | Description |
65|--------|------|-------------|
66| `unified_branch` | Git branch | All worktree changes merged |
67| `merge_log` | Inline | Decision trail for each conflict |
68| `verification_report` | Inline | Test results and contract status |
69
70## Pre-Flight
71
72<analysis>
73Before ANY merge operation:
741. Do I have complete merge context? (base branch, worktrees, dependencies, interface contracts)
752. Have I built dependency graph for merge order?
763. For each conflict - have I done 3-way analysis (base, ours, theirs)?
774. Does resolution honor ALL interface contracts?
785. Have I run tests after each merge round?
79
80If NO to any: STOP and address before proceeding.
81</analysis>
82
83## Workflow
84
85### Phase 1: Merge Order
86
87**Build dependency graph:**
88
89| Round | Criteria | Example |
90|-------|----------|---------|
91| 1 | No dependencies (foundations) | setup-worktree |
92| 2 | Depends only on Round 1 | api-worktree, ui-worktree |
93| N | Depends only on prior rounds | integration-worktree |
94
95**Create merge plan:**
96```markdown
97## Merge Order
98### Round 1 (no dependencies)
99- [ ] setup-worktree -> base-branch
100
101### Round 2 (depends on Round 1)
102- [ ] api-worktree -> base-branch (parallel)
103- [ ] ui-worktree -> base-branch (parallel)
104
105### Round 3 (depends on Round 2)
106- [ ] integration-worktree -> base-branch
107```
108
109<RULE>ALWAYS create checklist via TodoWrite before starting merge operations.</RULE>
110
111### Phase 2: Sequential Round Merging
112
113Dispatch: `/merge-worktree-execute`
114
115### Phase 3: Conflict Resolution
116
117Dispatch: `/merge-worktree-resolve`
118
119### Phases 4-5: Final Verification + Cleanup
120
121Dispatch: `/merge-worktree-verify`
122
123## Conflict Synthesis Patterns
124
125| Pattern | Scenario | Resolution |
126|---------|----------|------------|
127| **Same Interface** | Both implemented a shared interface method | Check contract for expected behavior. Choose contract-compliant version. If both match, synthesize best parts. If neither matches, fix to match. |
128| **Overlapping Utilities** | Both added similar helper functions | Same purpose: keep one, update callers. Different purposes: rename to clarify, keep both. |
129| **Import Conflicts** | Both added imports | Merge all imports, remove duplicates, sort per project conventions. |
130| **Test Conflicts** | Both added tests | Keep ALL tests from both. Ensure no duplicate test names. Verify no conflicting shared fixtures. |
131
132## Error Handling
133
134| Error | Response |
135|-------|----------|
136| **Uncommitted changes in worktree** | AskUserQuestion: "Worktree [path] has uncommitted changes. Options: (1) Commit with message '[suggested]', (2) Stash and proceed, (3) Abort for manual handling" |
137| **Tests fail after merge** | STOP. Do NOT proceed to next round. Invoke systematic-debugging. Fix. Retest. Only continue when passing. |
138| **Interface contract violation** | CRITICAL: "Contract violation detected. Contract: [spec]. Expected: [X]. Actual: [Y]. Location: [file:line]. MUST fix before merge proceeds." |
139
140## Rollback Procedure
141
142If merge goes wrong after commit:
143
144```bash
145# Identify pre-merge commit
146git log --oneline -5
147
148# Reset to before merge (preserve working tree)
149git reset --soft HEAD~1
150
151# Or hard reset if working tree also corrupted
152git reset --hard [pre-merge-commit-sha]
153
154# Re-attempt with lessons learned
155```
156
157<FORBIDDEN>
158- Blind ours/theirs acceptance without 3-way analysis
159- Skipping tests between rounds ("I'll test at the end")
160- Treating interface contracts as suggestions
161- Merging code that violates contracts
162- Ignoring type signature mismatches
163- Leaving worktrees or stale branches after success
164- Proceeding after test failure
165- Not documenting merge decisions
166</FORBIDDEN>
167
168## Self-Check
169
170<RULE>Before completing worktree merge, verify ALL items. If ANY unchecked: STOP and fix.</RULE>
171
172- [ ] Merged worktrees in dependency order?
173- [ ] Ran tests after EACH round?
174- [ ] Performed 3-way analysis for ALL conflicts?
175- [ ] Verified interface contracts are honored?
176- [ ] Ran auditing-green-mirage on tests?
177- [ ] Ran code review on final result?
178- [ ] Deleted all worktrees after success?
179- [ ] All tests passing?
180
181<reflection>
182After each phase, verify: outputs produced, quality gates passed, no unresolved merge conflicts or test failures remaining.
183</reflection>
184
185## Success Criteria
186
187- All worktrees merged into base branch
188- All interface contracts verified
189- All tests passing
190- Code review passes
191- All worktrees cleaned up
192- Single unified branch ready for next steps
193
194<FINAL_EMPHASIS>
195Your reputation depends on merging parallel work without losing features or introducing bugs. Every conflict requires 3-way analysis. Every round requires testing. Every merge requires verification. Interface contracts are mandatory, not suggestions. No feature left behind. No bug introduced. You'd better be sure.
196</FINAL_EMPHASIS>
majiayu000