merge-worktree

name	merge-worktree
description	Merge current worktree branch into the original branch, resolve conflicts with AI, then mark worktree for cleanup. Use when the user says "merge this worktree", "merge my branch back", or "finish this worktree."

Merge Worktree

Merge the current worktree's branch into the original (parent) branch. Resolves merge conflicts intelligently. Marks the worktree for cleanup after successful merge.

Instructions

1. Detect Context

Run these commands to understand the current state:

# Are we in a worktree?
git rev-parse --git-common-dir
git rev-parse --git-dir
git rev-parse --show-toplevel

# Current branch (should be worktree-<name>)
git rev-parse --abbrev-ref HEAD

# Find main worktree path
git worktree list --porcelain

Determine:

• WORKTREE_NAME: extracted from current branch (strip worktree- prefix) or directory name
• WORKTREE_BRANCH: current branch (e.g., worktree-bold-fox-gjac)
• MAIN_TREE_PATH: path of the main worktree (first entry in git worktree list)
• PARENT_BRANCH: branch checked out in the main worktree

If NOT in a worktree, tell the user and exit. This skill is designed to run from inside a worktree session.

2. Pre-merge Check

# Ensure all changes are committed in the worktree
git status --porcelain

If there are uncommitted changes:

• .claude/settings.json: This file is auto-managed by Claude Code at runtime. Deep-compare (parse JSON, compare key-value pairs ignoring order) against the committed version. If semantically equivalent, git restore it. If there are real value differences, git restore it anyway — runtime settings changes are ephemeral and should not be merged.
• Other files: Commit them first using the /commit skill or ask the user.

3. Commit Plan Files

Plan files are versioned artifacts that should travel with the branch. Before merging, ensure any plan files created during this worktree session are committed.

# Check for untracked or modified plan files
PLANS_DIR=$(git rev-parse --show-toplevel)/plans
if [ -d "$PLANS_DIR" ]; then
  git status --porcelain "$PLANS_DIR"
fi

If there are uncommitted plan files:

1. Stage them: git add plans/
2. Commit with message: chore: commit plan files from worktree session

This prevents plan files from being orphaned when the worktree is removed (gitignored files and untracked files don't survive cwrm).

4. Check Commits to Merge

# Check how many commits to merge
git rev-list --count <PARENT_BRANCH>..<WORKTREE_BRANCH>

If 0 commits ahead, report "Already up to date" and exit.

5. Check Main Tree State

Before merging, verify the main tree has no uncommitted changes:

git -C <MAIN_TREE_PATH> status --porcelain

If the main tree has uncommitted changes, warn the user and ask them to commit or stash first. Do NOT proceed with the merge — it will mix their uncommitted work with the merge result.

6. Attempt Merge

Run the merge from the main tree:

git -C <MAIN_TREE_PATH> merge --no-edit <WORKTREE_BRANCH>

If merge succeeds: Report success with commit count, skip to step 8.

If merge fails (conflicts): Continue to step 7.

7. Resolve Conflicts

Do NOT abort the merge. Instead:

1. List conflicting files:

   git -C <MAIN_TREE_PATH> diff --name-only --diff-filter=U
   

2. For each conflicting file:

   • Read the file (it has conflict markers <<<<<<<, =======, >>>>>>>)
   • Read the worktree's version: git show <WORKTREE_BRANCH>:<file>
   • Read the parent branch's version: git show <PARENT_BRANCH>:<file>
   • For JSON files (.claude/settings.json, etc.): do a deep comparison — parse both sides and check if the actual key-value pairs are semantically equivalent (ignoring key ordering, whitespace). If equivalent, keep the parent branch's version. Only treat as a real conflict if values differ.
   • For other files: resolve the conflict by understanding both sides' intent
   • Write the resolved file
   • Stage it: git -C <MAIN_TREE_PATH> add <file>

3. After all conflicts resolved:

   git -C <MAIN_TREE_PATH> commit --no-edit
   

4. If you cannot confidently resolve a conflict, leave it and tell the user which files need manual attention.

8. Mark for Cleanup

After successful merge, tell the user:

Merged <N> commit(s) from <WORKTREE_BRANCH> into <PARENT_BRANCH>.

This worktree is now safe to remove:
  cwrm --no-merge <WORKTREE_NAME>

Or continue working — run /merge-worktree again later to sync new commits.

Important

• Never force-push or rebase the parent branch
• Never delete the worktree branch — cwrm handles that
• Prefer the worktree's version when both sides changed the same thing and intent is unclear (the worktree has the newer work)
• Main tree uncommitted changes are checked in step 5 — do not skip this check