Purpose
Batch-finalize feature branches in the main repository: scan all active linked worktrees and local branches without worktrees, let the user choose which ones to land, verify each workspace is clean one by one, merge + push in sequence, and finally clean up all successfully merged worktrees. This saves the operation of entering each cd directory and manually delivering one by one.
Core Objective
Primary objective: On the main branch of the main repository, merge the user-selected branches (from worktrees or standalone branches) into main, push to origin, and clean up the successful worktrees—leaving the repository in a known clean state.
Success criteria(all must be satisfied):
- ✅ Invocation context verified: CWD is the main repository root (not inside a linked worktree), and the current branch is the main branch
- ✅ All candidates discovered:
git worktree list --porcelainandgit branchare both resolved; non-main entries are presented to the user in a unified list with type identifiers - ✅ Prechecks completed before any merge: all selected worktree entries have been checked for a clean workspace; all dirty entries are reported together in one block
- ✅ Sequential merge + push: each selected clean branch is in turn merged with
--no-ffand pushed; status is recorded one by one (succeeded/failed) - ✅ Unified cleanup: all
succeededworktree entries are removed together; branch-only entries skip worktree removal; failed entries are not cleaned up at all - ✅ Summary report output: merge / push / cleanup / branch deletion status is covered for each branch
Acceptance test: After the skill finishes executing,git log --oneline <main-branch> has one merge commit for each successful branch;git worktree list only the main repository plus failed/skipped worktree entries remain;git ls-remote origin <main-branch> is consistent with local.
Scope Boundaries
This skill is responsible for:
- Verifying the invocation context (main repository root + main branch)
- Determining the main branch (auto-detect; only ask the user when it cannot be determined)
- Scanning linked worktrees (
git worktree list --porcelain) and local branches without worktrees (git branch) - Deduplication: branches already covered by worktree entries are not shown again
- User multi-selects branches to merge (
allor a subset by index) - Prechecking workspaces: worktree entries use
git -C <path> status --porcelain; branch-only entries skip the dirty check (no separate workspace) - For each selected branch, execute pull →
--no-ffmerge → push - After each failure, ask the user: continue with the remaining entries or abort
- Unified cleanup of all successfully merged worktree entries (
git worktree remove) - Optional feature branch deletion (user confirmation, only
-d) - Per-branch summary report
This skill is not responsible for:
- Single worktree delivery (please use inside the worktree
deliver-feature) - Committing uncommitted changes (please first use inside each worktree
commit-work) - Rebase or squash before merge
- Resolving merge conflicts (stop and report to the user on conflict)
- Creating or managing pull requests
- Force pushing to any branch
- Parallel merge execution (always executed sequentially)
Handoff point:
- →
deliver-feature: When the user, within a single worktree, only wants to deliver that branch withoutcdreturning to the main repository - Stop and prompt the user: When invoked inside a linked worktree, or when invoked on a non-main branch in the main repository
- When a branch has a merge conflict: Stop that one, ask whether to continue with the rest
- When a branch push is rejected: Stop that one, ask whether to continue with the rest
Use Cases
- A developer has 2–4 feature branches (some in worktrees, some as standalone branches) ready to land on main all at once
- Batch wrap-up at the end of a sprint: merge, push, and clean up all completed feature branches in the main repository
- CI / automation flows generated multiple parallel worktrees plus several topic branches, and now the results are being consolidated
Behavior
Workflow (Checklist)
Step 1 — Verify the invocation context
git rev-parse --git-dir # 主仓库: <root>/.git ; linked worktree: <main-root>/.git/worktrees/<name>
git rev-parse --git-common-dir # 两种上下文均返回同一值: <main-root>/.git
git rev-parse --abbrev-ref HEAD # 当前分支
git rev-parse --show-toplevel # 当前仓库根目录
linked worktree's git-dir != git-common-dir; in the main repository the two are equal.
-
If
git rev-parse --git-dirandgit rev-parse --git-common-dirdiffer (i.e., CWD is inside a linked worktree) → Stop:"This skill must be run from the root of the main repository, not from inside a worktree. Current location:
<cwd>. To deliver the branch of the current worktree, usedeliver-feature。" -
If the current branch is not the detected main branch (Step 2) → Stop:
"The current branch is
<current-branch>, not<main-branch>. Please switch to the main branch first:git checkout <main-branch>。"
Record <main-repo>(= git rev-parse --show-toplevel). From then on, the CWD remains here for every step.
Step 2 — Determine the main branch
git remote show origin | grep 'HEAD branch'
- Result is unambiguous (e.g.,
HEAD branch: main) → use it directly. - Command fails or returns no result → check
git branch -rinorigin/main, then checkorigin/master。 - Still cannot determine → Ask the user:
"Unable to automatically determine the main branch. Please enter the main branch name (e.g., main, master, develop):"
Record <main-branch>。
Step 3 — Scan and display selectable branches
# 来源 1:linked worktrees
git worktree list --porcelain
# 来源 2:所有本地分支
git branch --format='%(refname:short)'
Parse the porcelain output. The first worktree record is the main repository itself—skip it. Record each of the rest as a type: worktree candidate.
From the git branch output, exclude:
<main-branch>itself- Branches already covered by worktree entries (deduplicated by branch name)
Record the remaining branches as type: branch candidates (with no associated worktree path).
Build a unified list of {path, branch, type} tuples. Skip detached entries and mark them as unavailable.
- No candidates → Stop:
"No active linked worktrees or local branches found; nothing to integrate."
Display the list with index number, type identifier, path (if applicable), branch name, and most recent activity hint:
Available branches to integrate:
[1] worktree /repos/myapp-auth feat/user-auth (last commit: 2 days ago)
[2] worktree /repos/myapp-api feat/api-v2 (last commit: 5 days ago)
[3] branch — feat/dashboard (last commit: 14 days ago — STALE)
Ask:
"Please select the branches to integrate, enter index numbers (comma-separated) or
all:"
Record <selected-list>。
Step 4 — Pre-check: check all selected entries
For each entry <selected-list> in E:
- If
E.type == worktree:git -C <E.path> status --porcelain - If
E.type == branch: no independent worktree — skip the dirty check, always treat as clean.
Collect the results separately into <clean-list> and <dirty-list>。
If <dirty-list> is non-empty, report all dirty entries uniformly before any merge begins:
Pre-flight check — dirty worktrees (will be skipped):
/repos/myapp-api (feat/api-v2) — 3 uncommitted file(s)
Ask:
"The above worktrees have uncommitted changes. Continue merging the remaining clean entries, or halt everything? [continue / halt]"
halt→ stop; do not perform any merges.continue→ continue only for<clean-list>. If<clean-list>is empty → stop and prompt "no actionable items".
Under no circumstances auto-stash.
Step 5 — Batch merge + push (executed sequentially)
For each entry <clean-list> in E:
# 多分支运行期间保持最新
git pull origin <main-branch>
# --no-ff 合并
git merge --no-ff <E.branch> -m "Merge branch '<E.branch>' into <main-branch>"
# 推送
git push origin <main-branch>
Keep CWD at <main-repo>。
When entry E fails:
- Merge conflict:
"Merge
<E.branch>into<main-branch>resulted in a conflict. Please resolve the conflict in<main-repo>, complete the merge manually, then push and remove the worktree (if applicable)." - Push rejected (non-fast-forward):
"After merging
<E.branch>, the push was rejected. Please run<main-repo>ingit reset --hard HEAD~1to undo the merge, then pull, re-merge, and push."
In both cases, mark E as failed, and ask:
"Continue processing the remaining branches, or abort all remaining items? [continue / abort]"
abort→ stop; do not process any remaining entries.continue→ markEasfailed, and continue with the next one.
Record the result for each entry:succeeded or failed。
Step 6 — Unified cleanup (worktree entries only)
After all merges are complete, confirm that CWD is still <main-repo>:
pwd # 必须等于 <main-repo>
Only for entries in <succeeded-list> where E.type == worktree :
git worktree remove <E.path>
Execute sequentially. If a removal fails (e.g., the path no longer exists), record the error and continue with the next one.
type: branch entries have no worktree path — skip this step entirely. Never remove the worktree of a failed entry.
Step 7 — Offer local branch deletion option
For all entries in <succeeded-list> , display the branch list uniformly:
"Successfully cleaned entries. Delete the following local feature branches? Enter the number,
allornone:"[1] feat/user-auth (was worktree) [2] feat/dashboard (was branch)
After each confirmation, execute:
git branch -d <E.branch>
Use only -d— never use -D. If -d fails, report the error and stop deleting that branch.
Step 8 — Summary report
integrate-branches summary
──────────────────────────────────────────────────────────────────────────
Type Branch Merge Push Cleanup Branch-Del
worktree feat/user-auth ✓ ✓ ✓ deleted
worktree feat/api-v2 ✗(conflict) — — —
branch feat/dashboard ✓ ✓ — deleted
──────────────────────────────────────────────────────────────────────────
Main repo: /repos/myapp · Main branch: main · Remote: origin
Status codes:✓ success · ✗(原因) failed · skipped(dirty) precheck failed · — not applicable
type: branch entries' Cleanup column is always —(no worktree to remove).
Input & Output
Input requirements
| Input | Required | Description |
|---|---|---|
| Main repository + main branch context | Yes | CWD must be the main repository root, and the current branch must equal the main branch |
| Active candidates | Yes | At least one linked worktree or local branch (other than main) exists |
| Branch selection | User input | all or enter comma-separated numbers from the displayed list |
| Working tree clean | Every worktree entry | Dirty worktrees are reported in advance and skipped; branch-only entries always pass pre-check |
| Main branch name | Automatic/Ask | Detect from remote; ask the user when it cannot be determined |
| Network access | Yes | pull and push to origin requires network access |
Output contract
| Element | Description |
|---|---|
| Merge commits | Each successful branch produces one on <main-branch> produces one on --no-ff merge commit |
| Remote push | Each successful branch is pushed once, updating origin/<main-branch> |
| Worktree removal | All successful type: worktree entries are removed from git worktree list are removed from |
| Branch deletion | Optional, executed after user confirmation; only git branch -d |
| Batch summary report | Per-branch table: type / branch / merge / push / cleanup / branch deletion status |
Constraints (Restrictions)
Hard Boundaries
- Force push is prohibited(
--force、--force-with-lease) to any branch - It is prohibited to remove the worktree after a merge or push failure
- Automatic stash is prohibited uncommitted changes — report in advance and skip that worktree
- Use of
git branch -Dis prohibited — only-d(safe deletion) - It is prohibited to start any merge before the pre-check of all selected entries is complete
- It is prohibited to continue executing inside a linked worktree or on a non-main branch of the main repository— stop and give the corresponding prompt
Skill Boundaries
- Single worktree delivery: use inside the worktree
deliver-feature - Commit pending changes: first use inside each worktree
commit-work - rebase / squash: use directly before invoking this skill
git rebase - Create PR: use platform-specific PR tools; this skill merges directly into main
- Code review: use before committing
review-diff; this skill does not perform code review
Anti-Patterns
Invocation context
✅ Run at the root of the main repository, on the main branch
❌ Do not run inside a linked worktree — that is the responsibility of deliver-feature ; after the worktree is deleted, the CWD becomes invalid, causing all subsequent commands to fail
Pre-check order
✅ Before starting any merge, perform a uniform dirty check on all selected worktree entries ❌ Do not check that entry only right before merging — a dirty worktree will be discovered only after some merges have already been committed
Merge method
✅ git merge --no-ff preserves branch history
❌ Do not use git merge --squash or fast-forward — history will be lost
Push safety
✅ Standard git push origin <main-branch>
❌ Never use on main --force or --force-with-lease
Cleanup order
✅ Remove the worktree only after both merge and push succeed ❌ Do not remove after merge but before push—if the push fails, the branch will be inaccessible
Branch deletion
✅ git branch -d(safe), and requires user confirmation
❌ Never use git branch -D(force)—may delete unmerged commits
Examples
Example 1: Mixed worktree branches and standalone branches (normal path)
Scenario: Two worktree branches and one standalone branch are ready to be merged into main。
Execution process:
# 步骤 3:扫描
git worktree list --porcelain
# main: /repos/myapp + /repos/myapp-auth feat/user-auth + /repos/myapp-api feat/api-v2
git branch --format='%(refname:short)'
# feat/user-auth(已在 worktree 中——去重)
# feat/api-v2 (已在 worktree 中——去重)
# feat/dashboard(独立分支)
# 展示列表:
# [1] worktree /repos/myapp-auth feat/user-auth (last commit: 2 days ago)
# [2] worktree /repos/myapp-api feat/api-v2 (last commit: 5 days ago)
# [3] branch — feat/dashboard (last commit: 14 days ago — STALE)
# 用户选择:all
# 步骤 4:预检
git -C /repos/myapp-auth status --porcelain # (empty ✓)
git -C /repos/myapp-api status --porcelain # (empty ✓)
# feat/dashboard — 无 worktree,跳过 ✓
# 步骤 5:顺序 merge + push(3 条)
git pull origin main
git merge --no-ff feat/user-auth -m "Merge branch 'feat/user-auth' into main"
git push origin main
git pull origin main
git merge --no-ff feat/api-v2 -m "Merge branch 'feat/api-v2' into main"
git push origin main
git pull origin main
git merge --no-ff feat/dashboard -m "Merge branch 'feat/dashboard' into main"
git push origin main
# 步骤 6:清理——仅 worktree 条目
pwd # /repos/myapp ✓
git worktree remove /repos/myapp-auth
git worktree remove /repos/myapp-api
# feat/dashboard — type: branch,跳过
# 步骤 7:删除分支——用户选 all
git branch -d feat/user-auth
git branch -d feat/api-v2
git branch -d feat/dashboard
Summary:
integrate-branches summary
──────────────────────────────────────────────────────────────────────────
Type Branch Merge Push Cleanup Branch-Del
worktree feat/user-auth ✓ ✓ ✓ deleted
worktree feat/api-v2 ✓ ✓ ✓ deleted
branch feat/dashboard ✓ ✓ — deleted
──────────────────────────────────────────────────────────────────────────
Main repo: /repos/myapp · Main branch: main · Remote: origin
Example 2: Dirty worktree skipped, standalone branch proceeds normally
Scenario: Three entries are selected, and one worktree has uncommitted changes.
Execution process:
# 步骤 4:预检
git -C /repos/myapp-auth status --porcelain # (empty ✓)
git -C /repos/myapp-api status --porcelain # M src/api.ts ← 脏
# feat/dashboard — 无 worktree,跳过 ✓
Skill reports:
Pre-flight check — dirty worktrees (will be skipped):
/repos/myapp-api (feat/api-v2) — 1 uncommitted file(s)
User answers continue → feat/user-auth and feat/dashboard continue;feat/api-v2 skip.
Summary:
integrate-branches summary
──────────────────────────────────────────────────────────────────────────
Type Branch Merge Push Cleanup Branch-Del
worktree feat/user-auth ✓ ✓ ✓ deleted
worktree feat/api-v2 skipped(dirty) — — —
branch feat/dashboard ✓ ✓ — deleted
──────────────────────────────────────────────────────────────────────────
Example 3: Wrong context—invoked inside a worktree
Scenario: The developer is on the /repos/myapp-api branch of feat/api-v2 .
Execution process:
git rev-parse --git-dir # /repos/myapp/.git/worktrees/myapp-api
git rev-parse --git-common-dir # /repos/myapp/.git (不同 → linked worktree)
Skill stops:
"This skill must run at the root of the main repository, not inside a worktree. Current location:
/repos/myapp-api. To deliver the branch of the current worktree, usedeliver-feature。"
AI Refactor Instruction
If this skill produces incorrect behavior:
- Wrong context continues execution: Return to step 1, add the git-dir vs git-common-dir comparison and branch equality validation
- Precheck skipped or deferred: Return to step 4, ensure prechecks are completed for all selected entries before any merge
- Failed worktree deleted: Stop; only
<succeeded-list>entries oftype: worktreemay be removed - branch-only entry executed worktree remove: branch-only entries have no worktree path—skip step 6 entirely
- Attempted force push: Replace with a standard push; if it fails, stop and report
- Pull skipped before merge: Re-execute from the pull step
- Worktree branch appears duplicated: The deduplication in step 3 must exclude branches already in the worktree list from the
git branchoutput
Self-Check
- Invocation context verified:
git rev-parse --git-direqualsgit rev-parse --git-common-dir, and the current branch equals<main-branch> - Main branch confirmed: Automatically detected or explicitly provided by the user, with no assumptions made
- Both sources scanned:
git worktree list --porcelainandgit branchhave both been parsed, and non-main entries have been displayed - Deduplication executed: Branches in worktrees do not appear duplicated in the branch list
- User selection recorded: Obtained before any precheck
allor a subset of indices - Prechecks for all worktree entries completed before any merge: Executed for each selected worktree entry
git -C <path> status --porcelain - branch-only entries skipped dirty check: They have no working tree to check
- Dirty worktree is uniformly reported: all dirty entries are listed together before the continue/halt prompt
- Pulled before every merge: before every
git merge --no-ffwas executed immediately beforegit pull origin <main-branch> - Used --no-ff merge: confirmed use of
git merge --no-ff, no fast-forward or squash - Marked only after push succeeded
succeeded: only aftergit pushreturned 0 is the entry added to<succeeded-list> - Uniform cleanup is performed only for successful worktree entries:
git worktree removewas never called on failed, skipped, ortype: branchentries - CWD confirmed before cleanup: before any
git worktree removebeforepwdequals<main-repo> - Branch deletion used
-d: no-Dflag in any branch deletion command; the user has confirmed each branch - Summary report has been output: the status code for each branch is correctly filled in
- No force push used: no
--forceor--force-with-lease