Ship It
处理完整的发布生命周期：暂存、提交、推送、创建PR、合并后归档决策记录以及清理。
概述
每次更改都通过分支和PR进行。 永远不要直接推送到main。此技能处理完整的收尾周期，包括合并后的文档归档。
提交消息即文档。 PR标题成为main上的squash-merge提交，并出现在变更日志中。在创建PR时就要正确填写。
合并后归档，绝不提前。 在PR合并之前，规格和计划保持可访问。只有在合并后，我们才将它们转换为紧凑的决策记录。
何时使用
- 用户说"push"、"ship it"、"let's ship"、"open a PR"、"create a PR"
- 在PR打开后，用户说"merged"、"it's merged"、"pull and cleanup"
- 用户已完成实现并希望收尾
- 完成计划后，下一步是提交工作
何时不使用
- 用户明确希望直接推送到main（首先确认这是有意的）
- 仓库未配置远程
- 更改是进行中的工作，用户尚未准备好推送
- 用户只想提交而不发布（请使用
conventional-commits-and-releases）
流程
阶段 0：验证和检测
红色套件永远不能成为PR。 首先运行项目的完整测试套件。如果 有任何失败，报告失败并停止 — 不要提交、推送或创建 PR。此门禁是团队策略，不可委托。
环境检测（普通仓库 vs. 命名分支工作树 vs. 分离HEAD）
以及基础分支确定委托给
superpowers:finishing-a-development-branch，它已经处理了所有三种情况。
以正确的方式检查可用性：在你自己的可用技能列表中查找finishing-a-development-branch。 如果它被列出，则可调用。如果未列出，则不可调用 — 继续执行回退。
不要通过文件系统探测它。
~/.claude/plugins/cache/保存了所有 曾经获取过的版本，包括已安装但禁用的插件， 技能也可以通过插件缓存以外的机制提供。缓存中存在路径 并不能证明你可以调用该技能。
如果可用 — 调用它进行测试验证、环境检测和 基础分支确定，然后在其选项菜单之前停止。
集成决策已由团队规则决定，用户不能在此重新做出： 此项目仅通过PR合并，因为PR是 产生预览部署和CI门禁的方式。它的 “合并回
<base>本地” 选项不可用。它的 “保持分支不变” 选项 仍然有效 — 这是一个推迟的决定，而不是绕过门禁。
如果缺失 — 回退，且不会丢失任何保证正确性的内容：
- 直接运行测试套件。
- 将分支的上游或
main视为基础；在继续之前向用户确认。 - 在阶段6跳过工作树清理；正常删除分支。
阶段 1：暂存和提交
git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "No upstream set"
决策树：
- 在main上且有未提交的更改 → 创建分支、提交、推送、PR
- 在功能分支上且有未提交的更改 → 提交、推送、PR（或更新现有PR）
- 在功能分支上且有未推送的提交 → 推送、PR（或更新现有PR）
- 在功能分支上且有现有PR → 推送（PR已存在）
如果有未暂存的更改：
- 询问用户是否应包含所有更改或特定文件
- 如果更改涉及多个关注点，建议拆分
精心制作提交消息：
| 类型 | 何时使用 |
|---|---|
feat | 新功能 |
fix | 错误修复 |
docs | 仅文档 |
chore | 配置、依赖项、工具 |
refactor | 代码重构，无行为变化 |
test | 添加或修改测试 |
ci | CI/CD 工作流更改 |
格式：<type>[optional scope]: <imperative description>
规则：
- 祈使语气（"add"，而不是 "added" 或 "adds"）
- 冒号后的首单词小写
- 结尾无句号
- 简短（主题50个字符或更少）
- 描述提交做什么，而不是如何做
向用户展示提议的提交消息，并在提交前确认。
阶段 2：分支和推送
如果在main上，创建一个分支：
<type>/<short-description>
示例：
feat/oauth-loginfix/null-response-handlingdocs/release-workflow-permissions
推送：
git push -u origin $(git branch --show-current)
阶段 3：创建PR
PR标题 = 常规提交消息（用于main上的squash-merge）。
PR正文结构：
## 更改内容
[添加/修改/删除的具体描述]
## 原因
[动机 — 这解决了什么问题？]
使用gh CLI创建：
gh pr create --title "<conventional commit message>" --body "<PR body>"
如果 gh 不可用，则从git push输出中提供PR URL或直接构建。
验证预览环境是否已启动。 如果项目为每个PR部署 预览，请等待该工作流并确认环境可达， 然后再交出PR：
gh pr checks --watch
如果预览部署失败，报告它并停止。没有人能审查的PR不算 发布。
此技能停止的位置。 ship-it 的部署感知到此为止，在
预览处。暂存和生产环境的提升不是它的职责 — 它们属于
项目的交付技能（cloud-delivery-aks 或其等价物）。下面的4-6阶段
是git和文档卫生，而不是部署。
阶段 4：等待合并
在PR创建后，询问："合并后告诉我，我会处理清理和归档。"
等待用户确认（例如 "merged"、"done"、"it's merged"）。
阶段 5：合并后 — 归档决策记录
规格和计划设计为详细 — 对人类阅读历史很好，但每次Claude加载时都很昂贵。将它们转换为紧凑的决策记录使关键决策读取成本低廉，而完整的叙述保留在磁盘上归档，除非有人特意打开，否则不花费任何成本。
仅在PR合并后，检查是否有未转换的规格/计划：
ls docs/superpowers/specs/ 2>/dev/null
ls docs/superpowers/decisions/ 2>/dev/null
recording-decisions 技能附带两个助手用于此目的。找到它们 —
该技能可能安装在项目中或全局：
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
如果找到，$d/doc-archive.sh 列出未转换的规格并打印转换提示，$d/index-rebuild.sh 重新生成索引。如果未找到，使用下面的步骤手动执行相同的工作 — 它们是自包含的。
如果存在未转换的规格/计划：
-
询问用户："我找到了可能与此工作对应的规格/计划。是否要将它们转换为紧凑的决策记录并归档原始文件？"
-
如果是，对于每个规格：
- 读取规格内容
- 生成带有YAML前言的决策记录：
--- title: <从规格中提取> date: <从规格文件名> component: <从内容推断> status: implemented supersedes: null dependencies: [<推断>] --- - 编写约30-50行，捕获：关键决策、接口、约束
- 保存到
docs/superpowers/decisions/<date>-<topic>.md - 将原始规格移动到
docs/superpowers/archive/specs/ - 将匹配的计划移动到
docs/superpowers/archive/plans/
-
重新构建主索引 — 从每个决策记录的前言重新生成
docs/superpowers/index.md，分组为活跃决策表（组件、标题、日期、依赖项）和已取代表（组件、标题、被取代者）。如果之前找到了$d/index-rebuild.sh，运行它；否则直接写入文件。 -
提交归档：
git add docs/superpowers/ git commit -m "docs: archive specs and update decision index" git push
阶段 6：清理
git checkout main
git pull
git branch -d <branch-name>
git push origin --delete <branch-name> 2>/dev/null || true
git fetch --prune
验证干净状态：
git branch --show-current
git log --oneline -3
如果工作发生在git工作树中，将拆卸委托给
superpowers:finishing-a-development-branch（其基于来源的清理 —
它知道它拥有哪些工作树，并保留外部管理的工作树）。
如果该技能不可用，使用 git worktree remove <path> 手动移除工作树，并首先向用户确认。
关键原则
- 红色套件永远不能成为PR — 先验证（阶段0）
- 永远不要直接推送到main — 始终分支 + PR。PR就是预览 部署和CI门禁；本地合并会跳过两者。这会覆盖任何 提供在本地合并作为选项的工作流。
- 发布在预览处结束 — 合并、归档和清理是卫生操作；提升到暂存和生产环境是单独技能的职责
- 常规提交 — PR标题就是变更日志条目
- 仅在合并后归档 — 规格在审查期间保持可访问
- 决策记录紧凑 — 约30-50行，YAML索引，LLM优化
- 完全清理 — 不留陈旧分支或跟踪引用