git-merge-expert-worktree

This skill mutates git state and must stay disciplined.

Non-negotiable rules:

1. Start by listing existing worktrees and identifying the current worktree context.
2. Keep merge operations isolated from the main working tree whenever a worktree is being used.
3. Use git worktree remove, not rm -rf, for normal cleanup.
4. Never delete non-ephemeral branches automatically.
5. Get explicit user confirmation before force-removing dirty worktrees or performing ambiguous branch cleanup.

Git Merge Expert — Worktree Specialist

Inputs

• $request: Merge target, source branch, worktree name, cleanup task, or conflict-resolution goal

Goal

Perform safe worktree-based git operations by:

• discovering existing worktrees and current context
• creating or selecting the right isolated workspace
• doing merge/conflict work in the worktree
• validating the result before integration
• cleaning up worktrees and ephemeral branches correctly

Step 0: Resolve the requested operation

Determine whether the user wants to:

• create a worktree
• perform a merge in a worktree
• resolve merge conflicts in a worktree
• validate an existing worktree merge
• clean up stale or finished worktrees

If the requested source/target branches or cleanup scope are ambiguous, use AskUserQuestion before mutating git state.

Success criteria: The intended worktree action, branch scope, and cleanup expectations are explicit.

Step 1: Discover current worktree state

Before creating or removing anything, inspect:

• git worktree list
• current repository root
• current branch and working tree state
• whether the target branch is already checked out in another worktree

Load references/worktree-conventions.md for path, naming, and lifecycle rules.

Rules:

• always list worktrees first
• verify whether you are already inside a linked worktree or the main tree
• do not attempt to check out the same branch in two worktrees

Success criteria: Existing worktrees, branch occupancy, and current context are known.

Step 2: Create or prepare the isolated worktree

Create or reuse the right worktree for the task.

Typical decisions:

• managed worktree path vs sibling-path worktree
• ephemeral session branch vs existing branch
• setup needs such as dependency install, symlinks, or env-file propagation

Load references/worktree-conventions.md for path and branch conventions.

Rules:

• prefer isolated worktrees over doing merge work in the main tree
• verify creation with git worktree list
• only run setup steps that make sense for the detected project

Success criteria: The worktree exists, is on the intended branch, and is ready for merge work.

Step 3: Perform the merge or conflict operation in the worktree

Inside the worktree:

• create a backup tag when appropriate
• run the merge, rebase, cherry-pick, or cleanup operation requested
• resolve conflicts carefully without silently dropping either side

Load references/merge-playbook.md for:

• conflict tiers
• lockfile handling
• abort-and-recreate recovery
• stale-worktree cleanup patterns

Rules:

• do not merge in the main tree if the user asked for worktree isolation
• regenerate conflicted lockfiles rather than hand-editing them
• abort and recreate the worktree when recovery is cleaner than patching a broken merge state

Success criteria: The git operation is complete in the worktree and the result is coherent.

Step 4: Validate before final integration

Validate the worktree result with the narrowest relevant checks:

• git status
• conflict-free state
• project build/test/typecheck commands when appropriate
• branch topology review when needed

Rules:

• do not claim merge success if unresolved conflicts or failing validation remain
• keep validation scoped to the project/tooling reality
• if validation fails, stop or recover before cleanup/push

Success criteria: The worktree result is clean enough to integrate or push.

Step 5: Cleanup and verify the main tree remains untouched

When the operation is complete:

• return to the main repository context if needed
• remove the worktree with git worktree remove
• delete only ephemeral session branches when appropriate
• run git worktree prune
• verify the remaining worktree list and main-tree state

Load references/merge-playbook.md for cleanup and recovery rules.

Rules:

• never auto-delete non-session branches
• warn before force-removing a dirty worktree
• explicitly verify the main working tree was not unintentionally modified

Success criteria: The worktree lifecycle is closed cleanly and the user can see the final git state.

Guardrails

• Do not let the model invoke this skill proactively; it mutates git and worktree state.
• Do not add context: fork; this workflow already creates git isolation explicitly.
• Do not add paths:; this is a generic git workflow skill.
• Do not keep giant walkthroughs, command tables, or recovery encyclopedias inline in SKILL.md.
• Do not use rm -rf for normal worktree cleanup.
• Do not delete user branches unless the user explicitly asked.
• Do not use force cleanup silently on dirty worktrees.

When To Load References

• references/worktree-expertise.md Use at session start for role and domain expertise.

• references/worktree-conventions.md Use for branch naming, path layout, lifecycle, setup conventions, and destroy safety.

• references/merge-playbook.md Use for merge execution, conflict-resolution tiers, lockfile handling, stale-worktree cleanup, and abort-and-recreate recovery.

Output Contract

Report:

1. the requested operation and resolved branch/worktree scope
2. the worktrees created, reused, or removed
3. the merge/conflict outcome and validation status
4. any branches or tags created or deleted
5. the final git worktree list and main-tree safety status