elf-linear-superpowers

# Linear × superpowers 生命週期 > **正本在 Linear。** 本 skill 是 Linear 團隊文件的執行摘要，兩邊衝突時以 Linear 文件為準，並提醒使用者更新本 skill。 > > | 文件 | 內容 | > |---|---| > | 開發流程規範：Spec／Plan × superpowers | 本流程的完整規範 | > | 流程總覽（給所有 AI）：從開單到收尾 | 步驟總表、狀態對照、八條鐵則、接手判斷 | > | 隊友規範：角色、命名與回報 | 統籌與 subagent 的角色、命名、回報 | > | 分支規範：三種 repo 類型 | 分支用途、命名、發佈、hotfix、git-guard | > | 流程：維運單 | 不改 repo 的維運工作 | > | Linear 巡檢規則 | 可自動檢查的規則 R1–R13、W1–W6 | > > 版本：2026-10-20 核准稿（對齊 superpowers v7.0.0；Linear 正本於發版時依核准稿更新） Linear 是規格與計畫的唯一來源（single source of truth）。superpowers 各 skill 照常執行，但**產出寫進 Linear issue，不寫 `docs/superpowers/specs/`、`docs/superpowers/plans/` 檔案**（除非使用者明確要求另存）。superpowers 允許使用者偏好覆蓋這兩個預設位置。 本機副本只有兩種，都不是正本：步驟 1 實作者檢查用的 Spec 暫存檔（檢查完刪除），以及步驟 4 開工時匯出到 worktree `.superpowers/sdd/` 的 Plan 與 Spec，給 superpowers 的 ledger、task brief 與審查包使用（見步驟 4）。匯出檔不進版控；與 Linear 不一致時以 Linear 為準，重新匯出。階段 Guard 另用兩個小檔，只記單號與核准，也不是正本：步驟 3 核准後由留下核准的審計員依 Linear 核准留言用核准憑證建立器建立的核准憑證、步驟 2 建的狀態檔；計畫有沒有核准，以 Plan 上的「計畫已核准」留言為準，Linear 留言是核准的唯一正本，憑證只是讓 Guard 讀得到的快取。 每個步驟結束時，都要把結果回寫到對應的 Linear 單（改狀態、勾 checkbox 或留言），不能只停留在對話裡。讀不到 Linear MCP 時先告訴使用者，不要改寫到本地檔案。 ## 與上游 superpowers 的分工 本 skill 對齊 obra/superpowers **v7.0.0**（2026-10-09）。superpowers 的流程行為以上游為準，本 skill 只補上游沒有的部分：Linear 紀錄、分支與發版規則、稽核留痕。本 skill 是團隊規範，等同使用者指示；上游 `using-superpowers` 規定使用者指示優先於 skill，所以兩者衝突時以本 skill 為準。**本 skill 覆蓋上游的地方全部列在下表，表外一律照上游做**。本 skill 對上游做法的轉述（四種停止條件、模型級別、5 項自審等）都是摘要，以上游原文為準。 | 上游預設 | 本團隊改為 | 原因 | |---|---|---| | brainstorming 把設計寫進 `docs/superpowers/specs/`；writing-plans 把計畫寫進 `docs/superpowers/plans/` | 寫進 Linear 的 Spec、Plan；步驟 4 才匯出本機副本 | Linear 是唯一來源，稽核可追溯 | | 快速、明確的小事直接做 | 只要會 commit 到 repo，就開單一開發工作單，兩道保險不省略 | 每個變更都要有工作單與證據 | | 使用者說跳過提問直接做時，brainstorming 結束、HARD-GATE 一併解除 | 跳過的只是訪談；仍要開單（Spec／Plan 或單一開發工作單），Spec／Plan 仍要定案、審計員核准，兩道保險不省略 | 每個變更都要有工作單與證據 | | 使用者同意的 spike 可以直接做，不寫測試、跳過計畫與審查 | spike 只在拋棄式 worktree 裡做（不用 Plan 的 worktree：spike 的 commit 會混進開發分支；也不為了 spike 建核准憑證），不 commit 進開發分支、不開 PR；要留下成果就另開單 | 拋棄式探索不進 repo | | 設計核准後下一步只能是 writing-plans；writing-plans 說 worktree 在執行時才建 | Spec 定案後**先寫 Plan**；取得「計畫已核准」留言、核准憑證 `verify` 通過、相依條件（blocked by 的單都已合進 `dev`）確認後，才走步驟 2 建 worktree（分支用 Plan 編號、基線測試留言、Orca 連單、狀態檔） | Guard 在本 Plan 的 worktree 建立前沒有保護對象：主目錄的分支不是 Guard 認得的格式，判斷順序第 5 條一律放行，核准前不在主目錄寫實作檔靠 elf-team-rule 規則 31 與步驟 3 第 1 項，不是靠狀態檔。核准前先建分支與狀態檔，只是讓一條還不確定要不要做的分支先存在，計畫被退回時還要回頭清掉（E-423 審計，2026-10-25） | | 計畫在對話裡核准 | 審計員在 Plan 留言「計畫已核准（YYYY-MM-DD，審計員：<模型>）」才算核准 | 對話不留紀錄 | | using-git-worktrees 優先用原生 worktree 工具 | 不用 `EnterWorktree` 建 worktree（它只建在 repo 內）；用 `git worktree add` 建在 repo 外同層（規則 31），再切進去（見步驟 2） | 不碰主目錄 | | 計畫和實際不符時只有四種情況停下來 | 另加兩種：需要改規格（裁決不能改 Spec）；elf-team-rule 規則 13 列的 git 停止條件（`--ff-only` 失敗、衝突、push 被拒等），一律照規則 13 停下，不適用裁決制 | 規格變更要使用者核准；git 異常一律先回報 | | 最終審查後殘留的問題，到 finishing-a-development-branch 列選項時才告訴使用者 | 殘留的 Critical 不進步驟 6：先在 Plan 留言列出，由使用者決定修或停 | 驗證與發版前先處理嚴重問題 | | finishing-a-development-branch 選單有「本地合併」 | 開發分支只開 PR 合進 `dev`；本地合併只用於規則 18、26 的情況 | 分支規範 | | 使用者打字 `discard` 後，finishing-a-development-branch 執行 `git branch -D` 與 `git worktree remove` | `discard` 只改 Linear 狀態（Plan → 已取消，見步驟 7），不刪分支，也不移除 worktree；要刪由 Eddie 個案決定並自己刪，AI 不刪、不給刪除指令（規則 19「已取消的 Plan」） | 刪除不可逆，已取消的 Plan 沒有發版證據可核對（E-391，Eddie 2026-10-25 決定） | | subagent-driven-development 收尾段在最終審查後用 `rm -rf <工作區>` 刪除工作區 | 不刪：`.superpowers/sdd/E-<Plan 編號>-plan/` 保留，隨 worktree 由清理實作者的 `release-cleanup` 移除（規則 36）；最終審查後只在 Plan 留言「Rulings I made」總表 | 發版前還可能回頭修正（步驟 6、PR 審查後），ledger 要留著；session 自己刪除沒有第二個角色核對（E-425，Eddie 2026-10-28 決定） | | 裁決（Ruling）記在 ledger，收尾時在對話回報 | 每個 Task 完成時把該 Task 的裁決原文留言到 Plan；最終審查後再留一則「Rulings I made」總表 | ledger 不進版控、會隨 worktree 由 `release-cleanup` 移除；session 中斷時 Linear 仍有紀錄 | 另有幾項是團隊另加的限制，上游沒有規定、也不衝突：單一 Plan 的 Task 建議 3–5 個、超過 10 個必拆（elf-team-rule 規則 16）；工作量大時在同一個 Spec 底下增加 Plan（規則 17）；超出 Spec 的需求不裁決（見步驟 4）；並行的問題調查同時最多兩條線；計畫可以交給計畫撰寫隊友寫（見隊友表）；階段 Guard（E-377，Claude Code 的 hook）在核准失效（「計畫已修改 vN」或「核准撤回」使憑證被 `revoke`）或本機還沒有憑證時，擋檔案工具寫 repo 裡 `docs/superpowers/` 以外的檔案，靠步驟 2 的狀態檔與步驟 3 第 9 項的核准憑證運作（憑證由留下核准的審計員依 Linear 核准留言用建立器建立，實作者只 `verify`；Linear 留言是唯一正本、憑證只是快取），說明見 skillshare-source 的 `docs/superpowers/guard.md`。 更新 superpowers（`skillshare update _superpowers`）前先讀上游 `RELEASE-NOTES.md`；行為有變動就開單同步本 skill 與團隊範本，同步後更新本節的版本。 ## 先分流：走哪條路 | 這件事… | 走 | |---|---| | 要 commit 到 repo，且需要設計 | 本 skill 的 Spec／Plan 流程 | | 要 commit 到 repo，但不需要設計（明確錯誤修正、緊急修正、小型改善） | 單一開發工作單（仍要兩道保險） | | 不 commit 到 repo（備份、AG 複寫、網路、主機、憑證、帳號、稽核佐證） | **維運單**（見文末「維運單」） | | 不確定要不要設計 | 先開 Spec，用 brainstorming 談。brainstorming 判斷為快速小事或小變更時：**先**把 Spec 改為已取消、**再**改 Plan（子單先關可能觸發父單自動改為已取消），各留言「規模判斷：小變更，改開 E-xxx」，另開單一開發工作單，把對話中講定的做法寫進「修正方式」 | 同一件事兩者都有時拆兩張：先開維運單把事情做掉，工具化另開 Spec／Plan。 單一開發工作單用的上游 skill：using-git-worktrees（照步驟 2 建在 repo 外同層，分支用該單編號，不建狀態檔；這種單沒有計畫核准這一關，開單後就可以建 worktree）→ 錯誤類先用 systematic-debugging 找出根因 → test-driven-development → requesting-code-review（照上游的審查範本派全新審查者，明確指定最強模型審整個分支；`BASE_SHA` 用 `git merge-base origin/dev HEAD`，hotfix 用 `origin/release`，不用上游範例的 `main`；沒有計畫檔，不用 `review-package`）→ receiving-code-review（逐項處理並留言）→ verification-before-completion → finishing-a-development-branch。不匯出、沒有 ledger：審查結果、延後的 Minor、決定不修的理由直接留言到該單。改到 skill 的單，另照步驟 3 的 writing-skills 做法先跑壓力情境再改。 ## Linear 設定（ELF EXPRESS 團隊，key：E） | 項目 | 值 | |---|---| | Spec 模板 | `Spec 設計規格`（建立時自動帶出子 issue `[Plan]`） | | 標題 | `[Spec] 主題`、`[Plan] 主題`，兩張同主題；維運單 `[維運] 主題` | | 階段 label（單選） | `Spec`、`Plan` | | 工作類型 label（單選） | `新功能`、`改善`、`錯誤`、`維運`；加在 Spec 或單一工作單，Plan 不加；`稽核` 可另加 | | 已退役 label | `業務需求`、`自主規劃`，不再使用 | | 狀態 | 待規劃 → 待辦 → 進行中 → 驗證中 → 已完成；另有 已取消、Duplicate、Triage | | 父子自動化 | 子 issue 全部完成 → 父 issue 自動關閉；子 issue 全部取消 → 父 issue 自動改為已取消；父 issue 關閉**不會**關子 issue | | Estimate | Spec 與 Plan **必填**；維運單選填 | | GitHub PR 自動化 | 開 PR → 進行中；PR 審查活動 → 驗證中；PR 合進 `dev` → 驗證中（自動，Eddie 依目標分支設定；設定完成前依 elf-team-rule 規則 10 的過渡期處理）。已導入 dev／release 的 repo，「已完成」在發版完成後於步驟 7 手動設定；還沒導入的 repo 維持 PR merge → 已完成 | ## 生命週期對照 `#` 是階段編號，也是全文引用的名稱（「步驟 2」「步驟 3」）；**執行順序照表列順序**，步驟 3（寫計畫並取得核准）排在步驟 2（建 worktree）之前。 | # | superpowers | 性質 | Linear 單 | 狀態 | 轉換條件／回寫內容 | |---|---|---|---|---|---| | 0 | 開單 | — | 新建 Spec＋子 Plan | 待規劃 | 套模板；負責人、專案、Spec estimate；巡檢 R1–R7 自查；回報編號 | | 1 | brainstorming | 必經 | Spec | 待規劃 → 進行中 | 先請使用者描述、逐段回放，確認後寫進 Spec；判斷規模；實作者檢查 → 結果補進 Spec；定案留言「規格已定案」 | | 3 | writing-plans | 必經 | Plan | 待規劃 → 待辦 | Spec 已定案才開始，此時還沒有 worktree；計畫只記決策；寫完 5 項自審、設 Plan estimate 後改待辦；審計員留言「計畫已核准」後，審計員先用建立器建核准憑證，實作者 `verify` 通過才可進步驟 2 | | 2 | using-git-worktrees | 必經 | Plan | — | **計畫已核准、憑證 `verify` 通過、相依確認後才做**；分支用 Plan 編號；基線測試留言；提醒在 Orca 連 Plan 單；建狀態檔 | | 3a | 排進週期 | 必經 | Spec＋Plan | 維持 | 使用者決定這兩週要做才排；兩張排同一週期；Plan 留言 | | 4-1 | executing-plans（Native） | 二擇一 | Plan | 待辦 → 進行中 | 匯出計畫；每個 Task 完成時勾該 Task 的全部步驟，並留言完成摘要與裁決 | | 4-2 | subagent-driven-development（Subagent-driven） | 二擇一 | Plan | 待辦 → 進行中 | 同上；留言另含該 Task 的審查結論 | | S1 | test-driven-development | 必經（每個 Task） | Plan | — | 即 Task 的 5 個步驟；executing-plans 規定開工就載入，subagent-driven-development 的實作者照 Task 的步驟做 | | S2 | systematic-debugging | 按需 | Plan | — | 現象、根因、修法、新測試留言 | | S3 | dispatching-parallel-agents | 按需 | Plan | — | 只用在彼此獨立的問題調查；同一張 Plan 的實作 Task 不並行；並行清單與整合結果留言 | | S4 | writing-skills | 必經（新增或修改 skill 的單） | Plan | — | 每個要改的 skill 先跑壓力情境（RED），改完用同一組情境再跑（GREEN）；兩次的結果留言 | | 5-1 | requesting-code-review | 必經・保險① | Plan | 進行中 → 驗證中 | 所有 Task 勾完即改；最強模型審整個分支；結果依嚴重度留言；最終審查後留言「Rulings I made」總表 | | 5-2 | receiving-code-review | 必經 | Plan | 維持驗證中 | 逐項處理方式留言；只修一輪（4-2 派修正隊友＋範圍重審；4-1 自己修、用測試驗證），殘留的由使用者決定 | | 6 | verification-before-completion | 必經・保險② | Plan＋Spec | 維持驗證中 | 證據分兩段留言：程式本身的證據合進 `dev` 前必須完成，與 `release` 有關的證據發版完成前補齊；勾 Spec 驗收條件 | | 7 | finishing-a-development-branch | 必經 | Plan →（自動）Spec | 開 PR → 進行中；合進 `dev` → 驗證中（自動）；發版完成 → 已完成（手動）；或 已取消 | 巡檢全規則自查；收尾選項與結果留言；已完成的三個條件與自動化設定前的過渡期見 elf-team-rule 規則 10 | ## 各步驟做法 ### 0. 找到或建立工作單 - **有編號**（如 `E-31`）：`get_issue` 讀取。是 Spec 就再讀子 issue（label `Plan`）；是 Plan 就先讀父 issue（Spec）。依下表判斷在哪一步，從那裡接續，**不要從頭來**： | 看到的狀態 | 現在在 | |---|---| | Spec 待規劃 | 步驟 1 | | Spec 進行中、沒有「規格已定案」留言 | 步驟 1 | | Spec 有「規格已定案」、Plan 待規劃 | 步驟 3（先在 Linear 寫計畫；核准後才做步驟 2） | | Plan 待辦、沒有「計畫已核准」留言，或最後一則「計畫已修改 vN」之後沒有「計畫已核准 vN」 | 步驟 3（等審計員，不得開工） | | Plan 待辦、已核准、還沒有本 Plan 的 worktree | 步驟 2（建 worktree、分支與狀態檔） | | Plan 待辦、已核准、已有 worktree、沒排週期 | 步驟 3a | | Plan 待辦、已核准、已有 worktree、已排週期 | 步驟 4（開工） | | Plan 進行中 | 步驟 4（先讀 ledger，見步驟 4「續跑」） | | Plan 驗證中、PR 尚未合進 `dev` | 步驟 5 或 6（看留言紀錄） | | Plan 驗證中、PR 已合進 `dev` | 步驟 7（等發版） | Spec 底下有兩張以上 Plan 時，判斷表逐張 Plan 套用：Spec 那幾列看 Spec，Plan 那幾列看自己負責的那張；已定案的 Spec 不因多一張 Plan 而回步驟 1。一個 session 只接一張 Plan（elf-team-rule 規則 31）。例外是 Plan 群組（規則 17）：群組裡任一張 Plan 還沒寫完或還沒核准，全組都算在步驟 3，任何一張都不得開工，已核准的那張也一樣。為什麼：全組一起審，後面的 Plan 才不會寫到一半推翻已經做完的前一張。 步驟 5-1 已改為驗證中的 Plan，在步驟 7 開 PR 時會被自動拉回進行中，這是正常的，仍在步驟 7（等 PR 合併），不要回步驟 4；PR 有審查活動或合進 `dev` 時會再自動改為驗證中（合進 `dev` 的自動化設定完成前依 elf-team-rule 規則 10 的過渡期處理）。 - **新需求**：`save_issue` 在團隊 `ELF EXPRESS` 套用模板 `Spec 設計規格` 建立 `[Spec] 主題`。確認底下有 `[Plan]` 子 issue（沒有就手動建：套用模板 `Plan 實作計畫`、parent 為此 Spec、label `Plan`、狀態 待規劃），並把子 issue 標題改成 `[Plan] 主題`。 - 建立後立即設定 Spec 的 **estimate**，依目前對需求規模的初估。 - **兩張單都要設負責人（Eddie）與專案**；找不到適合的專案就問使用者，不自行開專案、不留空。 - Spec 加一個**工作類型** label；Plan 只加 `Plan`。 - **開單時不排週期**（見步驟 3a）。 - 一件事拆成**兩組以上** Spec＋Plan 時，在該專案建立里程碑（名稱用這件事的主題），每組都放進去，有先後順序的用 blocked by 標出；只有一組不建里程碑。大型主題用專案或里程碑分組，**不用父單**。 - 專案狀態：開第一張 Spec 時從「積壓案件」改「規劃中」；第一張 Plan 進入進行中時改「進行中」；專案是否「已完成」問使用者。 - 對兩張單跑巡檢 R1–R7 自查，有錯先修正。 - 回報編號，例如「Spec E-31 / Plan E-32」。 ### 1. brainstorming → Spec 1. Spec 改為 **進行中**。Linear 的自動化會把改為進行中的 Spec 加進目前週期；照步驟 3a，週期要等 Plan 核准後兩張一起排，所以先把 Spec 的週期清掉。 2. 照 superpowers 的 brainstorming 談（v7：先請使用者描述想要什麼與為什麼、不先給選項；每弄懂一部分就回放並標明哪些是猜測；先問使用者哪些技術選擇要自己決定）。本 skill 不重寫它的做法。 3. brainstorming 判斷規模並明講，使用者可推翻： - 快速小事或小變更 → 依「先分流」最後一列轉單一開發工作單。 - 專案 → 繼續寫 Spec，Spec 就是上游所說的「書面設計」。 - 其實是好幾個獨立專案 → 說出來、和使用者談定順序，拆成兩組以上 Spec＋Plan 並建里程碑（步驟 0），一次談一個。 - 使用者說跳過提問直接做 → 跳過的只是訪談，照「與上游 superpowers 的分工」表仍要開單與核准。 4. 每段回放經使用者確認後，就用 `save_issue` 寫進 Spec 對應章節，不等全部談完（中斷時 Linear 仍有紀錄）。章節：目標、範圍（要做／不做／反目標）、背景與限制、已決定的做法、留給實作者決定、方案比較（選填）、測試、驗收條件、實作者檢查、待決問題。保留「給 Claude」引言與章節標題（範本註明可刪的章節除外）。「已決定的做法」每一項標明「Eddie 決定」或「AI 的決定」，AI 的決定不寫成使用者同意的。 5. **實作者檢查**（上游的 builder check）：用 `get_issue` 把 Spec 存成系統暫存資料夾（Windows 是 `%TEMP%`）裡的 `E-<Spec 編號>-spec.md`（不放在 repo 裡，檢查完刪除），照 brainstorming 的 `builder-check-prompt.md` 派全新 subagent 讀它，派發時寫檔案的絕對路徑（隊友名稱見「隊友（subagent）規則摘要」）。結果分三類：對話或專案已能回答的補進 Spec；小事自己決定並標「AI 的決定」；會改變做法、只有使用者能答的，整理成一則訊息一次問完。三類結果摘要填進「實作者檢查」。 6. 自審：無佔位文字、無矛盾、範圍明確、驗收條件可驗證。請使用者審閱全文，附上 AI 自己做的決定清單。 7. 使用者核准後，在 Spec 留言「規格已定案（YYYY-MM-DD，<核准者>核准）」，例如「規格已定案（2026-10-21，Eddie 核准）」。核准前不寫產品程式、不搭鷹架、不裝套件、不建專案、不呼叫實作 skill（上游 HARD-GATE），只能讀與探索。Spec **維持進行中，不要關閉**，它會在 Plan 完成時自動關閉。 ### 3. writing-plans → Plan 1. 以 Spec 最新內容為輸入（取代 superpowers 預設的設計文件路徑），並探索程式結構。這一步還沒有本 Plan 的 worktree（步驟 2 在核准之後），在主目錄唯讀探索即可，不開分支、不寫 repo 內的檔（步驟 1 的 Spec 暫存檔與第 9 項的暫存 JSON 都放 repo 外）；elf-team-rule 規則 31 的 worktree 要求從步驟 2 起適用。 2. 照 writing-plans 寫，填進 Plan 描述，保留模板結構： - 標頭：目標、Spec（父 issue 編號）、架構、技術棧 - 全域限制（上游的 Global Constraints）：規格中全專案適用的要求，一條一行，數值照抄規格 - 檢查重點（上游的 Review Focus）：規格沒寫、但最可能讓使用者出問題的輸入或情況，最多五種；每一條都在負責那段程式的 Task 加一個測試；沒有就寫「已檢查，沒有」 - 檔案結構：新增／修改／測試，精確路徑 - 每個 Task：檔案、介面（需要／產出：類別、方法、資料表，寫精確簽名）、5 個 checkbox 步驟（寫失敗測試 → 確認失敗 → 實作 → 確認通過 → commit）；每個 Task 都要能獨立測試與 commit - **計畫只記決策，不寫整段程式**（上游 6.4.2 起的寫法）：測試步驟寫測試名稱與斷言，斷言用規格的精確值；實作步驟寫檔案、精確簽名與規格的值，只有簽名和測試決定不了的演算法才附程式；驗證步驟寫指令與通過時的輸出。每一步是一個動作、一個可檢查的結果；設定、鷹架、文件併進需要它的 Task。 - **步驟編號全單唯一**：`- [ ] 步驟 <Task>.<步驟>：…`，例如 `- [ ] 步驟 2.3：在 src/rate.ts 實作 syncRates(date: Date): Promise<number>`。模板裡的「步驟 1」「步驟 2」要改掉，否則多個 Task 會出現相同文字，勾 checkbox 時無法精準定位。 - Task 標題維持 `## Task N：名稱`（上游的 task brief 靠這個格式切出每個 Task，已實測） - 新增或修改 skill 的單（含本 skill 與 elf-team-rule）：每個要改的 skill 照上游 writing-skills 加 RED、GREEN 兩個步驟。改之前派全新 subagent 跑壓力情境（紀律類 skill 每個情境至少組合三種壓力），記下沒有新內容時的行為；改完用同一組情境再跑，確認照做。計畫寫情境名稱、壓力與預期行為，不抄整段提示詞。 - 完成檢查 3. 不寫沒有決定任何事的句子（例如「加上驗證」「處理邊界情況」），也不把簽名與測試已經決定的程式整段抄進來。 4. 全域限制一律包含 Plan 範本的四條：**資料庫腳本必須冪等、可重複執行，不存在就建立、存在就更新，不可 DROP 既有資料表或資料**；PowerShell 腳本（.ps1）存成 UTF-8 with BOM；不在計畫範圍內的檔案不修改，不刪測試、不放寬斷言、不降低 coverage 門檻；發版由誰執行（規則 39）。本單沒有資料庫變更或 .ps1 時，照範本寫「本單無…」，不刪掉該條。 5. 照 writing-plans 做 5 項自審：規格涵蓋、逐步檢查、型別一致、檢查重點、比例（計畫比規格長好幾倍，就是在抄程式）。 6. 依 Task 數量與複雜度設定 Plan 的 **estimate**；與 Spec 初估差距大時同步更新 Spec 的 estimate。 7. 自審後 Plan 改為 **待辦**，送審計員（使用者的審計對話）審，並照 writing-plans 請使用者選執行方式、附一句推薦理由：**Subagent-driven**（4-2：每個 Task 有全新實作者與審查者，最徹底）或 **Native**（4-1：在本 session 自己做，最後由最強模型的審查者審整個分支，最省）。使用者選定後在 Plan 留言「執行方式：Subagent-driven」或「執行方式：Native」，步驟 4 照這則留言執行。 8. 審計員在 Plan 留言「計畫已核准（YYYY-MM-DD，審計員：<模型>）」後才進步驟 2、3a／4。對話裡的口頭同意不算，自己派的 subagent 審查只算自審。核准後若再改 Plan 描述（勾步驟與完成檢查不算），先留言「計畫已修改 v2（原因）」，用建立器 `revoke` 刪掉核准憑證，再重新送審；審計員留言「計畫已核准 v2（YYYY-MM-DD，審計員：<模型>）」後，由審計員照第 9 項重新 `create`，實作者 `verify` 通過才繼續；之後再改依序用 v3、v4。審計員退回時，依留言修改、重做 5 項自審後再送。核准到手、審計員已照第 9 項建好憑證、實作者 `verify` 通過、相依條件也確認後，才回步驟 2 建 worktree、分支與狀態檔，然後進 3a／4。 9. **核准憑證**（給階段 Guard）：審計員留言「計畫已核准」後，由留下這則留言的審計員，在核准後自己依這則 Linear 留言用核准憑證建立器 `create` 憑證，不請 Eddie 手建，也不等使用者在對話裡另外同意。 - **實作者 MUST NOT `create` 或恢復憑證**，在這些情況下一樣：Guard 擋下寫檔、核准目錄只有舊格式核准檔、憑證遺失、雜湊不符、`verify` 回 `recreate`。實作者只用 `verify` 檢查；結果不是通過就停下，在 Plan 留言請審計員處理，不開工、不繼續寫檔。即使使用者催促、Linear 上核准留言明明存在，也不例外。 - 有效的核准留言：在對應的 Plan 上；作者在核准者名單內（Linear user ID `f7c5792e-6252-49dd-8210-b15b30c5229d`，或 Multica Gatekeeper agent id `2c8a076b-e4c0-4fc7-81b9-3ea21cd3ac82`，見 guard.md「有效的核准留言」）；文字開頭是「計畫已核准（YYYY-MM-DD，審計員：<模型>）」或「計畫已核准 vN（…）」；依 `createdAt` 由舊到新看，「計畫已修改 vN」之後要有版號 ≥ N 的核准、「核准撤回」之後要有新的核准。 - 做法（審計員）：用 `get_issue`／`list_comments` 取 Plan 描述與全部留言，寫成 repo 外的暫存 JSON（例 `%TEMP%/E-<Plan 編號>-approval.json`，格式見 `guard.md`「建立器用法」），執行 `node "$HOME/.claude/hooks/skillshare/elf-guard/elf-approval.cjs" create --plan E-<Plan 編號> --input <暫存 JSON>`；把 stdout 的稽核摘要留言到 Plan，再刪掉暫存 JSON。 - 建立器拒絕（exit 1）或 Linear 讀不到時：審計員不建立，回報 Eddie；實作者不開工。 - 只透過建立器碰核准憑證：不用 Write／Edit／Bash／PowerShell 直接讀寫或刪除核准目錄，指令裡也不寫核准目錄的路徑（Guard 會擋）。要確認憑證內容時用 Read。 - user ID 比對只能排除其他帳號，不是防止 AI 自我核准的安全邊界，限制說明見 `guard.md`「有效的核准留言」。 - 為什麼：Eddie 只在 Linear 寫核准，對話外沒有第二份要手動同步的紀錄；建立器只寫這一張 Plan 的憑證，比開放核准目錄更不容易誤寫其他 Plan。建立者是審計員、檢查者是實作者，實作者就不能自己產生讓自己的 Guard 放行的憑證；Guard 擋下或 `verify` 不通過時，多半是核准失效或憑證缺漏，由核准的人判斷，不由被擋的人補。 **核准撤回**：Eddie 在 Plan 留言「核准撤回」後，AI 在下一個驗證時點（見步驟 4）發現，立刻用建立器 `revoke --plan E-<Plan 編號> --reason <原因>` 刪掉憑證、停止實作、在 Plan 留言；撤回不需要再問使用者同意。要立即停止時由 Eddie 在對話通知該 session。為什麼：Guard 讀不到 Linear，撤回只能靠 AI 在驗證時點發現。 **同一個 Spec 底下增加 Plan**（elf-team-rule 規則 17）：寫計畫時發現工作量要拆，或執行中依規則 17 受控拆分時： - 套模板 `Plan 實作計畫` 建子 issue：parent 為該 Spec、label `Plan`、狀態 待規劃、負責人與專案同 Spec，標題 `[Plan] 主題`。 - 設新 Plan 的 estimate，把 Spec 的 estimate 改成各 Plan 加總；Plan 之間有先後就用 blocked by。不建里程碑、不寫「## 並行」。 - Spec 的驗收條件逐條在結尾標明由哪張 Plan 勾，例 `（E-387）`。 - 新 Plan 只寫計畫；碰到 Spec 沒涵蓋的設計，回步驟 1 和使用者談，不在 Plan 裡自己決定。 - 同一個 Spec 底下的 Plan 是一個群組（規則 17「Plan 群組」）：全組都寫完（範圍、Task、檔案、驗證、相依）才一起送審，並在 Spec 寫一行 `疊加順序：E-<第一張> → E-<第二張> → …`，彼此沒有相依的也排成一條線。為什麼：審計員要看到整件事的切法才審得出相依與遺漏。 - 群組裡每張 Plan 都要先在 Linear 寫完、全組一起送審；這就是一般規則，每張都在全組核准、自己的憑證 `verify` 通過、輪到它開工前才做步驟 2（worktree、基線、狀態檔）。 - 執行中拆分照規則 17「群組的受控拆分與退出」：先暫停整個群組；後續 Plan 都沒建 worktree、分支、也沒開工才可插入新 Plan，否則停下請 Eddie 決定，不自行插入、重排或 rebase。原 Plan 照第 8 項留言「計畫已修改 vN」重新送審，新 Plan 獨立寫計畫與送審；恢復前全組重新符合核准與憑證條件。群組中途取消或退出一張 Plan 也先問 Eddie。 ### 2. using-git-worktrees → Plan（計畫核准後才做，排在步驟 3 之後） **前置條件只適用 Spec／Plan**：單一開發工作單與 hotfix 沒有計畫核准這一關，開單後直接做下面第 1–6 項、不建狀態檔（見「先分流」）。 **Spec／Plan 的 Plan 要三項都成立才執行本節**：① Plan 上有有效的「計畫已核准（…）」留言，且之後沒有未重新核准的「計畫已修改 vN」或「核准撤回」；② 核准憑證已由審計員依步驟 3 第 9 項建立，實作者 `verify` 通過；③ 相依條件已確認——blocked by 的單都已到達本 Plan 需要的狀態：會改 repo 的單以**已合進 `dev`** 為準，本 Plan 的基線是它們合併後的 `origin/dev`；Plan 群組內的 blocked by 以前一張到達本節第 3 項的完成點為準，基線是前一張的分支，不是 `origin/dev`；`[維運]` 單以狀態**已完成**為準；相依單已取消時，要先確認本 Plan 不再依賴它才算成立，仍依賴就回步驟 1 和使用者談。 **排進週期（步驟 3a）不是本節的前置條件**：核准、憑證與相依三項齊備就可以建，不必等使用者決定這兩週要不要做（Eddie 決定，2026-10-25）。任一項不成立就停在步驟 3，不建 worktree、不開分支、不 commit 狀態檔；使用者催促、指令已就緒、「只是先開好暖機」都不是例外，要提前建只能由使用者明確推翻本條。為什麼：核准前沒有本 Plan 的 worktree，Guard 沒有保護對象——主目錄的分支不符合 Guard 認得的格式，判斷順序第 5 條一律放行，核准前不在主目錄寫實作檔靠 elf-team-rule 規則 31 與步驟 3 第 1 項；計畫被退回或相依單改了基線時，先建的分支、狀態檔與基線測試都要回頭清掉重做（E-423 審計，2026-10-25）。 1. 動手前先確認 repo 屬於分支規範的第幾種（看根目錄 `BRANCHING.md` 或 README 開頭），不確定就問。 2. 分支名稱 `<類型>/e-<Plan 編號>-<英文短名>`，例如 `feat/e-32-fx-rate-sync`。類型：`feat`、`fix`、`docs`、`chore`、`test`、`hotfix`。英文短名小寫 kebab-case。GitHub PR 自動化靠分支名稱裡的編號對應到 Plan。**不要**用 Linear 產生的 `gitBranchName`（會帶中文與全形符號，在 Windows、CI、shell 容易出問題），也不要用個人前綴（如舊的 `tw199501/`）。 3. 一般分支從最新的 `origin/dev` 開出；hotfix 是單一工作單，用該單編號，從 `origin/release` 開出。Plan 群組（規則 17「疊加分支」）：疊加順序的第一張從 `origin/dev` 開；後一張從前一張 Plan 分支的完成點開，也就是前一張的全部 Task 完成、保險①與保險②「合進 `dev` 前」那段都做完之後，不從 `origin/dev` 開。為什麼：後一張要包含前一張的提交，最後一張的分支才能當唯一的整合 PR。 4. worktree 一律開在 repo 外（同層），不開在主倉庫目錄內。這是本團隊已宣告的偏好，using-git-worktrees 不必再問要不要建。不用 Claude Code 的 `EnterWorktree` 建 worktree（它只會建在 repo 內的 `.claude/worktrees/`）；改用 `git worktree add <repo 外同層的路徑> -b <分支名稱> origin/dev`（hotfix 用 `origin/release`），再用 `EnterWorktree` 的 `path` 參數切進去，讓 session 的工作目錄跟著過去；沒有 `path` 參數的版本改用 `cd`（兩者的限制見「待確認」）。Plan 群組的每張 Plan 各自一個 repo 外同層 worktree，後一張用 `git worktree add <repo 外同層路徑> -b <本 Plan 分支> <前一張 Plan 的分支>`；狀態檔照第 7 項。 5. 跑基線測試，在 Plan 留言：分支名稱、worktree 路徑、基線測試結果（通過數／失敗數）。基線不乾淨就停下來問使用者。 6. **Orca 連單**：worktree 一律由 Claude Code 建立，**不要**在 Orca 的 Linear 任務列表按 Use 建立。建立後提醒使用者在 Orca：讓該 worktree 顯示在側邊欄；在 Edit Worktree Details 的 issue 欄位貼上 **Plan** 單網址（只連 Plan，一個工作區只連一張單）。 7. **狀態檔**（給階段 Guard。只有 Spec／Plan 要建，單一開發工作單與 hotfix 不建）：在 worktree 建 `docs/superpowers/state/E-<Spec 編號>.yaml`，內容三行 `ticket: E-<Spec 編號>`、`phase: plan`、`plan: E-<Plan 編號>`（UTF-8、LF），以 `docs(E-<Plan 編號>): 加入狀態檔` commit 進本分支；合進 `dev` 後留著當紀錄，不刪。第 1 種 repo 送原作者的 `pr/` 分支不 cherry-pick 這個 commit（規則 12）。`phase` 之後不更新，在哪一步一律看 Linear。Guard 依分支名稱找狀態檔，認得哪些分支格式見 skillshare-source 的 `docs/superpowers/guard.md`。同一個 Spec 底下第二張以後的 Plan，另建 `docs/superpowers/state/E-<Plan 編號>.yaml`，內容三行 `ticket: E-<Spec 編號>`、`phase: plan`、`plan: E-<Plan 編號>`，不改第一張 Plan 用的 `E-<Spec 編號>.yaml`：Guard 先讀與分支編號同名的狀態檔，改了第一張的 `plan:`，第一張 Plan 的分支就不再受 Guard 保護。狀態檔建立時計畫已經核准，所以 Guard 的實際作用是在那之後：Plan 留言「計畫已修改 vN」或「核准撤回」、憑證被 `revoke` 之後，Guard 會重新擋住 `docs/superpowers/` 以外的寫入。 ### 3a. 排進週期 - 只有在 Plan 已寫好、狀態待辦、有「計畫已核准」留言、**使用者決定這兩週要做**時才排。 - 有目前週期且有餘力 → 排目前週期；否則排下一個週期；不確定就問。 - **Spec 與 Plan 一起排進同一個週期**，在 Plan 留言「已排入 Cycle N（YYYY-MM-DD～YYYY-MM-DD）」。 - 週期結束時，沒做完的單問使用者移到下一週期或退回不排週期，不讓單留在已結束的週期裡。 ### 4. 執行 → Plan **開工** - 確認工作目錄是本 Plan 的 worktree，且本 Plan 的狀態檔已 commit：第一張 Plan 是 `E-<Spec 編號>.yaml`，同一個 Spec 第二張以後是 `E-<Plan 編號>.yaml`（步驟 2 第 7 項）。沒有就先回步驟 2 把它建好（步驟 2 排在核准之後，到這一步才建是正常順序）。 - 確認 Plan 有「計畫已核准」留言、之後沒有還沒核准的「計畫已修改」留言、已排進週期；確認核准憑證有效：照步驟 3 第 9 項把 Plan 描述與全部留言寫成暫存 JSON，用建立器跑 `verify --plan E-<Plan 編號> --input <暫存 JSON>`（四個驗證時點之「開工前」）。實作者在這裡只 `verify`，MUST NOT `create` 或恢復憑證（步驟 3 第 9 項）：還沒建立憑證，或結果不是通過，一律停下請審計員處理。exit 1 時依稽核摘要的建議動作處理： - `revoke`（核准已撤回或核准留言不在 Plan 上）→ 用建立器 `revoke`、停止實作、在 Plan 留言 - `recreate`（已有更新版號的核准）→ 停下，在 Plan 留言請審計員重建憑證；實作者不 `create`。審計員重建後，實作者再 `verify` 一次，通過才開工 - `stop`（雜湊不符、沒有憑證或憑證損壞）→ 停下，在 Plan 留言請審計員處理，不開工，也不自行用目前的描述重建憑證；「可能只是格式差異」不是理由，勾選、換行與連結 `href` 的差異建立器已排除 Guard 擋下而核准目錄只有 E-377 的舊四欄位核准檔時：舊檔一律視為未核准。實作者 MUST NOT 依舊檔或原核准留言 `create`，也不恢復憑證，只 `verify`，停下在 Plan 留言請審計員判斷並重建。審計員只有以下三點都能證明，才依原核准留言 `create`：Plan 尚未完成或取消、後續仍會寫實作檔；找得到原核准留言；原核准留言之後沒有未重新核准的實質修改（只有勾選變化）。Plan 的 `updatedAt` 晚於核准留言又無法逐項證明只是勾選時，審計員不依舊留言建立新憑證，改為要求重新送審（`guard.md`「多台機器與舊格式遷移」）。 Plan 群組（規則 17）：群組的第一張開工前，逐張確認全組都有「計畫已核准」留言，並對每一張跑 `verify`；任一張不通過，全組都不開工。之後每張開工前只跑自己那張的 `verify`。為什麼：全組核准是開工條件，第一張開工時是唯一能一次確認的時點。 讀「執行方式」留言，沒有就問使用者並補留言。開始第一個 Task 時 Plan 改為 **進行中**。 - **匯出計畫**（在 worktree 根目錄）： 1. 先建 `.superpowers/sdd/`，在裡面寫一個內容只有 `*` 的 `.gitignore`。上游 `sdd-workspace` 也會建這個檔，先建是為了讓匯出檔從一開始就不被 git 看到。 2. 用 `get_issue` 把 Plan 描述存成 `.superpowers/sdd/E-<Plan 編號>-plan.md`，父 Spec 存成 `.superpowers/sdd/E-<Spec 編號>-spec.md`。 3. 匯出的 Plan 拿掉「## 完成檢查」一節：上游的 task brief 會把最後一個 Task 標題之後的內容全部切進該 Task。 4. 把匯出 Plan 的「**Spec：**」整行換成 `**Spec：** .superpowers/sdd/E-<Spec 編號>-spec.md`，讓執行者讀得到規格。 5. 一律以這個相對路徑當 `PLAN_FILE`（ledger 第一行靠它對應本 Plan）；ledger 在 `.superpowers/sdd/E-<Plan 編號>-plan/progress.md`。 6. repo 的格式化或 lint 工具（例如 prettier）會掃到 `.superpowers/` 時，把它加進該工具的忽略清單，用一個 `chore` commit 提交到本分支，並當成裁決記進 ledger（E-268 遇過）。不提交的話 worktree 會一直有未提交的變更，收尾時移除不了。 - **上游腳本的路徑**：`sdd-workspace`、`task-brief`、`review-package`、`task-start`、`task-done` 一律用 skillshare 來源樹的路徑、以 `bash` 執行，例如 `bash <skillshare 來源>/_superpowers/skills/subagent-driven-development/scripts/sdd-workspace .superpowers/sdd/E-<Plan 編號>-plan.md`（來源路徑看 `skillshare status` 的 Source；上游 6.4.1 起不保證腳本有執行權限）。不用 `~/.claude/skills/_superpowers__skills__*/scripts/`：`task-start`／`task-done` 用相對路徑找 subagent-driven-development 的腳本，在 skillshare 攤平的目錄可能找不到。 - 審查包的 `MERGE_BASE` 用 `git merge-base origin/dev HEAD`（hotfix 用 `origin/release`），不用上游範例的 `main`。 **執行中** - 每個 Task 開始前、每個 Task 完成準備 commit 或勾選前，各重讀 Plan 描述與全部留言跑一次 `verify`（四個驗證時點的後兩個），結果不通過時照「開工」的建議動作處理（`revoke` 由實作者執行；`recreate`、`stop` 與其他不是通過的結果，實作者不 `create`，停下請審計員處理）；看到「核准撤回」就照步驟 3 第 9 項撤回。為什麼：核准後改計畫或撤回，Guard 本身看不到。 - 每個 Task 完成（ledger 寫下 `Task N: complete`）時做兩件事： 1. 用 `save_issue` 的 `patch`（op `replace`）把該 Task 的每一行 `- [ ] 步驟 N.M` 改為 `- [x] 步驟 N.M`，只改這些行，不重送整份描述。Linear 會存成 `- [X]`，兩者都代表已完成。 2. 在 Plan 留言一則：`Task N 完成（commits <a>..<b>）`、驗證結果（4-1：`task-done` 的測試結果；4-2：Task 審查的規格與品質結論、修正了幾輪）、本 Task 期間 ledger 的 `Ruling:` 行原文（開工前掃描計畫時的裁決併入 Task 1 這則）、隊友換人與原因。 - commit 訊息附 Plan 編號，例如 `feat(E-32): 新增匯率同步排程`。 - Plan 群組裡發現前面 Plan 的問題（規則 17「疊加分支」(4)）：最後一張的分支已存在就在它上面修；還不存在就在目前最末端、已存在的分支上修，下一張再從修正後的完成點開。已被後續 Plan 當作基線的分支不再加 commit，即使它的 worktree 還開著。修正的 commit 訊息寫所屬 Plan 的編號（例 `fix(E-701): …`），並在那張 Plan 留言。整合 PR 的審查或 CI／PR 檢查要修時也一樣在 PR 所在的最後一張分支修、重跑受影響的測試與 PR 檢查，不另開 Spec 或修正單；修法是某張 Plan 的實質變更（例如要加 Task），那張 Plan 照步驟 3 第 8 項留言「計畫已修改 vN」、`revoke`，審計員重新核准並 `create` 後，實作者 `verify` 通過才繼續。為什麼：往已被當作基線的分支加 commit，後續分支就不含這個修正，只能再合併或改寫歷史。 - **計畫與實際不符：照上游的裁決制**，不停下來等。以 Spec 為最高依據自己決定，記進 ledger：`Ruling: <決定> — <理由> — <錯了的代價>`，然後繼續。超出 Spec 範圍的需求不裁決（團隊補充）：照 Spec 也能完成 Plan、只是發現 Spec 沒涵蓋的新需求，就不做，記進 ledger，收尾時回報（需要就另開單）；不改 Spec 就完成不了 Plan，屬於下面的「需要改規格」。停下來問使用者的情況：上游的四種（不可逆或破壞性的操作；安全相關的動作；worktree 以外的副作用，例如合併、推送共用分支、發佈；計畫壞到每條路都只能猜），加上本團隊的兩種（需要改規格；elf-team-rule 規則 13 列的 git 停止條件，例如 `--ff-only` 失敗、衝突、push 被拒）。上游本來也要求停下來的：基線測試不乾淨（using-git-worktrees）、連續 3 次修不好（systematic-debugging；4-2 的做法見 S2）。 - 派發 subagent **一律明確指定模型**（上游 Model Selection；省略會繼承 session 模型）。各角色用哪一級見「隊友（subagent）規則摘要」。 - 4-1 Native：照 executing-plans，本 session 就是實作者，用 `task-start`／`task-done` 記 ledger；最後一樣派最強模型的審查者審整個分支（步驟 5-1）。 - 4-2 Subagent-driven：照 subagent-driven-development，每個 Task 一位全新實作者、一位 Task 審查者。同一張 Plan 的實作隊友一次只派一個（上游規定，避免衝突）；統籌不自己修程式，審查發現的問題交回實作隊友。 - S1：必須親眼看到失敗、親眼看到通過才能勾。 - S2：修好後留言現象、根因、修法、新測試。4-1 由本 session 照 systematic-debugging，連續 3 次修不好就停下質疑架構並問使用者；4-2 的實作隊友回報 BLOCKED 或 NEEDS_CONTEXT 時，統籌照上游處理：補資訊、換更強的模型、拆小；計畫本身有誤時照裁決制決定修正、記進 ledger、帶著裁決重派。需要改規格，或計畫壞到每條路都只能猜時，才停下來問使用者；需改規格時，使用者同意後回 Spec 修改並留言。 - S3：只用在彼此獨立的問題調查（例如多個不相關的失敗），同一張 Plan 的實作 Task 不並行；整合後跑完整測試，留言並行清單與整合測試結果。 - S4：照 writing-skills 跑壓力情境，派發時明確指定模型；兩次的模型、情境與結果寫進該 Task 的完成留言。新內容下仍不照做、要改已核准的文字時，屬於「需要改規格」，停下來問使用者。 **續跑**（新 session、換 worktree、context 壓縮後） - 「在哪一步」看 Linear 狀態（步驟 0 的判斷表）；「做到哪個 Task」看 ledger 與 `git log`。ledger 第一行寫的是本 Plan 的匯出檔時，有 `Task N: complete` 的 Task 已完成，不要重派。 - Linear 勾選與 ledger 不一致時，以 ledger 與 `git log` 為準，補勾 Linear、補留 Task 完成留言。