Purpose
Land the current feature branch onto main from within the linked worktree, without switching directories. Through git -C <main-repo> operate on the main repository, while the user stays in the feature worktree the whole time, until they explicitly choose to leave. This eliminates the back-and-forth of "cd to main repo → invoke batch tool → select only the just-finished branch → cd back".
Core Objective
Primary objective: land the current worktree's feature branch (merged via --no-ff ) onto main, push to origin, and let the user decide whether to keep or remove the worktree—all without leaving the worktree directory.
Success criteria(all must be satisfied):
- ✅ Invocation context verified: CWD is inside a linked worktree (not the main repository), and the current branch is not the main branch
- ✅ Pre-check passed: the current worktree has no uncommitted changes (
git status --porcelainis empty) - ✅ Merge is performed in the main repository, not in the worktree:
pull/merge --no-ff/pushall pass viagit -C <main-repo>; during the merge, CWD always stays in the worktree - ✅ Push succeeded:
git push origin <main-branch>only after returning 0 are cleanup options offered - ✅ User controls cleanup: the user explicitly chooses keep / remove (optional branch deletion, only
-d); no implicit removal - ✅ Single-branch summary: report the merge commit hash, push status, and cleanup result
Acceptance test: after the skill finishes executing,git -C <main-repo> log --oneline <main-branch> shows exactly one new merge commit referencing that feature branch;git -C <main-repo> ls-remote origin <main-branch> matches local; if the user chooses removal,git worktree list no longer contains the source worktree.
Scope Boundaries
This skill is responsible for:
- Verifying the invocation context (inside a linked worktree, not the main branch)
- Determining the main branch (auto-detect; only ask the user when it cannot be determined)
- Pre-checking the current worktree (whether the working tree is clean)
- Via
git worktree list --porcelainlocate the main repository path - Via
git -Cperform pull →--no-ffmerge → push - Hand off to the user on conflict or rejected push (no auto-resolution)
- Optionally removing the worktree and deleting the feature branch (user confirmation, only
-d) - Single-branch summary report
This skill is not responsible for:
- Multi-worktree batch operations (please use
integrate-branches) - Committing uncommitted changes (please first use
commit-work) - Rebase or squash before merging
- Resolving merge conflicts (stop and prompt the user on conflict)
- Creating or managing pull requests
- Force-pushing to any branch
Handoff points:
- →
integrate-branches: when the user is on the main branch of the main repository and wants to land multiple worktrees at once - Stop and prompt the user: when invoked in the main repository (not a worktree), or invoked from a worktree that is on the main branch
- On merge conflict: stop and instruct the user to resolve it manually in the main repository; do not handle the worktree
- On rejected push: stop and instruct the user to undo the merge in the main repository (e.g.
git -C <main-repo> reset --hard HEAD~1), retry manually after pulling
Use Cases
- The developer is in
/repos/myapp-api(worktree, branchfeat/api-v2) and has just finished a feature, wants to land it on main but does not want to leave the current directory - Run
commit-workinside the worktree, then immediately deliver that single branch - The IDE / editor session is pinned to a worktree directory; the user wants to deliver a feature but does not want to interrupt the current session
Behavior
Checklist
Step 1 — Verify 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 # 当前 worktree 根目录(CWD 所在的仓库根)
Determine the context: a linked worktree's git-dir != git-common-dir(the per-worktree .git/worktrees/<name> differs from the shared .git ). Equivalently, in a linked worktree <toplevel>/.git is a regular file (gitlink), while in the main repository it is a directory.
-
If
git rev-parse --git-direqualsgit rev-parse --git-common-dir(i.e., the CWD is the main repository rather than a linked worktree) → Stop:"This skill must be run inside a linked worktree, not in the main repository. Current location:
<cwd>. To batch-merge multiple worktrees from the main repository, useintegrate-branches。" -
If the current branch equals the detected main branch (Step 2) → Stop:
"The current branch is
<main-branch>. This skill delivers a feature branch to main, not main into itself. Please switch to the feature branch in this worktree, or from the main repository useintegrate-branches。"
Record <feature-worktree>(= git rev-parse --show-toplevel) and <feature-branch>(= the current branch).
Step 2 — Determine the main branch and locate the main repository
git remote show origin | grep 'HEAD branch'
- The result is unambiguous (e.g.,
HEAD branch: main) → use it directly. - The 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>。
Locate the main repository from the worktree list:
git worktree list --porcelain
Parse the porcelain output. The first record is the main repository (its worktree line gives the path). Record <main-repo>. Integrity check:<main-repo> != <feature-worktree>。
Step 3 — Pre-check: the current worktree must be clean
git status --porcelain
If the output is non-empty → Stop:
"The current worktree
<feature-worktree>has uncommitted changes. Please commit first (e.g., usingcommit-work) and then call again. No automatic stash."
Step 4 — Pull main, merge the feature branch, push (executed via git -C <main-repo> )
git -C <main-repo> checkout <main-branch>
git -C <main-repo> pull origin <main-branch>
git -C <main-repo> merge --no-ff <feature-branch> -m "Merge branch '<feature-branch>' into <main-branch>"
git -C <main-repo> push origin <main-branch>
The CWD of all commands always stays at <feature-worktree>——git -C flag drives main repository operations without changing the user's location.
On merge conflict → Stop:
"Conflict occurred while merging
<feature-branch>into<main-branch>(main repository<main-repo>). Please resolve the conflict manually in the main repository, complete the merge, then rungit -C <main-repo> push origin <main-branch>. The worktree is unaffected."
When the push is rejected (non-fast-forward) → Stop:
"Push was rejected after merging
<feature-branch>. Please run<main-repo>ingit reset --hard HEAD~1to undo the merge, thengit pull, re-merge and push manually."
After a successful push, capture git -C <main-repo> rev-parse <main-branch> via <merge-commit-hash>。
Step 5 — Ask the user about cleanup options
Single prompt, three options:
"Delivery complete. worktree
<feature-worktree>and branch<feature-branch>how should they be handled?[1] Keep worktree (stay here, keep branch) [2] Remove worktree, keep branch (cd back to main repository) [3] Remove worktree and delete branch (
git branch -d, safe delete)Please choose 1 / 2 / 3:"
For options 2 and 3, the skill outputs a final prompt telling the user to cd to <main-repo>(the skill itself cannot change the user shell's CWD; it only executes git commands).
For options 2 and 3, execute via git -C :
git -C <main-repo> worktree remove <feature-worktree>
For option 3 only, after worktree removal execute:
git -C <main-repo> branch -d <feature-branch>
Use only -d—never -D. If -d fails (which should not occur after a successful --no-ff merge), report the error and stop deletion (do not retry -D)。
Step 6 — Summary report
deliver-feature summary
──────────────────────────────────────────────────────────────────────────
Feature branch: feat/api-v2
Worktree: /repos/myapp-api
Main repo: /repos/myapp
Main branch: main
Merge commit: a1b2c3d (--no-ff)
Push: ✓
Worktree: removed | kept
Branch: deleted | kept
──────────────────────────────────────────────────────────────────────────
Next: cd /repos/myapp (仅在 worktree 被移除时显示)
Input & Output
Input requirements
| Input | Required | Description |
|---|---|---|
| Worktree context | Yes | CWD must be inside a linked worktree; stop if invoked in the main repository |
| Non-main branch | Yes | The current branch must not be <main-branch>; otherwise stop |
| Clean working tree | Yes | git status --porcelain must be empty; do not auto-stash |
| Cleanup option | User input | Choose one of three: keep / remove and keep branch / remove and delete branch |
| main branch name | Automatic/ask | Detect from remote; ask the user if it cannot be determined |
| Network access | Yes | pull and push to origin require network |
Output contract
Produces (side effects):
| Element | Description |
|---|---|
| Merge commit | In the main repository <main-branch> exactly one --no-ff merge commit |
| Remote push | origin/<main-branch> updated once |
| Worktree removal | Optional, user-selected |
| Branch deletion | Optional, user-selected; only git branch -d |
| Summary report | Single-branch table, including merge commit hash, push status, cleanup result, and, when applicable, a follow-up cd hint |
Restrictions
Hard Boundaries
- Do not change CWD—all main repository operations are done via
git -C <main-repo>; the user shell always stays in the worktree - Do not force push(
--force、--force-with-lease) to any branch - Do not auto-stash uncommitted changes—stop and prompt the user
- Do not use
git branch -D—only-d - Do not remove the worktree before both merge and push have succeeded
- Do not continue execution in the main repository or on the main branch's worktree——Stop and give the corresponding prompt
Skill Boundaries
- Batch merge multiple worktrees: On the main repository's main branch, use
integrate-branches - Commit pending changes: Before invoking this skill, use
commit-work - rebase / squash: Before invoking this skill, directly use
git rebase - Create PR: Use a platform-specific PR tool; this skill merges directly into main
- Code review: Before committing, use
review-diff; this skill does not perform code review
Anti-Patterns
Invocation Context
✅ Run inside a linked worktree, on a non-main branch
❌ Do not run in the main repository—that is the responsibility of integrate-branches ; when run from main, there is no current worktree to deliver
CWD Discipline
✅ Use git -C <main-repo>for all main repository operations; keep CWD in the worktree
❌ Do not cd <main-repo>midway through skill execution—if the user later removes the worktree, they expect to remain where they were when invoking, until choosing option 2/3
Precheck Order
✅ Verify the working tree is clean before any merge attempt ❌ Do not start merging first, then discover dirty files midway
Merge Method
✅ git merge --no-ff preserves branch history
❌ Do not use git merge --squash or fast-forward—history would be lost
Cleanup Safety
✅ Remove the worktree only after the user explicitly chooses option 2 or 3 and both merge+push succeed ❌ Do not remove the worktree automatically—the user may still want to continue working there
Branch Deletion
✅ Use git branch -donly when the user explicitly chooses option 3 (safe)
❌ Never use git branch -D—it may delete unmerged commits
Examples
Example 1: Normal path—deliver and clean up
Scenario: A developer in worktree /repos/myapp-api has just completed feat/api-v2, and wants to land it and clean up.
Execution Process:
# CWD: /repos/myapp-api
# 步骤 1:上下文——在 linked worktree 内部,非 main 分支 ✓
git rev-parse --git-dir # /repos/myapp/.git/worktrees/myapp-api
git rev-parse --git-common-dir # /repos/myapp/.git (与 --git-dir 不同 → linked worktree ✓)
git rev-parse --abbrev-ref HEAD # feat/api-v2
git rev-parse --show-toplevel # /repos/myapp-api
# 步骤 2:main 分支 + 主仓库
git remote show origin | grep 'HEAD branch' # HEAD branch: main
git worktree list --porcelain # 第一条记录 → /repos/myapp
# 步骤 3:预检——干净 ✓
git status --porcelain # (empty)
# 步骤 4:pull → merge → push,全部通过 git -C;CWD 保持 /repos/myapp-api
git -C /repos/myapp checkout main
git -C /repos/myapp pull origin main
git -C /repos/myapp merge --no-ff feat/api-v2 -m "Merge branch 'feat/api-v2' into main"
git -C /repos/myapp push origin main
# merge commit: a1b2c3d
# 步骤 5:用户选择 [3] 移除 worktree 并删除分支
git -C /repos/myapp worktree remove /repos/myapp-api
git -C /repos/myapp branch -d feat/api-v2
Summary:
deliver-feature summary
──────────────────────────────────────────────────────────────────────────
Feature branch: feat/api-v2
Worktree: /repos/myapp-api
Main repo: /repos/myapp
Main branch: main
Merge commit: a1b2c3d (--no-ff)
Push: ✓
Worktree: removed
Branch: deleted
──────────────────────────────────────────────────────────────────────────
Next: cd /repos/myapp
Example 2: Wrong context—invoked in the main repository
Scenario: A developer is on the /repos/myapp branch of main , and habitually runs deliver-feature。
Execution Process:
# CWD: /repos/myapp
git rev-parse --git-dir # /repos/myapp/.git
git rev-parse --git-common-dir # /repos/myapp/.git (相等 → 主仓库,而非 worktree)
Skill stops:
"This skill must run inside a linked worktree, not in the main repository. Current location:
/repos/myapp. To batch merge multiple worktrees from the main repository, useintegrate-branches。"
No git operations were performed.
Example 3: Conflict—stop, do not handle the worktree
Scenario: A developer runs /repos/myapp-api from the feat/api-v2 of deliver-feature. The precheck passes. A conflict is encountered when merging into main.
Execution Process:
# CWD: /repos/myapp-api(全程保持在此)
git -C /repos/myapp pull origin main
git -C /repos/myapp merge --no-ff feat/api-v2 -m "Merge branch 'feat/api-v2' into main"
# CONFLICT (content): Merge conflict in src/api.ts
Skill stops:
"Conflict occurred while merging
feat/api-v2intomain(main repository/repos/myapp). Please resolve the conflict manually in the main repository, complete the merge, then rungit -C /repos/myapp push origin main. The worktree is unaffected."
CWD is still /repos/myapp-api. The worktree is intact. No push. No cleanup.
AI Refactor Instruction
If this skill produces erroneous behavior:
- CWD was changed during execution: if any step ran
cd <main-repo>or used a non--Cgit command on the main repository → roll back; for all main repository operations usegit -C <main-repo> - Error context continues execution: if the skill was run while the CWD was the main repository (i.e.
git rev-parse --git-direqualsgit rev-parse --git-common-dir) → roll back to step 1, add the git-dir vs git-common-dir comparison check - Automatic stash was performed: if
git stashappears anywhere → remove it; stop when the working tree is dirty per step 3 - worktree was removed before the push succeeded: if
git worktree removeis executed beforegit pushreturns 0 → stop; perform cleanup only after step 4 is complete and the user chooses option 2 or 3 - Attempted to force push: if
--forceor--force-with-leaseappears in any push command → replace with a standard push; if rejected, stop and report
Self-Check List (Self-Check)
- Worktree context verified:
git rev-parse --git-dirandgit rev-parse --git-common-dirare different - Non-main branch confirmed: current branch ≠ detected main branch
- main branch determined: auto-detected or explicitly provided by the user, no assumptions made
- Main repository path located: parsed from the first record of
git worktree list --porcelainFirst record parsing - Pre-checks passed:
git status --porcelainis empty before any merge - CWD never changed: all main repository commands use
git -C <main-repo>; the user's shell always stays in<feature-worktree> - pull done before merge:
git -C <main-repo> pull origin <main-branch>is executed beforegit merge --no-ffexecuted before - Merge with --no-ff used: confirm that
git merge --no-ffis used, with no fast-forward or squash - Cleanup options offered only after a successful push: show the cleanup prompt only after
git pushreturns 0 - Cleanup requires the user's choice: worktree removal occurs only with option 2 or 3
- Branch deletion used
-d: no-Dflag; only option 3 - Summary report output: includes the merge commit hash, push status, cleanup result, and, when applicable, the follow-up cd hint
- No force push used:
--forceor--force-with-lease