Imported from tarrragon/claude (skills/version-bootstrap/SKILL.md). Install upstream with npx skills add tarrragon/claude --skill version-bootstrap. Copyright stays with the author.

/version-bootstrap — 版本規劃波 Orchestrator

把版本提案展開成可執行的 ticket，中間不漏教學比對。

定位

使用方式

/version-bootstrap --version <version>

PM 執行後，依 6 步流程逐步推進。每步有 checkpoint（PM 確認後才進下一步），不是全自動 pipeline。

6 步流程

Step 1：列出提案清單（全自動）

動作：讀取 docs/todolist.yaml 中指定版本的 proposals 欄位，列出提案清單和摘要。

doc list proposals  # 確認提案狀態

輸出：提案 ID + 標題 + 狀態表格。

跨提案依賴檢查（強制）：接著執行依賴檢查腳本，偵測「本版提案依賴的提案排在更晚版本」的排序矛盾。

uv run .claude/skills/version-bootstrap/scripts/check_proposal_dependencies.py --version <version>

腳本讀 docs/proposals-tracking.yaml 各提案的 depends_on 欄位（選填，list of str，元素為本提案依賴的前置提案 id）比對 target_version 排序；若專案已採用 doc skill，該欄位格式定義的權威來源見 doc skill 的 tracking_schema.py（PROPOSALS_TRACKING_SCHEMA["proposal_entry_optional"]），非本 yaml 檔案本身的頭部註解。若未採用 doc skill，本腳本仍可正常運作（腳本本身不 import 該檔，以執行期讀取的 list 格式驗證取代靜態 import），只是欄位格式需自行依上方括號說明推斷，無法查閱該權威定義檔案。輸出 [WARNING] 時，PM 必須在本 Checkpoint 前二擇一處理：(1) 把依賴提案移入本版或更早版本一起排入，(2) 把本提案移至依賴提案完成之後的版本。動機案例：曾有版本以雙提案啟動，其中一提案依賴另一個排在更晚版本的提案，卻仍排入本版，矛盾拖到規劃波中段才由用戶手動發現，最終將該提案移至依賴對象所在的版本節點。若此檢查在 Step 1 就位，矛盾可在提案確認階段被攔截。

Checkpoint：PM 確認版本範圍——哪些提案納入本版、哪些延後；依賴檢查腳本無 [WARNING] 輸出，或警告已處理（移版/補前置）。

Step 2：建 Spec 骨架（半自動）

動作：用 /doc batch-init 批量建立 spec 骨架。

doc batch-init --proposals PROP-XXX,PROP-YYY --domain <domain>

輸出：每個提案對應 1 份 spec 骨架檔案。

PM 工作：填寫每份 spec 的 FR 列表、介面定義、約束條件。這是規劃波最耗時的人工步驟。

UI 類提案元件庫前置檢查（強制，元件庫雙向約束方法論落地）：Why——UI 類提案若跳過 design token 層與元件庫規劃直接進入實作，設計端與工程端會各自決定元件形狀，產生重複造輪與樣式漂移，已上線元件難以回溯套用 token 體系。Consequence——未在本步驟攔截，UI 實作票會在 Step 6 匯總建票時直接開出，等到 Phase 3b 實作階段才發現缺 token 層或元件庫章節，需回頭補規劃甚至推翻已完成的實作。Action——填寫 spec FR 時逐一判別提案是否涉及 UI/頁面/元件（FR 描述含「畫面」「頁面」「元件」「介面」「UI」等關鍵字），判為 UI 類提案者須先確認下列兩項存在，缺則先補齊才可繼續本提案的 UI 實作票規劃：

判準與分層依據（L1/L2/L3 分層、狀態綁定判準、流程整合點）見 .claude/methodologies/component-library-bidirectional-constraint-methodology.md。非 UI 類提案略過本檢查。

Why 加 design-system spec 檢查：doc skill 已提供 design-system-spec-template，但 batch-init 只產一般功能 spec，UI 版本易漏產 design system 專屬 spec。Consequence：漏產則 Step 4.5 地基波的 design-system 實作無契約可依（實證：PM 用 batch-init 產一般功能 spec 卻未產 design-system spec，經指正後才補）。Action：UI 版本填 spec 時一併用 design-system-spec-template 產出 design system spec，作為 Step 4.5 design-system 實作的契約。

Checkpoint：所有 spec FR 填寫完成；UI 類提案已完成元件庫前置檢查（design token 層、L3 元件庫章節、design-system spec 三者存在或已補齊），非 UI 類提案略過本項。

Step 2.5：Domain 規劃（半自動）

Why：spec 定義 FR（系統做什麼）、UC 定義使用者場景（誰怎麼用），兩者皆為垂直視角，不界定 domain 的水平聚合邊界——aggregate / kernel / read-model 分類、依賴方向、層測試策略。Consequence：跳過本步驟，domain 邊界會在實作階段臨場拍板（退化為「哪個檔案太大就拆」），依賴方向底線無文件可依，易出現 read-model 互相耦合、持久化細節混入 domain；測試設計（Step 5）也無 per-bundle 依據。需事後補 domain map（實證：某個移動應用實作案例中於實作前補建）。Action：spec FR 填完後、測試設計前，為每個 domain 產出或更新 domain map。

動作：用 doc skill 的 domain-map-template 為每個 domain 產出 domain map（多 domain 專案放 domain 子目錄，單 domain 專案放 docs/ 根層）：

# 多 domain 專案：放對應 domain 子目錄
cp .claude/skills/doc/templates/domain-map-template.md docs/spec/{domain}/domain-map.md
# 單 domain 專案：放 docs/ 根層
cp .claude/skills/doc/templates/domain-map-template.md docs/domain-map.md

PM 工作：依模板從 spec FR 反推 bundle 邊界（切分判準見 .claude/methodologies/domain-bundle-mapping-methodology.md）——界定 aggregate / kernel / read-model 分類、依賴方向 DAG（用實際 import 鏈驗證，不憑心智模型宣告——如 grep -rn "import.*<lower_layer>" lib/<domain_dir>/ 或 codegraph callers，確認 import 集合不含被禁層）、每 bundle 的目標路徑與測試層、FR→bundle 全覆蓋表。

產出或更新語意：saas 起手的版本，saas Stage 1/2 的 DDD 切分已餵入 domain map 的產出端，本步驟將其精修為層/依賴/測試 map；非 saas 起手（提案 / handoff 起手）則從模板新建。此語意消除「domain 規劃綁死 saas 起手」——標準化為所有規劃波的通用步驟。

被誰消費：Step 5 測試設計依 domain map 逐 bundle 決定測試層（domain unit / data repository / presentation widget）；Step 6 建票依 domain / data / presentation 分層切分。

Checkpoint：每個 domain 有 domain map；依賴方向底線經 import 鏈驗證；spec 全部 FR 在 FR→bundle 覆蓋表有歸屬（含標為非 domain 的 presentation / data FR）。

Step 2.6：資料契約產出（半自動）

Why：spec FR 定義欄位存在，不定義欄位的值域、狀態責任分層、不變式、交易邊界、錯誤語意與恢復模型；domain map §3 Bundle 界定表的 data/infrastructure 列只標「持久化細節屬 data 層」，未展開細節。Consequence：跳過本步驟，資料層設計意圖（為何選這個約束、哪些不變式由 DB 保證）無專屬載體，散落於 DDL 註解與 repository 程式碼各處；Step 5 測試設計對資料層契約條目無盤點依據，覆蓋缺口不可審計（見 .claude/methodologies/data-layer-contract-methodology.md 第 6 節）。Action：spec FR 與 domain map 完成後、紅燈測試設計前，依兩旗標判準決定是否產出資料契約文件。

動作：先依 .claude/methodologies/data-layer-contract-methodology.md 第 2 節兩正交旗標（契約文件 / migration 治理）判定（本步驟不複寫判準內容，僅引用）。兩旗標皆否時，僅維持 schema 約束 + DDL 註解即為合法終態，本步驟到此結束（合法跳過文件產出，非偷懶）。任一旗標為要時，cp 模板產出：

# 沿用 SPEC-NNN 編號體系，subdomain 固定為 data-contract
cp .claude/skills/doc/templates/data-contract-template.md docs/spec/{domain}/{name}-data-contract.md

消費來源：spec FR 列表（欄位語意/值域）+ domain map data 層（§3 Bundle 界定表 Infrastructure/data 列的「資料契約文件引用連結」欄）。

PM 工作：依模板填寫 A 區（邏輯契約，DB-agnostic）與 B 區（實作綁定，DB-specific），完成後執行 doc query <SPEC-ID> 做 doc CLI 驗證——確認 frontmatter 有效、文件可被查詢發現。

被誰消費（feed Step 5）：每條契約條目（不變式/欄位語意/邊界行為）登錄至 docs/traceability.yaml 第三軸 data_contract_tests；Step 5 派發 sage 時一併帶入此軸，供測試設計逐條盤點覆蓋缺口，避免資料層規則只靠「剛好被某測試涵蓋」被動覆蓋。

Checkpoint：兩旗標已判定並記錄理由（含合法跳過情形）；旗標=要時，資料契約文件已產出且 doc query 查詢成功；traceability.yaml 第三軸 data_contract_tests 已初始化，契約條目與測試對應無 TODO 佔位。

Step 3：教學比對（半自動）

動作：對每份完成的 spec 執行 /spec validate（Full 模式，含維度 4 教學一致性）。

前置：確認 CLAUDE.md「教學模組對應表」中有對應模組。

PM 工作：

• 偏移（高/中）：對齊教學設計或先在 blog 補完
• 教學缺口：在 blog 對應模組補完後再回來

Checkpoint：維度 4 無高嚴重度偏移。教學缺口已處理或標記 sync-pending。

Step 4：建 UC + traceability（半自動）

動作：Step 2 的 batch-init 已同時建立 UC 骨架和 traceability 映射佔位。

PM 工作：填寫每份 UC 的 GWT 場景、更新 traceability 映射（spec FR → UC scenario）。

Checkpoint：所有 UC 場景填寫完成，traceability 映射無 TODO 佔位。

Step 4.5：地基波（半自動，僅含 UI 提案的版本）

Why：測試設計（Step 5）需驗 zh/en overflow 與元件互動反應，這些依賴 i18n 系統與元件實體先存在；若 Step 4 後直接進 Step 5，UI 版本會在 i18n / design-system / 元件庫尚未 build 時進測試設計，無可驗對象。Consequence：跳過本步驟，測試票會假設不存在的 i18n key 與元件，Phase 3b 才暴露缺地基，需回頭補甚至推翻測試設計（實證：地基波經指正後手動插入）。Action：對含 UI 提案的版本，於測試設計前編排地基波實作波。

動作：依 component-library 方法論〈地基波 build 順序〉為權威，編排四塊地基實作：

PM 工作：為四塊各建實作票，另為元件契約建 DOC 票——i18n 與 design-system 可並行；UX 審查產出反應規格；元件契約依賴 UX 審查；元件庫依賴前三塊與元件契約為 blockedBy。順序與依賴依方法論〈地基波 build 順序〉，本 skill 不重複判準只做 orchestration。

Checkpoint：UI 版本的 i18n / design-system / UX 審查 / 元件庫四塊實作完成並測試綠；非 UI 版本略過本步驟（比照 Step 2 UI 判別）。

Step 5：紅燈測試設計（半自動，可並行）

動作：對每份 spec 派發 sage-test-architect 做 Phase 2 紅燈測試設計，依紅燈層級順序分兩段產出：

• 5a 外圈驗收紅燈（先）：對 runtime_surface: yes 的 UC 場景產出整合層測試描述，含 on-device / 端對端層級；外圈定義「什麼叫做完」，以 wip tag 與 gate 隔離。runtime_surface: no 的場景豁免本段（豁免判準見權威節，此處不複寫）。
• 5b 內圈單元紅燈（後）：規格分解的單元測試設計，驅動實作紅綠循環。

順序規則、豁免判準與 wip tag 共存機制的權威定義見 /tdd skill references/phase2/rules.md「紅燈層級順序」節，此處不複寫。

多 spec 可並行派發（每個 spec 1 張子票）。派發時使用 /tdd Phase 2 流程，sage 產出紅燈測試規格（5a + 5b 兩段皆屬同一 Phase 2 產出）。

消費 Step 2.5 domain map（兩軸測試設計）：

1. 層軸：依 domain map 逐 bundle 決定測試層——domain bundle 走純函式 unit test、data 走 repository test、presentation 走 widget test（分層測試策略見 .claude/methodologies/hybrid-testing-strategy-methodology.md）。
2. 不變式軸：依 domain map 的「Bundle 不變式清單」節逐 bundle 列舉 domain 行為不變式測試（例：某項缺漏沿用前值、比率分母為 0 的定義值、依賴方向不成環等各專案自己的 domain 不變式），與 UC 場景測試並存去重——UC 場景測試涵蓋垂直使用者行為，不變式測試涵蓋水平 domain 規則，兩軸交集去重、聯集為完整覆蓋。避免 domain 規則只靠「剛好出現於某 UC 場景」被動覆蓋。

sage 派發 prompt 應同時帶 spec FR / UC 場景（既有）與 domain map 的 bundle 不變式清單（新增），使兩軸都被系統列舉。traceability 的 domain-bundle→test 軸（見下）記錄不變式軸覆蓋。

PM 工作：驗收 sage 產出——確認 FR↔AC 覆蓋矩陣（Q12）無空行。

Checkpoint：所有 spec 的 Phase 2 完成，紅燈測試規格已提交。

Step 6：匯總建票（半自動）

動作：根據 Step 2-5 的產出，建立 W2/W3/W4 的 IMP ticket。

• W2/W3：GREEN 實作票（每個 spec FR 或功能模組 1 張）
• W4：驗收票（E2E + Phase 4）

建票來源：

• spec FR 列表 → IMP ticket
• Phase 2 紅燈規格 → 確認 ticket 粒度（每張 ticket 的紅燈數）
• UC 場景 → 整合測試 ticket
• domain map bundle 分層 → 按 domain / data / presentation 切分實作票，並依 domain map §5「對實作票切分指引」對齊各票的層歸屬與依賴方向底線

PM 工作：確認 Wave 分配、並行安全（共用檔案需整合票）。

Checkpoint：所有 ticket 建立完成，Wave 分配確認。

反應式工作（不納入 bootstrap）

以下工作在規劃波過程中可能發生，但不屬於 bootstrap pipeline：

移版硬耦合盤點 SOP

提案因跨提案依賴矛盾（Step 1 檢查結果）或其他理由決定移版時，禁止整包提案原封不動搬到新版本——必須先盤點該提案在本版留下的 schema / DDL / 契約級殘留耦合，比照下方動機案例「契約先定形、業務邏輯後移版」的模式先行定形，斬斷後才能讓移出的主體與留在本版的部分變成獨立軌道。

動機：曾有版本規劃雙提案，其中一提案因依賴另一個排在更晚版本的提案而整體移版，但其變更清單第一項會動到契約 SOT 檔案（如 schema 定義）並牽動資料庫 DDL——若放任不管、等本版 DDL 凍結後才在移版目標版本定形該欄位，會重演過往「先上線、後補契約定義」造成的多階段漂移。提前在 DDL 凍結前定形該欄位形狀，才讓兩個提案真正解耦。

盤點步驟：

判斷準則（步驟 3 分級）：

與早期手動流程的對照

版本紀錄在同目錄的 CHANGELOG.md。