| name | finish |
| description | 完成当前开发项：撰写 SUMMARY.md，反思跨项目可沉淀流程并可向 claude-code-global 提 issue，关联并关闭 issue（GitHub / GitLab，如有），提交代码 |
| disable-model-invocation | false |
用户调用此 skill 表示当前开发项已完成。
参数处理：先解析并剔除下列收尾开关，剩余 args 才当作用户对本次开发的额外说明（撰写 SUMMARY.md 时融入「局限性」「后续 TODO」「关键设计」等章节；无剩余则按常规总结）。
收尾开关（控制 Step 8，可组合；不带任何开关 = rebase + FF merge + 删 worktree + 删分支 + 删 backup tag 一站到底）：
| 调用 | 8.2 rebase + 备份 tag | 8.3 FF merge | 删 worktree | 删分支 | 删 backup tag |
|---|
/finish（默认） | ✓ | ✓ | ✓ | ✓ | ✓ |
--no-merge / --keep-branch | ✓ | ✗ | ✓ | ✗ | ✗ |
--keep-backup | ✓ | ✓ | ✓ | ✓ | ✗ |
--no-rebase | ✗ | ⚠️ 仅当已可 FF | （随其它开关） | （随其它开关） | （随其它开关） |
各开关做什么以上表为准，下面只说什么时候用它：
--no-merge（同义 --keep-branch）：开发已做完但还不想合入主干（等 review / 等跨仓联调）。worktree 照删 —— 留着它主工作树反而切不到该分支，删掉后 git switch <分支> 即可继续用。--keep-backup：高风险轮想让 backup tag 多留几天兜底。--no-rebase：不想动历史；此时只有分支相对主分支已可 FF 才会 merge，否则停下提示。
开关可组合、语义叠加（--no-merge --keep-backup 与单 --no-merge 等价 —— 后者本就保留 backup tag）。
Step 1 · 撰写 SUMMARY.md
按宪法「总结」部分的要求，在 docs/ 下当前开发项文件夹中撰写 SUMMARY.md（结合 args）。
末尾（「后续 TODO」之后）额外加一段 「## 可沉淀项」：反思本轮有没有值得沉淀成跨项目资产 / 可复用流程的经验，列出来并标注去向（判据见 Step 3）。无则写「暂无」，不留空让人猜。这是本地持久记录，Step 3 据此对跨项目项采取行动。
Step 2 · 扫 SUMMARY 提示「刻意不做」项归档
需求以云端 issue 为单一真源，无本地索引文件。写完 SUMMARY 后扫「局限性」与「后续 TODO」段，问用户：
「上面有没有刻意决定不做的项要归档留痕（避免未来翻老 SUMMARY 误以为是遗漏）？」
用户给出条目 + 原因 → 归档为带 wontfix 的 closed issue（与「issue 是真源」一致、可检索）。二选一：① 用户跑 /backlog 起 issue、三轴之外额外加 wontfix，建完随即 close；② 本步直接建：
python3 $HOME/.claude/scripts/platform_issue.py issue-create \
--title "刻意不做：<一句话>" --body-file /tmp/wontfix.md \
--label wontfix --label type:docs --label area:<Y> --label priority:P2
要往 issue 补材料（验证产物、实测数据、结论回写）时走 helper 的 issue-comment --issue <N> --body-file <F>，不要直调 gh issue comment。
body 写原因 + SUMMARY 路径。wontfix label 缺失先补进 .github/labels.yml 并 sync（三轴 + wontfix 是硬要求，缺则 issue-create 整条失败）。helper 契约（子命令语义、exit code 降级、三轴硬约束）的单一真源是 scripts/platform_issue.md。
用户说「无」→ 跳过。
Step 3 · 跨项目可沉淀流程反思（在任意项目都跑）
开发轮里冒出的「值得复用的重复流程」常散落对话里靠人捡、易错过抽象时机。这里主动反思，对跨项目资产类候选直接向 claude-code-global 跨仓库提 issue。
3.1 候选判据
扫本轮过程（含 Step 1 写的「可沉淀项」段），尽量三条都满足才算，宁缺毋滥控制噪音：跨项目通用（不是本项目特有逻辑）、有具体落点（能指明改哪个 template 字段 / 哪个 skill·hook / 宪法哪段）、≥2 次的模式或明显通用。
最多保留 3 条（按价值排序）。无候选 → 打印「本轮无可沉淀项」，结束本步。
3.2 去向分类
- 跨项目资产 → 跨仓库提 issue 到 claude-code-global（改共享模板，或新增 skill / hook / 写进宪法）
- 仅当前项目可复用 → 文字建议「在本项目跑
/backlog 起本地 issue」，本步不替用户 file
3.3 自指守卫
当前仓库就是 claude-code-global（git rev-parse --show-toplevel == realpath "$HOME/.claude/global-repo"）→ 跨项目候选改为建议走本地 /backlog，不 API 自 file。本步剩余跳过。
3.4 逐条确认（外部可见动作，不自动 file）
对每个跨项目候选逐条问用户：现在提 / 先放一放 / 不提。可只提其中几条；「先放一放」不阻塞 commit。
3.5 对确认要提的候选跨仓库 file
-
派生目标 slug 与 platform（不硬编码，多设备 / 改名都成立）：
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
目录不存在 / URL 取不到 / PLAT 空 → 跳过 file，提示「无法定位 claude-code-global，候选已记在 SUMMARY 可沉淀项段」，不阻塞 finish。
-
选并校验三轴 label：type:* + priority:P2（沉淀项默认排队）+ area:*（读 $GLOBAL_DIR/.github/labels.yml 选最贴的一个）。三轴是硬要求，且选完必须对目标仓库校验三个 label 都真实存在：
python3 "$HOME/.claude/scripts/platform_issue.py" --platform "$PLAT" label-list --repo "$SLUG"
只从该列表挑，不在列表的不要硬塞（为什么必须校验、以及硬塞失败后的补救路径，见 scripts/platform_issue.md「三轴 label 硬约束」）。
-
写临时 body（/tmp/distill-<n>.md）：来源项目名 + 轮次 + 为什么值得沉淀 + 具体落点建议 + 末尾标注「跨项目自动沉淀 issue」。当前项目有 remote 就给回链 URL。
-
调 helper 跨仓库提（--platform "$PLAT" issue-create --repo "$SLUG" + 三轴 label + --body-file），成功则打印返回的 issue URL。
失败兜底（关键）：helper 报错时绝不去掉 --label 重试以求创建成功 —— 那正是历史上产出无 label 裸 issue 的原因（完整推导见 scripts/platform_issue.md）。正确做法是回第 2 步重新校验 / 修正 label，带齐三轴重试；仍无法解决则停下把错误报给用户（候选已记在 SUMMARY，可手动补，不阻塞 finish）。
Step 4 · 识别 issue 关联
读 docs/<本轮编号>-*/PROMPT.md 顶部有没有 > 来自 [#<N> ...](<URL>) 引用块（由 /start <issue#> 写入）。
有 → 提取全部 issue 号与 URL（一轮批量收多个 issue 时每个各一行），传给 /commit 让 message body 自然包含 Closes #N（不嵌 title）。合并到 default branch 时自动关 issue —— 该关键字在 GitHub 与 GitLab 默认分支均原生生效（GitLab 还支持 Fixes / Resolves / Implements 与 cross-project 引用），本 skill 无需平台分支处理。
关多个 issue 时每个都要带自己的关闭关键字、各占一行：
Closes #13
Closes #20
绝不要写成 Closes #13 #20（含逗号的 Closes #13, #20 同样不行）—— 关闭关键字只对紧跟其后的第一个 issue 号生效，后面的会被当成普通引用、不会关闭。这是踩过的坑（一行写四个只关了第一个）。
无 issue 关联（自由描述分支）→ 跳过本步剩余部分。
Step 4.5 · round 编号一致性检查
本轮若经历过 rebase / 历史整理，目标分支可能已占用本地 round 编号，导致 docs 目录编号 与 /commit 将生成的 [round N] 前缀脱节。commit 前逐条核对，命中不一致则给出顺延计划、要求用户确认，绝不静默继续：
docs/<N>-... 目录编号是否需顺延到下一个空位；docs/DEVTREE.md 的 Epic 结构与索引是否随之顺延（本步在 Step 5 /devtree 之前，顺延后 /devtree 会据最新目录重生成）；/commit 将生成的 [round N] 前缀是否与文档目录编号一致；- 顺延如需改写已提交的历史（rename docs 目录 + amend/rebase）→ 明确提示「这会改写历史」，等用户确认才动手；
- 顺延后重跑
git log --oneline / git status 确认三者编号一致再进 Step 5。
三者本就一致 → 打印一行「round 编号一致，无需顺延」直接进 Step 5。
Step 5 · 调用 /devtree
更新开发树 docs/DEVTREE.md。
Step 6 · README review & update
放在 commit 之前，让 README 改动跟本轮代码进同一 commit。命中触发清单则按 references/readme-review.md 执行（触发条件 / 不触发 / 判定数据源 / 子步全在那里）；否则打印一行「README review skipped: 本轮变更不在触发清单」并跳过。
Step 7 · 调用 /commit
提交所有变更（含 SUMMARY.md / DEVTREE.md / README.md）。Step 4 识别到 issue 关联时，把 Closes #N 作为额外上下文传给它，多 issue 按 Step 4 的硬规则各占一行。
/commit 会按当前执行的 Agent 选 Co-authored-by 身份 —— Codex 执行 /finish 时同样不写 Claude 身份，别在 finish 语境下被默认成 Claude。
Step 8 · worktree 收尾
/start 默认在独立 worktree 内开一轮。本步在 /commit 之后自动判断是否在 worktree 内：
[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]
- 不在 worktree（含
--no-worktree 轮）→ 打印一行「non-worktree round，跳过 worktree 收尾」，直接进 Step 9。
- 在 worktree → 读
references/worktree-finish.md 按其 8.1–8.5 执行（诊断 / 备份 + rebase / FF merge / 二次确认清理 / 不自动 push），各开关的跳过分支以上方对照表为准。
Step 9 · 轻量提示
打印一行：
「如果 SUMMARY 里的『后续 TODO』有想真正推进的项，单独跑 /backlog 起 issue。SUMMARY 是回顾文档不是承诺清单，TODO 不必每条都开 issue。」
