| name | deliver-feature |
| description | From inside a linked worktree, deliver the current feature branch into main — merge with --no-ff, push, and optionally clean up the worktree, all without leaving CWD. |
| description_zh | 在 linked worktree 内将当前 feature 分支交付到 main——以 --no-ff 合并、推送，并可选清理本 worktree，全程不离开当前目录。 |
| tags | ["git","workflow","automation"] |
| version | 1.1.0 |
| license | MIT |
| recommended_scope | both |
| metadata | {"author":"ai-cortex"} |
| triggers | ["deliver feature","finish feature","land feature","merge feature","ship feature","deliver this"] |
| input_schema | {"type":"free-form","description":"A linked git worktree on a non-main branch with a clean working tree."} |
| output_schema | {"type":"side-effect","description":"One --no-ff merge commit on the main branch in the main repo, pushed to origin; optional worktree removal and feature branch deletion; single-branch summary report."} |
技能（Skill）：交付功能（Deliver Feature）
目的（Purpose）
在 linked worktree 内将当前功能分支落地到 main，无需切换目录。通过 git -C <main-repo> 操作主仓库，用户全程保持在功能 worktree 中，直到明确选择离开为止。省去了"cd 主仓库 → 调用批量工具 → 仅选刚完成的分支 → cd 返回"的来回跳转。
核心目标（Core Objective）
首要目标：将当前 worktree 的功能分支（通过 --no-ff 合并）落地到 main，推送到 origin，并让用户决定保留还是移除该 worktree——全程不离开 worktree 目录。
成功标准（必须全部满足）：
- ✅ 调用上下文已验证：CWD 在 linked worktree 内部（而非主仓库），且当前分支不是 main 分支
- ✅ 预检通过：当前 worktree 无未提交变更（
git status --porcelain 为空）
- ✅ 在主仓库执行合并，不在 worktree 中执行：
pull / merge --no-ff / push 均通过 git -C <main-repo> 完成；合并期间 CWD 始终保持在 worktree
- ✅ 推送成功：
git push origin <main-branch> 返回 0 后才提供清理选项
- ✅ 用户控制清理：用户明确选择保留 / 移除（可选分支删除，仅
-d）；不隐式移除
- ✅ 单分支汇总：报告 merge commit hash、推送状态与清理结果
验收测试：技能执行完毕后，git -C <main-repo> log --oneline <main-branch> 显示恰好一条新的引用该功能分支的 merge commit；git -C <main-repo> ls-remote origin <main-branch> 与本地一致；若用户选择移除，git worktree list 不再包含来源 worktree。
范围边界（Scope Boundaries）
本技能负责：
- 验证调用上下文（在 linked worktree 内部，非 main 分支）
- 确定 main 分支（自动检测；仅在无法确定时询问用户）
- 对当前 worktree 进行预检（工作区是否干净）
- 通过
git worktree list --porcelain 定位主仓库路径
- 通过
git -C 对主仓库执行 pull → --no-ff merge → push
- 遇冲突或推送被拒时移交给用户（不自动解决）
- 可选移除 worktree 及删除功能分支（用户确认，仅
-d）
- 单分支汇总报告
本技能不负责：
- 多 worktree 批量操作（请在主仓库 main 分支上使用
integrate-branches）
- 提交未提交的变更（请先使用
commit-work）
- 合并前的 rebase 或 squash
- 解决合并冲突（遇冲突则停止并提示用户）
- 创建或管理 pull request
- 向任何分支强制推送
转交点：
- →
integrate-branches：用户在主仓库 main 分支上，想一次性落地多个 worktree 时
- 停止并提示用户：在主仓库（非 worktree）调用，或从处于 main 分支的 worktree 调用
- 合并冲突时：停止并指示用户在主仓库手动解决；不处理 worktree
- 推送被拒时：停止并指示用户在主仓库撤销合并（如
git -C <main-repo> reset --hard HEAD~1）、pull 后手动重试
使用场景（Use Cases）
- 开发者在
/repos/myapp-api（worktree，分支 feat/api-v2）刚完成功能，想落地到 main 但不想离开当前目录
- 在 worktree 内运行
commit-work 后，立即交付该单条分支
- IDE / 编辑器会话固定在某个 worktree 目录；用户想交付功能但不想中断当前会话
行为（Behavior）
工作流程（Checklist）
步骤 1 — 验证调用上下文
git rev-parse --git-dir
git rev-parse --git-common-dir
git rev-parse --abbrev-ref HEAD
git rev-parse --show-toplevel
判断上下文：linked worktree 的 git-dir != git-common-dir（per-worktree 的 .git/worktrees/<name> 与共享的 .git 不同）。等价地，linked worktree 中 <toplevel>/.git 是普通文件（gitlink），主仓库中是目录。
记录 <feature-worktree>（= git rev-parse --show-toplevel）与 <feature-branch>（= 当前分支）。
步骤 2 — 确定 main 分支并定位主仓库
git remote show origin | grep 'HEAD branch'
- 结果无歧义（如
HEAD branch: main）→ 直接使用。
- 命令失败或无结果 → 检查
git branch -r 中的 origin/main，再看 origin/master。
- 仍无法确定 → 询问用户：
"无法自动确定 main 分支，请输入 main 分支名称（如 main、master、develop）："
记录 <main-branch>。
从 worktree 列表定位主仓库：
git worktree list --porcelain
解析 porcelain 输出。第一条记录是主仓库（其 worktree 行给出路径）。记录 <main-repo>。完整性校验：<main-repo> != <feature-worktree>。
步骤 3 — 预检：当前 worktree 必须干净
git status --porcelain
若输出非空 → 停止：
"当前 worktree <feature-worktree> 有未提交变更。请先提交（如使用 commit-work）后重新调用。不自动 stash。"
步骤 4 — Pull main、合并功能分支、推送（通过 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>
所有命令的 CWD 始终保持在 <feature-worktree>——git -C 标志驱动主仓库操作，不改变用户位置。
合并冲突时 → 停止：
"合并 <feature-branch> 到 <main-branch> 时发生冲突（主仓库 <main-repo>）。请手动在主仓库解决冲突、完成合并，然后运行 git -C <main-repo> push origin <main-branch>。worktree 未受影响。"
推送被拒（非 fast-forward）时 → 停止：
"合并 <feature-branch> 后推送被拒。请在 <main-repo> 中运行 git reset --hard HEAD~1 撤销合并，然后 git pull，重新合并并手动推送。"
推送成功后，通过 git -C <main-repo> rev-parse <main-branch> 捕获 <merge-commit-hash>。
步骤 5 — 询问用户清理选项
单一提示，三个选项：
"交付完成。worktree <feature-worktree> 和分支 <feature-branch> 如何处理？
[1] 保留 worktree（保持在此，分支保留）
[2] 移除 worktree，保留分支（cd 回主仓库）
[3] 移除 worktree 并删除分支（git branch -d，安全删除）
请选择 1 / 2 / 3："
选项 2 和 3 时，技能输出最终提示，告知用户 cd 到 <main-repo>（技能本身无法改变用户 shell 的 CWD；仅执行 git 命令）。
选项 2 和 3 时，通过 git -C 执行：
git -C <main-repo> worktree remove <feature-worktree>
仅选项 3 时，在 worktree 移除后执行：
git -C <main-repo> branch -d <feature-branch>
仅用 -d——绝不用 -D。若 -d 失败（在成功的 --no-ff 合并后不应出现），上报错误并停止删除（不重试 -D）。
步骤 6 — 汇总报告
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）
输入要求
| 输入 | 是否必需 | 说明 |
|---|
| Worktree 上下文 | 是 | CWD 必须在 linked worktree 内部；在主仓库调用则停止 |
| 非 main 分支 | 是 | 当前分支必须不是 <main-branch>；否则停止 |
| 工作区干净 | 是 | git status --porcelain 必须为空；不自动 stash |
| 清理选项 | 用户输入 | 三选一：保留 / 移除保留分支 / 移除并删除分支 |
| main 分支名 | 自动/询问 | 从 remote 检测；无法确定时询问用户 |
| 网络访问 | 是 | pull 和 push 到 origin 需要网络 |
输出契约
产生（副作用）：
| 元素 | 说明 |
|---|
| Merge commit | 在主仓库 <main-branch> 上恰好产生一条 --no-ff merge commit |
| 远程推送 | origin/<main-branch> 更新一次 |
| Worktree 移除 | 可选，用户选择 |
| 分支删除 | 可选，用户选择；仅 git branch -d |
| 汇总报告 | 单分支表格，含 merge commit hash、推送状态、清理结果，及适用时的后续 cd 提示 |
约束（Restrictions）
硬边界（Hard Boundaries）
- 禁止改变 CWD——所有主仓库操作通过
git -C <main-repo> 完成；用户 shell 始终保持在 worktree
- 禁止强制推送（
--force、--force-with-lease）到任何分支
- 禁止自动 stash 未提交变更——停止并提示用户
- 禁止使用
git branch -D——仅 -d
- 禁止在 merge 与 push 均成功前移除 worktree
- 禁止在主仓库或 main 分支的 worktree 上继续执行——停止并给出对应提示
技能边界（Skill Boundaries）
- 批量合并多个 worktree：在主仓库 main 分支上使用
integrate-branches
- 提交待处理变更：在调用本技能前使用
commit-work
- rebase / squash：在调用本技能前直接使用
git rebase
- 创建 PR：使用平台专用 PR 工具；本技能直接合并到 main
- 代码审查：提交前使用
review-diff；本技能不做代码审查
反模式（Anti-Patterns）
调用上下文
✅ 在 linked worktree 内部、非 main 分支上运行
❌ 不要在主仓库运行——那是 integrate-branches 的职责；从 main 运行时没有当前 worktree 可交付
CWD 纪律
✅ 所有主仓库操作使用 git -C <main-repo>；CWD 保持在 worktree
❌ 不要在技能执行中途 cd <main-repo>——若用户之后移除 worktree，他们期望保持在调用时所在位置，直到选择选项 2/3
预检顺序
✅ 在任何合并尝试前验证工作区干净
❌ 不要先开始合并，再在中途发现脏文件
合并方式
✅ git merge --no-ff 保留分支历史
❌ 不要使用 git merge --squash 或 fast-forward——历史会丢失
清理安全性
✅ 仅在用户明确选择选项 2 或 3、且 merge+push 均成功后才移除 worktree
❌ 不要自动移除 worktree——用户可能还想在那里继续工作
分支删除
✅ 仅在用户明确选择选项 3 时使用 git branch -d（安全）
❌ 绝不使用 git branch -D——可能删除未合并的提交
示例（Examples）
示例 1：正常路径——交付并清理
场景：开发者在 worktree /repos/myapp-api 刚完成 feat/api-v2，想落地并清理。
执行过程：
git rev-parse --git-dir
git rev-parse --git-common-dir
git rev-parse --abbrev-ref HEAD
git rev-parse --show-toplevel
git remote show origin | grep 'HEAD branch'
git worktree list --porcelain
git status --porcelain
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
git -C /repos/myapp worktree remove /repos/myapp-api
git -C /repos/myapp branch -d feat/api-v2
汇总：
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
示例 2：错误上下文——在主仓库调用
场景：开发者在 /repos/myapp 的 main 分支上，习惯性地运行了 deliver-feature。
执行过程：
git rev-parse --git-dir
git rev-parse --git-common-dir
技能停止：
"本技能必须在 linked worktree 内部运行，不能在主仓库中运行。当前位置：/repos/myapp。若要从主仓库批量合并多个 worktree，请使用 integrate-branches。"
未执行任何 git 操作。
示例 3：冲突——停止，不处理 worktree
场景：开发者从 /repos/myapp-api 的 feat/api-v2 运行 deliver-feature。预检通过。合并到 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"
技能停止：
"合并 feat/api-v2 到 main 时发生冲突（主仓库 /repos/myapp）。请手动在主仓库解决冲突、完成合并，然后运行 git -C /repos/myapp push origin main。worktree 未受影响。"
CWD 仍是 /repos/myapp-api。worktree 完好。无推送。无清理。
AI 重构指引（AI Refactor Instruction）
若本技能产生错误行为：
- 执行中 CWD 被改变：若某步骤运行了
cd <main-repo> 或对主仓库使用了非 -C 的 git 命令 → 回退；对所有主仓库操作改用 git -C <main-repo>
- 错误上下文继续执行：若在 CWD 为主仓库时运行了技能（即
git rev-parse --git-dir 等于 git rev-parse --git-common-dir）→ 回退到步骤 1，补充 git-dir vs git-common-dir 比较校验
- 自动 stash 被执行：若任何位置出现了
git stash → 移除；按步骤 3 在脏工作区时停止
- 在推送成功前移除了 worktree：若
git worktree remove 在 git push 返回 0 前执行 → 停止；仅在步骤 4 完成且用户选择选项 2 或 3 后才执行清理
- 尝试强制推送：若任何推送命令中出现
--force 或 --force-with-lease → 替换为标准推送；若被拒，停止并上报
自检清单（Self-Check）
