| name | finish |
| description | 完成当前开发项：撰写 SUMMARY.md，反思跨项目可沉淀流程并可向 claude-code-global 提 issue，关联并关闭 issue（GitHub / GitLab，如有），提交代码 |
| disable-model-invocation | false |
用户调用此 skill 表示当前开发项已完成。
参数处理：调用时可能附带参数（args）。先解析并剔除以下收尾开关，剩余 args 才当作用户对本次开发的额外说明（撰写 SUMMARY.md 时融入对应章节，如「局限性」「后续TODO」「关键设计」；若剔除开关后无剩余则按常规总结）。
收尾开关（控制 Step 8 worktree 收尾行为，可组合；默认不带任何开关 = rebase + FF merge + 删 worktree + 删分支 + 删 backup tag 一站到底）：
--no-merge（同义词 --keep-branch）：rebase 让分支线性，但不 FF merge 到主分支；worktree、分支、backup tag 全保留。用于发包 / 外审前想先留分支等 review、或本轮想继续迭代的场景。--keep-backup：正常 FF merge + 清理 worktree / 分支，但保留 backup tag（高风险轮想多保几天兜底）。--no-rebase：跳过 8.2 的 rebase（与备份 tag）；更激进的可选项，仅在「分支相对主分支已可 FF」时仍能 merge，否则停下提示用户先 rebase 或加 --no-merge。
各开关行为对照见 Step 8 顶部对比表。
执行以下步骤：
Step 1：撰写 SUMMARY.md
按全局 CLAUDE.md「总结」部分的要求，在 docs/ 下当前开发项文件夹中撰写 SUMMARY.md（结合参数内容）。
SUMMARY 末尾（「后续 TODO」之后）额外加一段 「## 可沉淀项」：反思本轮过程中有没有值得沉淀成跨项目资产 / 可复用流程的经验，列出来并标注去向（见 Step 3 的判定标准与去向分类）。无则写「暂无」，不留空让人猜。这是本地持久记录，Step 3 据此对跨项目项采取行动。
Step 2：扫 SUMMARY 提示「刻意不做」项归档
需求以云端 issue 为单一真源，无本地索引文件。写完 SUMMARY 后，扫「局限性」与「后续 TODO」段，问用户：
「上面有没有刻意决定不做的项要归档留痕（避免未来翻老 SUMMARY 误以为是遗漏）？」
- 用户给出条目 + 原因 → 归档为带
wontfix label 的 closed issue（与「issue 是真源」一致、可检索）。二选一：① 用户跑 /backlog 起 issue、选完三轴额外加 wontfix，建完随即 close；② 本步直接 issue-create --title "刻意不做：<一句话>" --body-file /tmp/wontfix.md --label wontfix --label type:docs --label area:<Y> --label priority:P2（body 写原因 + SUMMARY 路径），建完 gh issue close <N> -r "not planned" / glab issue close <N>。wontfix label 缺失先补进 .github/labels.yml 并 sync（三轴 + wontfix 是硬要求，缺则 issue-create 整条失败）。label 契约见 ~/.claude/scripts/platform_issue.md。
- 用户说「无」→ 跳过
Step 3：跨项目可沉淀流程反思（在任意项目都跑）
本步价值：开发轮里冒出的「值得复用的重复流程」常散落对话里靠人捡、易错过抽象时机。这里主动反思，对跨项目资产类候选直接向 claude-code-global 跨仓库提 issue（独立于当前项目、无索引耦合），不靠事后回忆。
3.1 反思候选 + 判定标准
扫本轮过程（含 Step 1 写的「可沉淀项」段），按标准挑候选——尽量三条都满足才算，宁缺毋滥控制噪音：
- 跨项目通用：不是本项目特有逻辑；
- 有具体落点：能指明改哪个 template 字段 / 哪个 skill·hook / GLOBAL_AGENTS.md 哪段；
- ≥2 次的模式，或明显通用。
最多保留 3 条（按价值排序取 top 3）。无候选 → 打印「本轮无可沉淀项」，结束本步。
3.2 候选去向分类
- 跨项目资产 → 跨仓库提 issue 到 claude-code-global：
- 改
~/.claude/templates/ 下的共享模板；
- 在 claude-code-global 里新增 skill / hook / 写进
GLOBAL_AGENTS.md。
- 仅当前项目可复用 → 文字建议「在本项目跑
/backlog 起本地 issue」，本步不替用户 file。
3.3 自指守卫
若当前仓库就是 claude-code-global（git rev-parse --show-toplevel == realpath "$HOME/.claude/global-repo"）→ 跨项目资产候选改为建议走本地 /backlog（遵循本项目「issue 即单一真源」约定），不 API 自 file。本步剩余跳过。
3.4 逐条确认（外部可见动作，不自动 file）
对每个跨项目候选，逐条用 AskUserQuestion 问用户：现在提 / 先放一放 / 不提。逐条决策、可只提其中几条；「先放一放」不阻塞 commit。
3.5 对确认要提的候选，跨仓库 file
-
派生目标 slug + platform（不硬编码，多设备/改名都成立；install.sh 把本仓库软链为 ~/.claude/global-repo）：
GLOBAL_DIR="$HOME/.claude/global-repo"
URL=$(git -C "$GLOBAL_DIR" remote get-url origin)
SLUG=$(printf '%s' "$URL" | sed -E 's#\.git$##; s#^git@[^:]+:##; s#^https?://[^/]+/##')
case "$URL" in *github.com*) PLAT=github ;; *gitlab*) PLAT=gitlab ;; *) PLAT="" ;; esac
$GLOBAL_DIR 不存在 / URL 取不到 / PLAT 空 → 跳过 file，提示「无法定位 claude-code-global，候选已记在 SUMMARY 可沉淀项段，可手动提 issue」，不阻塞 finish。
-
选并校验三轴 label：type:*（feat/refactor/docs）+ priority:P2（沉淀项默认排队）+ area:*——读 $GLOBAL_DIR/.github/labels.yml 在 install/skill/hook/template/doc 里选最贴的一个。三轴是硬要求。选完对目标仓库校验三个 label 都真实存在（labels.yml 未必已同步到远端，二者可能脱节）：
python3 "$HOME/.claude/scripts/platform_issue.py" --platform "$PLAT" label-list --repo "$SLUG"
只从该列表挑；不在列表的不要硬塞（会让 issue-create 整条失败），改选已存在的同轴 label，或先 label-sync-from-file 同步后再校验。
-
写临时 body（/tmp/distill-<n>.md）：来源项目名 + 轮次 + 为什么值得沉淀（重复性/通用性）+ 具体落点建议 + 末尾标注「跨项目自动沉淀 issue」。当前项目有 remote 就给回链 URL，否则写项目目录名。
-
调 helper 跨仓库提：
python3 "$HOME/.claude/scripts/platform_issue.py" --platform "$PLAT" \
issue-create --repo "$SLUG" \
--title "<标题>" --body-file /tmp/distill-<n>.md \
--label type:<X> --label area:<Y> --label priority:P2
成功则打印返回的 issue URL 给用户。
失败兜底（关键）：若 helper 报错（如某 label 在目标仓库不存在导致 gh/glab 整条失败），绝不去掉 --label 重试以求创建成功——那正是历史上产出无 label 裸 issue（如 #12）的原因。正确做法：按 step 2 重新校验/修正 label（改选已存在的，或先 label-sync-from-file），带齐三轴重试；若仍无法解决，停下把错误报给用户，候选已记在 SUMMARY 可沉淀项段、可手动补，不阻塞 finish。
Step 4：识别 issue 关联
读 docs/<本轮编号>-*/PROMPT.md 顶部，看是否有 > 来自 [#<N> ...](<URL>) 引用块（由 /start <issue#> 写入）：
Step 4.5：round 编号一致性检查
/commit 会从 round<N>- 分支名或 docs/<N>-*/ 目录推断 [round N] 前缀。若本轮经历过 rebase / 历史整理，目标分支可能已占用本地 round 编号，导致 docs 目录编号 与 生成的 commit round 脱节。commit 前逐条核对，命中不一致则给出顺延计划、要求用户确认，绝不静默继续：
触发条件：目标分支已占用当前开发轮的本地 round 编号，或整理历史后发现 docs round 与将生成的 commit round 不一致。
docs/<N>-... 目录编号是否需要顺延到下一个空位。docs/DEVTREE.md 的 Epic 结构、可视化与节点索引是否随之同步顺延（本步在 Step 5 /devtree 之前，顺延后 /devtree 会据最新目录重生成）。/commit 将生成的 [round N] 前缀是否与文档目录编号一致。- 顺延如需改写已提交的历史（rename docs 目录 + amend/rebase commit）→ 明确提示「这会改写历史」，等用户确认后才动手。
- 顺延后重新跑
git log --oneline、git status 与必要的文档检查，确认 docs 目录、DEVTREE.md、commit 前缀三者编号一致，再进 Step 5。
三者本就一致（未经历 rebase 冲突，或编号无撞车）→ 打印一行「round 编号一致，无需顺延」，直接进 Step 5。
Step 5：调用 /devtree
调用 /devtree 更新开发树（docs/DEVTREE.md）。
Step 6：README review & update
放在 commit 之前，让 README 改动跟本轮代码进同一 commit。命中触发清单则按 references/readme-review.md 执行（触发条件 / 不触发 / 判定数据源 / 子步全在那里）；否则打印一行「README review skipped: 本轮变更不在触发清单」并跳过。
Step 7：调用 /commit
调用 /commit 提交所有变更（包括 SUMMARY.md / DEVTREE.md / README.md 的变化）。
/commit 会按当前执行的 Agent 选择 Co-authored-by 身份（CC → Claude、Codex → OpenAI Codex，详见 /commit 第 8 步与全局 CLAUDE.md「git 规则」）—— Codex 执行 /finish 收尾时同样不写 Claude 身份，不要在 finish 语境下被默认成 Claude。
关键：如果 Step 4 识别到 issue 关联，把 Closes #N 作为额外上下文传给 commit skill —— 让生成的 commit message body 自然包含 Closes #N（不嵌 title）。多 issue 按 Step 4 硬规则各占一行、各带关键字，不能一行写 Closes #13 #20。
Step 8：worktree 收尾
/start 默认在独立 worktree 内开一轮（见 /start skill）。本步在 /commit 之后自动判断是否在 worktree 内，是则一站式完成「rebase → FF merge → 清理」，免去手工三步走。
先检测是否在 linked worktree 内：
[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]
- 不在 worktree（两者相等，含
--no-worktree round）→ 打印一行「non-worktree round，跳过 worktree 收尾」，直接进 Step 9。
- 在 worktree → 按下方收尾开关对照表决定流程。
收尾开关对照表（开关来自 ARGUMENTS 解析，✓=执行 / ✗=跳过保留）：
| 调用 | 8.2 rebase + 备份 tag | 8.3 FF merge | 8.4 删 worktree | 8.4 删分支 | 8.4 删 backup tag |
|---|
/finish（默认） | ✓ | ✓ | ✓ | ✓ | ✓ |
--no-merge / --keep-branch | ✓ | ✗ | ✗ | ✗ | ✗（保留） |
--keep-backup | ✓ | ✓ | ✓ | ✓ | ✗（保留） |
--no-rebase | ✗ | ⚠️ 仅当已可 FF | （随其它开关） | （随其它开关） | （随其它开关） |
开关可组合，语义叠加（如 --no-merge --keep-backup 与单 --no-merge 等价——后者本就保留全部）。各分支的具体动作见 8.3 / 8.4。
收尾流程遵循 /rebase skill 的核心原则（FF-only、备份 tag、冲突逐文件解、abort 兜底、分段确认），但不调用 /rebase skill —— 因 /rebase 阶段 3 的 git checkout <主分支> 在 worktree 下必失败（主分支已被主工作树占用），FF merge 须改用 git -C <主工作树> merge。
8.1 诊断
展示 git worktree list、git branch --show-current、git status（应干净，/commit 刚跑完）、git log --graph --oneline -15。
探测主分支：git symbolic-ref --short refs/remotes/origin/HEAD（得 origin/master → 取末段）；失败则本地探测 main / master。
算主工作树路径：dirname "$(git rev-parse --path-format=absolute --git-common-dir)"。
前置检查：当前分支不能就是主分支；工作区必须干净。任一不满足 → 停下问用户。
8.2 备份 + rebase
--no-rebase：跳过本整节（不打备份 tag、不 rebase），直接进 8.3。后续 8.3 仅在分支相对主分支「已可 FF」时才合并，否则停下提示。
- 备份 tag：
git tag backup/<分支名>-$(date +%Y%m%d-%H%M)，告诉用户「搞砸了用 git reset --hard <该 tag> 回退」。
- rebase：
git rebase <主分支>。
- 无冲突 → 展示
git log --graph --oneline -10，停下等用户确认后进 8.3。
- 有冲突（finish 跑过
/devtree，DEVTREE.md 几乎必与主分支并行进度撞车）→ git status 列冲突文件，逐个解、逐个 git add，再 git rebase --continue；后续 commit 续冲突则重复。冲突时暂停让用户解，不自动跳过；随时可 git rebase --abort + 备份 tag 兜底。解完展示 graph，停下等用户确认。
8.3 FF merge 到主分支
--no-merge / --keep-branch：跳过本节与 8.4，改走 8.4-skip（见下），把 worktree / 分支 / backup tag 全保留并打印其位置。
主分支 checkout 在主工作树，当前 worktree 不能 git checkout 它，故用 -C 在主工作树内合并：
git -C <主工作树> merge --ff-only <当前分支>
若 --ff-only 失败（主分支在本轮期间又前进）→ 回到 8.2 把当前分支继续 rebase 到最新主分支，再重试（--no-rebase 下不能自动 rebase → 停下提示用户去掉 --no-rebase 重跑或手动 rebase）。禁止 fallback 普通 merge。
8.4 二次确认 + 清理
向用户明确列出将删除的项，等用户确认（销毁性动作）。--keep-backup 时 backup tag 不在删除列表里、保留。
-
用户确认 → 先 cd <主工作树>（当前 cwd 即将随 worktree 一起消失），再依次执行：
git worktree remove <当前 worktree 路径>
git branch -d <当前分支>
git tag -d backup/<分支名>-<时间戳>
若 git worktree remove 失败（IDE / 编辑器占用 worktree 内文件）→ 给清晰提示「请关闭打开该目录的编辑器后重试」，不加 --force 硬删，保留全部状态。
-
用户拒绝 → 保留 worktree / 分支 / backup tag 全部状态，打印当前状态，结束。
8.4-skip（--no-merge / --keep-branch 专用）
不 merge、不删除任何东西。打印三项的保留位置供用户后续手动处理：
本轮已 commit + SUMMARY 就位，按 --no-merge 保留：
worktree : <当前 worktree 路径>
分支 : <当前分支>（已 rebase 到 <主分支>，线性可后续 FF）
backup : backup/<分支名>-<时间戳>
后续可：① 让人 review / 提 PR；② 继续在此 worktree 迭代；③ 准备好后手动 git -C <主工作树> merge --ff-only <当前分支> 并清理。
然后直接进 Step 9（跳过 8.5 的 push 提示——主分支未前进）。
8.5 不自动 push
打印一行提示：主分支已 FF 前进，是否 git push 由用户决定（与 finish 不自动 push 的约定一致）。
Step 9：轻量提示
收尾打印一行：
「如果 SUMMARY 里的「后续 TODO」有想真正推进的项，单独跑 /backlog 起 issue。SUMMARY 是回顾文档不是承诺清单，TODO 不必每条都开 issue。」
