lguidolin/ship-it

Ship It

處理完整的交付生命週期：暫存、提交、推送、開啟 PR、合併後歸檔決策記錄並清理。

概述

每次變更都經過分支和 PR。 絕不直接推送到 main。此技能處理完整的收尾循環，包括合併後的文件歸檔。

提交訊息即文件。 PR 標題會成為主分支上的 squash-merge 提交，並顯示在變更日誌中。在建立 PR 時就必須寫對。

合併後才歸檔，絕不提前。 規格和計劃在 PR 合併前保持可讀。只有合併後，我們才將其轉換為簡潔的決策記錄。

使用時機

• 使用者說「推送」、「ship it」、「我們交付吧」、「開 PR」、「建立 PR」
• 使用者在 PR 已開啟後說「已合併」、「合併了」、「拉取並清理」
• 使用者已完成實作並想結束工作
• 在完成計劃後，下一步是提交成果

不應使用時機

• 使用者明確想要直接推送到 main（請先確認這是故意的）
• 倉儲未設定遠端來源
• 變更還在進行中，使用者尚未準備好推送
• 使用者只想提交而不交付（請使用 conventional-commits-and-releases）

流程

階段 0：驗證與偵測

紅燈測試套件不得變成 PR。 先執行專案的完整測試套件。如果任何測試失敗，回報失敗並停止 — 不要提交、推送或開啟 PR。此關卡是團隊政策，不可委託。

環境偵測（一般倉儲 vs. 命名分支 worktree vs. detached HEAD）和基礎分支確定委託給 superpowers:finishing-a-development-branch，該技能已處理所有三種情況。

以正確方式檢查可用性：在您自己的可用技能清單中尋找 finishing-a-development-branch。 如果它出現在清單中，則可被呼叫。如果不在清單中，則不可 — 繼續使用備用方案。

不要探測檔案系統來尋找它。~/.claude/plugins/cache/ 儲存了所有曾經擷取的版本，包括已安裝但已停用的外掛，而且技能也可以透過其他機制提供。快取中某個路徑的存在並不能證明您可以呼叫該技能。

如果可用 — 呼叫它進行測試驗證、環境偵測和基礎分支確定，然後在其選項選單前停止。

整合決策已由團隊規則決定，使用者無需重新決定：此專案僅透過 PR 合併，因為 PR 產生了預覽部署，並且是 CI 的關卡。其「在本機合併回 <base>」選項不可用。其「保持分支不變」選項仍然有效 — 這是推遲的決定，而不是繞過關卡。

如果不可用 — 使用備用方案，並且不會遺漏任何影響正確性的東西：

• 直接執行測試套件。
• 將分支的上游或 main 視為基礎；在繼續之前與使用者確認。
• 跳過階段 6 的 worktree 清理；正常刪除分支。

階段 1：暫存與提交

git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "未設定上游"

決策樹：

• 在 main 上且有未提交的變更 → 建立分支、提交、推送、PR
• 在功能分支上且有未提交的變更 → 提交、推送、PR（或更新現有 PR）
• 在功能分支上且有未推送的提交 → 推送、PR（或更新現有 PR）
• 在功能分支上且有現有 PR → 推送（PR 已存在）

如果有未暫存的變更：

• 詢問使用者是否應包含所有變更或特定檔案
• 如果變更涉及多個關注點，建議拆分

撰寫提交訊息：

類型	使用時機
feat	新功能
fix	錯誤修正
docs	僅文件
chore	設定、依賴、工具
refactor	程式重構，無行為變更
test	新增或修改測試
ci	CI/CD 工作流程變更

格式：<類型>[可選範圍]: <祈使句描述>

規則：

• 祈使語氣（使用「add」，而不是「added」或「adds」）
• 冒號後小寫開頭
• 結尾無句號
• 簡短（主旨 50 字元以內）
• 描述提交做了什麼，而不是如何做

提交前將建議的提交訊息呈現給使用者並確認。

階段 2：分支與推送

如果在 main 上，建立一個分支：

<類型>/<簡短描述>

範例：

• feat/oauth-login
• fix/null-response-handling
• docs/release-workflow-permissions

推送：

git push -u origin $(git branch --show-current)

階段 3：開啟 PR

PR 標題 = 常規提交訊息（用於 main 上的 squash-merge）。

PR 主體結構：

## 變更內容

[新增/修改/移除的具體描述]

## 原因

[動機 — 這解決了什麼問題？]

使用 gh CLI 建立：

gh pr create --title "<常規提交訊息>" --body "<PR 主體>"

如果 gh 不可用，請提供 git push 輸出中的 PR URL 或自行建構。

驗證預覽環境已啟動。 如果專案會為每個 PR 部署預覽，請等待該工作流程完成並確認環境可訪問，然後再交出 PR：

gh pr checks --watch

如果預覽部署失敗，請回報並停止。沒有人可以審查的 PR 不算交付。

此技能在此停止。 ship-it 的部署意識止於預覽。暫存和正式環境的升級不是它的職責 — 它們屬於專案的交付技能（cloud-delivery-aks 或其等效技能）。下面的階段 4-6 是 git 和文件的衛生維護，而不是部署。

階段 4：等待合併

建立 PR 後，詢問：「合併後請告訴我，我會處理清理和歸檔。」

等待使用者確認（例如，「已合併」、「完成了」、「合併了」）。

階段 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 會重新產生索引。如果沒找到，請使用下面的步驟手動完成相同的工作 — 這些步驟是自包含的。

如果存在未轉換的規格/計劃：

1. 詢問使用者：「我發現可能與此工作對應的規格/計劃。要將它們轉換為簡潔的決策記錄並歸檔原始檔案嗎？」

2. 如果同意，對於每個規格：

   • 讀取規格內容
   • 產生一個帶有 YAML 前端資料的決策記錄：

     ---
     title: <從規格中提取>
     date: <從規格檔案名稱取得>
     component: <從內容推斷>
     status: implemented
     supersedes: null
     dependencies: [<推斷>]
     ---
     

   • 撰寫約 30-50 行，包含：關鍵決策、介面、約束條件
   • 儲存到 docs/superpowers/decisions/<日期>-<主題>.md
   • 將原始規格移動到 docs/superpowers/archive/specs/
   • 將對應的計劃移動到 docs/superpowers/archive/plans/

3. 重新建立主索引 — 根據每個決策記錄的前端資料重新產生 docs/superpowers/index.md，分組為有效決策表格（元件、標題、日期、依賴）和已取代表格（元件、標題、由誰取代）。如果您之前找到了 $d/index-rebuild.sh 請執行它；否則直接撰寫檔案。

4. 提交歸檔：

   git add docs/superpowers/
   git commit -m "docs: 歸檔規格並更新決策索引"
   git push
   

階段 6：清理

git checkout main
git pull
git branch -d <分支名稱>
git push origin --delete <分支名稱> 2>/dev/null || true
git fetch --prune

驗證乾淨狀態：

git branch --show-current
git log --oneline -3

如果工作是在 git worktree 中完成的，請將拆除工作委託給 superpowers:finishing-a-development-branch（其基於來源的清理 — 它知道哪些 worktree 是自己擁有的，並會保留外部管理的 worktree）。如果該技能不可用，請使用 git worktree remove <path> 手動移除 worktree，並先與使用者確認。

關鍵原則

• 紅燈測試套件不得變成 PR — 在其他任何操作之前先驗證（階段 0）
• 絕不直接推送到 main — 始終分支 + PR。PR 就是預覽部署和 CI 關卡；本地合併會跳過這兩者。這會覆蓋任何提供本地合併選項的工作流程。
• 交付止於預覽 — 合併、歸檔和清理是衛生維護；升級到暫存和正式環境是另一個技能的職責
• 常規提交 — PR 標題就是變更日誌條目
• 只有合併後才歸檔 — 規格在審查期間保持可讀
• 決策記錄是簡潔的 — 約 30-50 行，YAML 索引，LLM 最佳化
• 完全清理 — 不留陳舊分支或追蹤引用