Agent skill
worktree-merge
Use when merging parallel worktrees back together after parallel implementation
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/worktree-merge
SKILL.md
Worktree Merge
Merge parallel worktrees into unified branch after parallel implementation.
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 batching "test at end."
- Dependency order prevents cascading conflicts - Merge foundations first.
- Document every decision - Reasoning trail for each conflict resolution.
Inputs
| Input | Required | Description |
|---|---|---|
base_branch |
Yes | Branch all worktrees branched from |
worktrees |
Yes | List of worktree paths with purposes and dependencies |
interface_contracts |
Yes | Path to implementation plan defining contracts |
test_command |
No | Command to run tests (defaults to project standard) |
Outputs
| Output | Type | Description |
|---|---|---|
unified_branch |
Git branch | Single branch with all worktree changes merged |
merge_log |
Inline | Decision trail for each conflict resolution |
verification_report |
Inline | Test results and contract verification status |
Workflow
Phase 1: Merge Order
Build dependency graph. Create merge plan grouping worktrees into rounds by dependencies.
| Round | Criteria |
|---|---|
| 1 | No dependencies (foundations) |
| 2 | Depends only on Round 1 |
| N | Depends only on prior rounds |
Create task checklist via TodoWrite before starting.
Phase 2: Sequential Merge
For each round:
git checkout [base-branch] && git pull origin [base-branch]
WORKTREE_BRANCH=$(cd [worktree-path] && git branch --show-current)
git merge $WORKTREE_BRANCH --no-edit
Conflicts? Proceed to Phase 3. Success? Run tests immediately.
Tests fail? Invoke systematic-debugging. Fix. Retest. Do NOT proceed until green.
Phase 3: Conflict Resolution
Invoke merge-conflict-resolution skill with contract context:
- Interface contracts from implementation plan
- Worktree purpose and expected interfaces
- Type signatures and function contracts
git merge --continue
Phase 4: Final Verification
- Full test suite
- Invoke
green-mirage-auditon modified test files - Invoke
code-revieweragainst implementation plan - Verify each interface contract: both sides exist, types match, behavior matches spec
Phase 5: Cleanup
git worktree remove [worktree-path] --force
git branch -d [worktree-branch] # if no longer needed
Conflict Synthesis Patterns
| Pattern | Resolution |
|---|---|
| Both implemented same interface | Choose contract-compliant version; synthesize if both valid |
| Overlapping utilities | Same purpose: keep one, update callers. Different: rename, keep both |
| Import conflicts | Merge all, dedupe, sort per conventions |
| Test file conflicts | Keep all tests, ensure no name collisions |
Error Handling
| Error | Action |
|---|---|
| Uncommitted changes in worktree | Ask: commit, stash, or abort |
| Tests fail after merge | STOP. Debug. Fix. Retest. No proceeding. |
| Contract violation | STOP. Fix to match contract. Document. |
Self-Check
Before completing:
- Merged in dependency order?
- Tested after EACH round?
- 3-way analysis for ALL conflicts?
- Interface contracts verified?
- Green-mirage-audit run?
- Code review passed?
- Worktrees deleted?
- All tests green?
If ANY unchecked: STOP and fix.
Success Criteria
All worktrees merged. All contracts verified. All tests passing. Code review passed. Worktrees cleaned. Single unified branch ready.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?