Agent skill

merging-worktrees

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'.

View SKILL.md on GitHub Repository
Stars 5
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/axiomantic/spellbook/tree/main/skills/merging-worktrees

SKILL.md

Worktree Merge

Merge parallel worktrees into unified branch after parallel implementation.

<ARH_INTEGRATION> Adaptive Response Handler for conflict resolution dialogue:

  • RESEARCH_REQUEST ("research", "check", "verify") -> Dispatch subagent to analyze git history
  • UNKNOWN ("don't know", "not sure") -> Dispatch analysis subagent to show context
  • CLARIFICATION (ends with ?) -> Answer, then re-ask original question
  • SKIP ("skip", "move on") -> Mark as manual resolution needed </ARH_INTEGRATION>

MUST:

  1. ALWAYS perform 3-way analysis - no exceptions, no shortcuts
  2. Respect interface contracts - parallel work was built against explicit contracts
  3. Document reasoning - every resolution decision must be justified
  4. Verify everything - tests are mandatory after each round

Skipping steps = lost features. Rushing = broken integrations. Undocumented decisions = confusion. </CRITICAL>

Invariant Principles

  1. Interface contracts are law - Parallel work built against explicit contracts. Violations block merge.
  2. 3-way analysis mandatory - Base vs ours vs theirs. No blind ours/theirs acceptance.
  3. Test after each round - Catch integration failures immediately. No "test at end" batching.
  4. Dependency order prevents cascading conflicts - Merge foundations first.
  5. Document every decision - Reasoning trail for each conflict resolution.

Pre-Conflict Gate

When dispatching a conflict resolution subagent:

  1. Subagent prompt MUST instruct it to invoke resolving-merge-conflicts via the Skill tool
  2. Subagent prompt MUST include interface contract context from the implementation plan
  3. 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. </CRITICAL>

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:

markdown
## 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

<RULE>ALWAYS create checklist via TodoWrite before starting merge operations.</RULE>

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:

bash
# 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

<RULE>Before completing worktree merge, verify ALL items. If ANY unchecked: STOP and fix.</RULE>

  • Merged worktrees in dependency order?
  • Ran tests after EACH round?
  • Performed 3-way analysis for ALL conflicts?
  • Verified interface contracts are honored?
  • Ran auditing-green-mirage on tests?
  • Ran code review on final result?
  • Deleted all worktrees after success?
  • All tests passing?

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

<FINAL_EMPHASIS> Your 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. </FINAL_EMPHASIS>

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

axiomantic/spellbook

spellbook-auditing

Meta-audit skill for spellbook development. Spawns parallel subagents to factcheck docs, optimize instructions, find token savings, and identify MCP candidates. Produces actionable report.

5 2
Explore
axiomantic/spellbook

documentation-updates

Use after modifying library skills, library commands, or agents to ensure CHANGELOG, README, and docs are updated

5 2
Explore
axiomantic/spellbook

project-encyclopedia

[DEPRECATED] Use project-level AGENTS.md files instead. Previously used for first-session codebase onboarding and persistent glossary creation.

5 2
Explore
axiomantic/spellbook

reviewing-impl-plans

Use when reviewing implementation plans before execution. Triggers: 'is this plan solid', 'review the plan', 'check before I start building', 'anything missing from this plan', 'will this plan work', 'audit the implementation plan'. NOT for: reviewing design documents (use reviewing-design-docs) or creating plans (use writing-plans).

5 2
Explore
axiomantic/spellbook

session-resume

Session resume protocol and session repairs handling. Loaded when spellbook_session_init returns resume_available: true, or when session_init returns a repairs array. Triggers: 'resume', 'continue', 'where were we', session resume, session repairs.

5 2
Explore
axiomantic/spellbook

brainstorming

Use when exploring design approaches, generating ideas, or making architectural decisions. Triggers: 'explore options', 'what are the tradeoffs', 'how should I approach', 'let's think through', 'sketch out an approach', 'I need ideas for', 'how would you structure', 'what are my options'. Also invoked by develop when design decisions are needed.

5 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results