SuperAPI AI Directory

deliver-feature

General & other

View repository

Updated 10-15 23:43

About this skill

Skill: Deliver Feature

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):

  1. ✅ Invocation context verified: CWD is inside a linked worktree (not the main repository), and the current branch is not the main branch
  2. ✅ Pre-check passed: the current worktree has no uncommitted changes (git status --porcelain is empty)
  3. ✅ Merge is performed in the main repository, not in the worktree:pull / merge --no-ff / push all pass via git -C <main-repo> ; during the merge, CWD always stays in the worktree
  4. ✅ Push succeeded:git push origin <main-branch> only after returning 0 are cleanup options offered
  5. ✅ User controls cleanup: the user explicitly chooses keep / remove (optional branch deletion, only -d); no implicit removal
  6. ✅ 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 --porcelain locate the main repository path
  • Via git -C perform pull → --no-ff merge → 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, branch feat/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-work inside 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-dir equals git 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, use integrate-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 use integrate-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 -r in origin/main, then check origin/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., using commit-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 run git -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> in git reset --hard HEAD~1 to undo the merge, then git 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, use integrate-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-v2 into main (main repository /repos/myapp). Please resolve the conflict manually in the main repository, complete the merge, then run git -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:

  1. CWD was changed during execution: if any step ran cd <main-repo> or used a non- -C git command on the main repository → roll back; for all main repository operations use git -C <main-repo>
  2. Error context continues execution: if the skill was run while the CWD was the main repository (i.e. git rev-parse --git-dir equals git rev-parse --git-common-dir) → roll back to step 1, add the git-dir vs git-common-dir comparison check
  3. Automatic stash was performed: if git stash appears anywhere → remove it; stop when the working tree is dirty per step 3
  4. worktree was removed before the push succeeded: if git worktree remove is executed before git push returns 0 → stop; perform cleanup only after step 4 is complete and the user chooses option 2 or 3
  5. Attempted to force push: if --force or --force-with-lease appears 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-dir and git rev-parse --git-common-dir are 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 --porcelain First record parsing
  • Pre-checks passed:git status --porcelain is 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 before git merge --no-ff executed 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 push returns 0
  • Cleanup requires the user's choice: worktree removal occurs only with option 2 or 3
  • Branch deletion used -d: no -D flag; 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: --force or --force-with-lease