worktree-merge

Original：🇺🇸 English

Translated

Integrate any number of feature branches from parallel worktrees through one safe integration branch, validating after each merge and running the project's full check suite before touching the main line. Use when parallel worktree development is done and the branches need to be merged, or when the user says "merge my worktrees", "integrate these branches", or invokes /worktree-merge.

2installs

Sourcecoleam00/skills

Added on2026-08-14

NPX Install

npx skill4agent add coleam00/skills worktree-merge

SKILL.md Content

View Translation Comparison →

Worktree Merge

Integrate any number of feature branches into your working branch through a single throwaway integration branch, so nothing lands on the main line until every branch is merged and the whole suite passes. Validation commands are detected from the repo, never assumed.

Input

$ARGUMENTS

is the list of branches to integrate.

Fewer than two → ask which branches to integrate. Don't guess.
Two or more → integrate them in the given order.

Detect the validation commands ONCE

Find the commands that prove this project works, preferring what CI already runs: read

.github/workflows/*

, a

Makefile

, or the manifest's test/lint scripts, and reuse those exact commands (test runner, type checker, linter). Do not hardcode

pytest

/

mypy

/

pyright

— use whatever this repo actually uses.

Steps

Preconditions. Confirm you're at the repository root, not inside
```
worktrees/
```
(
```
[[ $(pwd) =~ /worktrees/ ]]
```
→ error). Store the current branch. Verify every branch in the list exists (
```
git rev-parse --verify <branch>
```
). Abort early with a clear message if any check fails.
Create one integration branch off the current branch, named for the set (e.g.
```
integration-<first>
```
, with a short suffix if there are several — keep it filesystem-safe). This is where merges are tested; the main line stays untouched until the end.
Merge each branch in order,
```
--no-ff
```
. After each merge, run the detected test command so a break is localized to the branch that caused it.
- On conflict: stop, name the conflicting branch and files, and give resolution steps (resolve →
```
git add
```
  →
```
git commit
```
  → re-run the skill). Don't attempt automatic resolution.
- On test failure: stop, report which tests failed, and give the rollback (
```
git checkout <original>
```
  →
```
git branch -D <integration>
```
  ).
Full validation once all branches are merged: run the project's complete detected suite (tests + type checks + lint). Any failure → report it and roll back; nothing reaches the main line red.
Merge the integration branch into the original branch (
```
--no-ff
```
), then delete the integration branch.
Offer cleanup with AskUserQuestion: remove the N worktrees and delete their feature branches, or keep them. On yes, for each branch:
```
git worktree remove worktrees/<branch>
```
and
```
git branch -d <branch>
```
.

Report

Success: the integration branch used, each branch merged (with its post-merge test result), the full validation result, the merge into
```
<original>
```
, and cleanup status (worktrees kept or removed, with the manual cleanup commands if kept).
Failure: the step and branch that failed, the current branch state, and exact rollback commands (
```
git checkout <original>
```
→
```
git branch -D <integration>
```
), plus how to continue after fixing (re-run with the same branch list).

Notes

```
--no-ff
```
preserves each feature branch's history.
The integration branch is disposable — the original branch only moves after every merge and the full suite pass.
Prefer opening a PR per branch when you're on a team; this skill is for fast local integration when you own the merge.