create-agentic-dev-env 1.0.0 → 1.2.0

package/README.md

@@ -53,8 +53,11 @@ knowledge/
 ├── process/     # 跨服務的團隊流程知識
 ├── specs/       # 當前功能規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-skills/          # init 時注入工作目錄（contribute / add-service / align-spec / spec-audit）
-.claude/skills/  # 在 ADE repo 內工作用（create-prd / prd-to-spec / feedback-upstream）
+skills/          # init 時注入工作目錄的十五支 ade-* skills（help / update / contribute / add-service /
+                 #   list-service / create-prd / prd-to-spec / dev / dev-auto / align-spec / spec-audit /
+                 #   commit / ship / add-skill / add-process）；其中七支 symlink 進 .claude/skills/ 在 ADE repo 內也可用
+.claude/skills/  # 只在 ADE repo 內工作用（feedback-upstream）
+CONTEXT.md       # 開發流程詞彙表；產品域詞彙在 knowledge/specs/GLOSSARY.md
 claude-md/       # CLAUDE.md managed 區段的內容
 ```
 
@@ -63,9 +66,11 @@ claude-md/       # CLAUDE.md managed 區段的內容
 - **Context 管理是底層原則**：agent 的 context 是最稀缺資源，所有文件與流程設計都遵守「常駐最小化、細節按需載入、導航短細節深」——CLAUDE.md 區段只寫「何時做＋去哪看」，細節留在知識庫等被載入
 - **服務 registry 兩層結構**：`index.md` 是全服務概覽（模擬工程師「先總覽定位、再查細節」的認知路徑），每個服務一份 YAML 記錄 repo 位址、技術棧、依賴關係——agent 據此自主 clone 與開發
 - **知識分層**：ADE 只收「跨服務知識、取得服務的最小資訊、產品規格」三類；bootstrap 流程與服務內部慣例歸服務 repo 自己的文件，不複製會過期的副本
-- **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（含盲點拷問）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾；另有 `ade-spec-audit` 定期巡檢，抓 hotfix 等計畫外變更造成的規格漂移
+- **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（模糊想法先跑 Discovery，再盲點拷問，`validate-prd.sh` 機械檢查）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾；另有 `ade-spec-audit` 定期巡檢，抓 hotfix 等計畫外變更造成的規格漂移
 - **Managed 區塊覆蓋**：工作目錄裡的 ADE 內容視同唯讀，`update` 無條件覆蓋——想改就回 ADE repo 開 PR，強迫知識回流中央
-- **機制回饋上游**：各 ADE repo 演化出的 skill／模板改良，由 `ade-feedback-upstream` skill 開 PR 回本專案（只回饋機制，公司知識絕不外流）
+- **判準制開發流程**：`ade-dev` 六關（規格→規劃→逐 Phase 實作→測試審視→沉澱→Ship），每關只定義產出與過關判準、狀態全落檔可換 session 接手；Spec Ready G1–G8 全 PASS 的任務可 auto-pilot 無人把關跑完，`ade-dev-auto` 批次串接。規則住在 `knowledge/process/ade-dev-workflow/`，證據盤點在本 repo `docs/research/ade-dev/`（不隨 ADE repo 複製）
+- **消費端自助**：`ade-help` 即時掃描列出可用 skills、`ade-update` 比對版本後更新並回報新增的 skill；交付走 `ade-commit`（專案慣例優先）與 `ade-ship`（平台偵測、專案範本優先）
+- **機制回饋上游**：各 ADE repo 演化出的 skill／模板改良，由 `ade-feedback-upstream` skill 開 issue 回本專案（改良來源含各流程沉澱出的 `[upstream-candidate]` issues；只回饋機制，公司知識絕不外流）
 
 ## 開發
 

package/bin/create.js

@@ -21,7 +21,7 @@ fs.cpSync(path.join(__dirname, '..', 'template'), dest, { recursive: true })
 fs.renameSync(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'))
 fs.renameSync(path.join(dest, 'dot-claude'), path.join(dest, '.claude'))
 // 這些 skill 在 ADE repo 內也要可觸發，symlink 進 .claude/skills/（單一真相在 skills/）
-for (const s of ['ade-add-service', 'ade-add-skill']) {
+for (const s of ['ade-add-service', 'ade-add-skill', 'ade-add-process', 'ade-create-prd', 'ade-prd-to-spec', 'ade-help', 'ade-list-service']) {
   fs.symlinkSync(path.join('..', '..', 'skills', s), path.join(dest, '.claude', 'skills', s), 'dir')
 }
 for (const rel of fs.readdirSync(dest, { recursive: true })) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-dev-env",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Scaffold and manage team Agentic Dev Environment (ADE) knowledge repos",
   "repository": {
     "type": "git",

package/template/CONTEXT.md

@@ -0,0 +1,53 @@
+# ADE 開發流程
+
+ADE 知識庫與其標準開發流程（判準制、延遲展開）的統一詞彙。
+
+## Language
+
+**產品規格（Spec）**:
+ADE `knowledge/specs/` 內的長期資產，描述產品當前功能的整體規格，由 PO 持續迭代。
+_Avoid_: 規格（不加限定詞）
+
+**實作規格**:
+開發流程規格關的產出，只描述該次開發範圍的規格，活在工作目錄。簽核後凍結，停留在該次開發當下，不隨開發過程更新；同步產品規格時以實作結果為準，不以它為準。
+_Avoid_: spec（易與產品規格混淆）、技術規格
+
+**關（Gate）**:
+開發流程的階段邊界，以「產出＋過關判準」定義，不規定做法。判準是可檢查的狀態，不是動作。
+_Avoid_: 階段、phase（流程意義）、step
+
+**Phase**:
+可獨立交付的開發單位——可單獨開發、驗收、合併交付，不影響主幹安全。Plan 產出 Phase 清單（全貌地圖），輪到才展開。
+_Avoid_: 增量、功能點、子任務、milestone
+
+**交付定義**:
+Plan 時每個 Phase 的 1–3 行完成描述（完成後可觀察到什麼行為、為何交付安全）。人工簽核的對象；展開時細化為 AC。
+_Avoid_: spec 摘要、goal
+
+**展開（Expansion）**:
+輪到某 Phase 開發時，將其交付定義細化為 AC 與 Tasks 的動作。未輪到的 Phase 維持粗粒度，不預先展開。
+_Avoid_: breakdown、拆解（plan 層的拆分）
+
+**AC（驗收標準）**:
+展開時產出的 Given/When/Then 條目，每條須可回溯到交付定義；Phase 驗收與測試的契約。
+_Avoid_: 驗收條件、DoD
+
+**Task**:
+Phase 展開後的內部工作項，checklist 一項即可。無獨立驗收契約、無獨立檔案；是 agent 組織 how 的自由。
+_Avoid_: 子任務、ticket
+
+**Spec Ready**:
+判定一顆任務是否就緒可交給 auto-pilot 的硬性 gate 清單，逐條 PASS／FAIL／DEFERRED（未到評估時機），不打分數；任一 FAIL 即不得 auto。
+_Avoid_: 就緒分數、readiness score
+
+**Auto-pilot**:
+ade-dev 的無人中途把關執行模式：Spec Ready 全 PASS 後，簽核點降為回報點，所有關的判準與審查照跑。
+_Avoid_: 自動模式（未指明層級）、全自動
+
+**煞車（Brake）**:
+任務層的執行期停止條件，由 ade-dev 定義。命中即停下該顆任務、降回手動，不影響其他任務。
+_Avoid_: 熔斷（那是批次層）
+
+**熔斷（Circuit breaker）**:
+批次層的停止條件，由 ade-dev-auto 定義。命中即停整批——針對共因失敗或累計失敗；與單顆任務的煞車分層，兩詞不混用。
+_Avoid_: 煞車（那是任務層）

package/template/README.md

@@ -45,52 +45,68 @@ init 會在當前目錄建立：
 
 之後同指令改跑 `update` 拉取最新知識（update 會直接 clone 最新版，不受 dlx 快取影響）。
 
+### 裝好之後，先記這兩支 skill
+
+- **`/ade-help`** — 「有哪些 skill 可以用？」問它。它即時掃描當前位置真正載得到的 `ade-*` skills 並列出用途，不會像文件一樣過期
+- **`/ade-update`** — 說「更新 ADE」，它會先比對版本（一樣就不跑）、提醒手改過的 managed 內容先走 `ade-contribute` 回流（否則被覆蓋），更新完回報版本變化與期間新增的 skill。session 開始偵測到落後時也會主動提醒
+
 ## 結構
 
 ```
 knowledge/
-├── services/    # 服務 registry：index.md 總覽導航 + 一服務一檔
-├── process/     # 團隊流程知識
-├── specs/       # 當前功能規格，持續迭代的真相來源
+├── README.md    # 知識分層規則（canonical）
+├── services/    # 服務 registry：index.md 總覽導航 + 一服務一檔 yaml
+├── process/     # 跨服務流程與團隊級慣例
+├── specs/       # 產品規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-skills/          # init 時注入工作目錄的 .claude/skills/（六支，見下方 Skills 一覽）
-.claude/skills/  # 在本 repo 內工作用的 skills（三支＋add-service、add-skill 的 symlink，見下方 Skills 一覽）
+skills/          # init 時注入工作目錄的 .claude/skills/（十五支，見下方 Skills）
+.claude/skills/  # 在本 repo 內工作用的 skills（ade-feedback-upstream ＋ 七支的 symlink）
 claude-md/       # CLAUDE.md managed 區段的內容
+CONTEXT.md       # ADE 開發流程的統一詞彙表（產品域詞彙另在 knowledge/specs/GLOSSARY.md）
 ```
 
-## Skills 一覽
+## Skills
 
 ### 注入工作目錄的 skills（init 後在工作目錄可用）
 
-- **`ade-contribute`** — 知識回流的核心通道。當 agent 在工作中發現知識庫內容與現實不符（服務資訊過期、文件缺漏），或學到值得保存的新知識時觸發。它會先查 ADE repo 的 open issues／PRs 避免重複回流（已有記錄就留言補充），沒有才開 issue 記錄缺口，接著 clone 本 ADE repo、建分支、修改對應文件、開 PR 連結該 issue。人只需要 review PR。**注意：絕不直接改工作目錄裡的 `.claude/ade/` 副本**——那是 managed 區域，update 時會被覆蓋，改了等於白改；這支 skill 存在的意義就是把修改導向正確的地方。其他三支 skill 的「開 PR」動作也都委派給它，所以回流機制只需要維護這一份。
-
-- **`ade-add-service`** — 在知識庫註冊新服務。使用者說「新增服務」「把某某服務加進知識庫」時觸發。它會依 `knowledge/services/_template.yaml` 的欄位結構建立服務描述檔（`repo` 的 url 與 branch 為必填，因為 agent 之後要靠它自主 clone 服務），同步在 `services/index.md` 總覽表加一列。資訊不足時它會問人，不會留空猜測。**本 ADE repo 內也可用**（`.claude/skills/` 有 symlink，這是主要使用場景）：在本 repo 直接編輯、照一般 git 慣例收尾；在工作目錄則走 `ade-contribute` 流程開 PR。
-
-- **`ade-align-spec`** — 開發收尾的文件對齊。RD 完成一個 PRD 的開發後觸發。它對照 `workspaces/` 下的實際實作，逐一核對 spec 中屬於這次 PRD 的 `🚧 尚未實作` 標記：做完且行為一致的移除標記；實作與 spec 有出入的**以實作為準**修改 spec 並記下差異；沒做的保留。全部驗收項完成時把 PRD 狀態改為「已實作」。最後開 PR，把差異清單列給 PO 判斷是否接受。它只動屬於這次 PRD 的標記，同一份 spec 上其他進行中 PRD 的標記不會被誤刪。
-
-- **`ade-spec-audit`** — spec 的定期健檢。PRD 流程只覆蓋「計畫內」的開發，hotfix 和直接改 code 的計畫外變更會讓 spec 悄悄失真——這支 skill 補上這條偵測路徑。觸發後它逐份 spec 對照相關服務的實作（缺的 repo 會先 clone），找出「行為已變、功能已移除、實作有但 spec 沒記載」的漂移，產出清單讓人確認該修 spec 還是該修 code（漂移不一定是文件錯，也可能是實作偏離了規格），確認後開 PR 修正。建議在 release 後或定期執行。
-
-- **`ade-add-skill`** — 為 ADE 生態新增 skill 的 meta-skill。使用者說「新增 skill」「把這個做成 skill」時觸發。它先問使用對象再決定放置位置：消費端工作目錄用 → `skills/ade-*`（init/update 注入）；本 ADE repo 內用 → `.claude/skills/ade-*`；兩邊都用 → 放 `skills/` 加 symlink。並落實命名規則（`ade-` 前綴）、context 紀律與 README 同步。**本 ADE repo 內也可用**（`.claude/skills/` 有 symlink）。
-
-- **`ade-add-process`** — 為團隊建立或修改流程慣例的 meta-skill。使用者說「以後都這樣做」「定一個慣例」時觸發。它依三層機制選載體：無條件約束 → `claude-md/section.md` 加一行指標；有觸發時機的程序 → 新增一支 `ade-` 前綴 skill；細節 → `process/` 一主題一檔。並執行 context 紀律：常駐層只寫「何時做＋去哪看」（參考技巧）、常駐規則超過 10 行時新增前必須與使用者確認取捨。最後走 `ade-contribute` 流程開 PR。
+「本 repo」欄標 ✅ 者在本 ADE repo 內也可用（`.claude/skills/` 有 symlink，單一真相在 `skills/`）。
+
+| Skill | 用途 | 本 repo |
+| --- | --- | --- |
+| **`ade-help`** | 列出當前位置可用的 ade-* skills 與各自用途（「有哪些 skill」）。清單由 `list-skills.sh` 掃 `.claude/skills/ade-*/SKILL.md` 的 frontmatter 即時產生——不寫死清單，skill 搬家或新增都不用回頭改。 | ✅ |
+| **`ade-update`** | 把工作目錄的 managed 內容拉到本 repo 最新版（「更新 ADE」，或 session 開始偵測到落後時）。先用 `git ls-remote` 比對 `.ade.json` 的 `commit`（一樣就不跑）、提醒把 managed 區域的手改先走 `ade-contribute` 回流，才執行 `pnpm dlx <source> update`，最後回報版本變化與期間新增的 skill。只在消費端工作目錄用——本 repo 內用一般 `git pull`。 | — |
+| **`ade-contribute`** | 從工作目錄修改本知識庫的**唯一通道**（「改 ADE 的 spec／skill」「回流」）。主動撰寫直接建分支開工；被動回流先查 open issues／PRs 避免重複，沒有才開 issue 記錄缺口、PR 再連回該 issue。工作副本放 `workspaces/<ade-repo-name>/`，已存在就重用、收尾切回主幹。**絕不直接改工作目錄的 `.claude/ade/` 副本**——那是 managed 區域，update 時會被覆蓋。其他 skill 的「開 PR」動作都委派給它。 | — |
+| **`ade-add-service`** | 在知識庫註冊新服務（「新增服務」）。依 `knowledge/services/_template.yaml` 建描述檔（`repo` 的 url 與 branch 必填，agent 之後要靠它自主 clone），並同步 `services/index.md` 總覽表。資訊不足會問人，不留空猜測。 | ✅ |
+| **`ade-list-service`** | 列出目前所有已註冊的服務（「有哪些服務」）。讀 `services/index.md` 並與目錄下的描述檔比對，回報清單與兩者不一致處。只讀不改。 | ✅ |
+| **`ade-create-prd`** | 引導 PO 產出標準化 PRD（「建 PRD」），涵蓋「只有模糊想法」到「照範本填寫」兩種起點。想法未成形先跑 **Discovery** 7 題（一批 2–3 題，已有答案的跳過），接著對照服務總覽、既有 spec 與進行中 PRD 用團隊詞彙寫入 `knowledge/prd/`，再進**盲點拷問**（邊界與錯誤情境、跨服務影響、權限安全、資料相容性、驗收可測性、相鄰功能），最後用 `validate-prd.sh` 機械檢查。**不自動翻狀態**——留「草稿」，PO 確認才改「已確認」。 | ✅ |
+| **`ade-prd-to-spec`** | 把已確認的 PRD 落入規格（「PRD 轉 spec」）。找出受影響的 spec（必要時新建），將需求寫成「功能完成後應有的樣子」，並在每個新增／變更的行為區塊上方加 `🚧 尚未實作（PRD: …）`——spec 因此同時承載「已上線現況」與「已定案未開發」，靠標記區分。完成後回填 PRD 的「Spec 異動摘要」，帶 PO 逐項確認。產出即 RD 開發時的規格依據。 | ✅ |
+| **`ade-dev`** | 判準制標準開發流程（「開始開發」「繼續開發」）。六關：規格（實作規格，人簽核後凍結）→ 規劃（Phase 地圖）→ 實作（逐 Phase 輪到才展開，TDD 紅→綠，交前兩軸審查）→ 測試審視 → 沉澱 → Ship。每關只定義產出與過關判準，不規定做法；狀態全在 `.ade-dev/`，session 可隨時 `/clear` 換手。內建 **Spec Ready gate G1–G8 與 auto-pilot 模式**，配零容忍煞車與有限重試。規則全在 `knowledge/process/ade-dev-workflow/`，skill 只是指標。 | — |
+| **`ade-dev-auto`** | 串接多個 ade-dev 任務的批次執行器（「批次開發」）。列出 `.ade-dev/` 下未完成任務供多選，逐顆跑 Spec Ready 判定，不合格的問人補齊或剔除，全數就緒後依序 auto-pilot 執行。只定義批次層 B1–B4 與批次熔斷，任務內判準全在 ade-dev。 | — |
+| **`ade-align-spec`** | 開發收尾的文件對齊（「開發完了更新 spec」）。對照實際實作逐一核對該 PRD 的 `🚧 尚未實作` 標記：做完且一致的移除、有出入的**以實作為準**改 spec 並記差異、沒做的保留；驗收項全完成時 PRD 轉「已實作」。最後開 PR 把差異清單交 PO 判斷。只動屬於這次 PRD 的標記。 | — |
+| **`ade-spec-audit`** | spec 的定期健檢（「規格還對嗎」）。PRD 流程只覆蓋計畫內開發，hotfix 與直接改 code 會讓 spec 悄悄失真——這支補上偵測路徑：逐份 spec 對照實作（缺的 repo 會先 clone），找出行為已變／功能已移除／實作有但 spec 沒記載的漂移，產出清單讓人決定修 spec 還是修 code，確認後開 PR。建議 release 後或定期執行。 | — |
+| **`ade-commit`** | commit 訊息慣例解析，任何要在服務 repo commit 的場景使用。依序找專案自述（CLAUDE.md／AGENTS.md／CONTRIBUTING）→ commitlint 等設定檔 → 既有 git log 風格 → 都沒有才用 ADE 預設（`knowledge/process/git-commit.md`，Conventional Commits）。一個 commit 一件事。 | — |
+| **`ade-ship`** | 從服務 repo 分支發出 MR／PR（「發 MR」「ship」）。偵測平台（GitHub → `gh`、GitLab → `glab`，退 API）、專案自有範本優先（GitHub 六個位置＋組織預設、GitLab 設定層與 `.gitlab/merge_request_templates/`）、沒有就用內建 `templates/mr.md`，依實際 diff 填寫後發出並回報 URL。不自動 merge。 | — |
+| **`ade-add-skill`** | 新增 skill 的 meta-skill（「把這個做成 skill」）。先問使用對象再決定位置：消費端工作目錄用 → `skills/ade-*`（init/update 注入）；本 repo 內用 → `.claude/skills/ade-*`；兩邊都用 → 放 `skills/` 加 symlink。並落實 `ade-` 命名規則、context 紀律與 README 同步。 | ✅ |
+| **`ade-add-process`** | 建立或修改流程慣例的 meta-skill（「以後都這樣做」）。依三層機制選載體：無條件約束 → `claude-md/section.md` 加一行指標；有觸發時機的程序 → 新增一支 `ade-` 前綴 skill；細節 → `process/` 一主題一檔。並執行 context 紀律：常駐層只寫「何時做＋去哪看」，常駐規則超過 10 行時新增前必須與使用者確認取捨。 | ✅ |
 
 ### 在本 ADE repo 內工作用的 skills（PO／維護者在本 repo 開 Claude Code 使用）
 
-- **`ade-create-prd`** — 引導 PO 產出標準化的 PRD。它依 `knowledge/prd/_template.md` 建檔並逐區塊陪 PO 填寫，過程中會先讀服務總覽與既有 spec，用團隊既有詞彙、找出與現有規格的衝突。填完後進行**盲點拷問**：邊界與錯誤情境、跨服務影響、權限安全、資料相容性、驗收條件是否可測試、最容易被誤會包含在內的相鄰功能——問到每題都有明確答案或明確說「不在範圍」為止。PO 確認後狀態改「已確認」，才能進入下一步。
-
-- **`ade-prd-to-spec`** — 把已確認的 PRD 落入規格。它找出受影響的 spec 檔（必要時新建），將 PRD 需求寫成「功能完成後應有的樣子」，並在每個新增／變更的行為區塊上方加 `🚧 尚未實作（PRD: …）` 標記——spec 因此同時承載「已上線的現況」與「已定案未開發」兩種資訊，靠標記區分。完成後回填 PRD 的「Spec 異動摘要」，帶 PO 逐項確認 spec 與預期相符才算結束。這一步的產出就是 RD 開發時的規格依據。
-
-- **`ade-feedback-upstream`** — 把本 repo 演化出的**機制**改良（更好的 skill 寫法、模板結構、流程設計）以 **issue** 回饋給上游 create-agentic-dev-env 框架，由上游維護者決定是否採納，讓所有 ADE repo 受益。它有一條鐵律：只回饋機制、**絕不回饋內容**——`knowledge/` 下的公司知識、服務資訊、規格全屬機密，送出前會逐行檢查 issue 內文、把公司語彙抽換成通用範例。上游位址記在 `package.json` 的 `ade.upstream`。
+| Skill | 用途 |
+| --- | --- |
+| **`ade-feedback-upstream`** | 把本 repo 演化出的**機制**改良（更好的 skill 寫法、模板結構、流程設計）以 **issue** 回饋給上游 create-agentic-dev-env 框架，由上游維護者決定是否採納，讓所有 ADE repo 受益。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程收尾沉澱時經 `ade-contribute` 開出）。鐵律：只回饋機制、**絕不回饋內容**——`knowledge/` 下的公司知識、服務資訊、規格全屬機密，送出前逐行檢查 issue 內文、把公司語彙抽換成通用範例。上游位址記在 `package.json` 的 `ade.upstream`。 |
 
 ## PRD / Spec 流程
 
-1. PO 在本 repo 用 `ade-create-prd` 建立標準化 PRD（含盲點拷問），定案後標「已確認」
+1. PO 用 `ade-create-prd` 建立標準化 PRD（含 Discovery 與盲點拷問），定案後標「已確認」
 2. PO 用 `ade-prd-to-spec` 把 PRD 融入 `specs/`，新行為標 `🚧 尚未實作`，逐項確認對齊
-3. RD 在工作目錄開發（`workspaces/`）
+3. RD 在工作目錄走 `ade-dev` 六關開發（`workspaces/`），`ade-ship` 發 MR
 4. 開發完成 RD 跑 `ade-align-spec`：核對實作、移除 🚧、PRD 標「已實作」，開 PR 回本 repo
+5. 補漏：hotfix 與直接改 code 不會經過上面四步，`ade-spec-audit` 定期抓出這種規格漂移
+
+步驟 1、2 在本 repo 或工作目錄都能跑——在工作目錄時走 `ade-contribute`，改的是 `workspaces/` 下的工作副本，最後開 PR。
 
 ## 維護原則
 
-- 工作目錄裡的 ADE 內容是唯讀副本，update 會覆蓋。所有修改都回到本 repo 走 PR——agent 端由 `ade-contribute` / `ade-add-service` skills 引導完成
+- 工作目錄裡的 ADE 內容是唯讀副本，update 會覆蓋。所有修改都回到本 repo 走 PR——agent 端由 `ade-contribute` 引導完成
 - 知識分層：本 repo 只收跨服務知識、取得服務的最小資訊、產品規格三類——完整規則見 `knowledge/README.md`（canonical）
 - 使用中演化出的**機制**改良（skill 寫法、模板、流程），用 `ade-feedback-upstream` skill 回饋給 create-agentic-dev-env 上游；公司知識內容絕不外流

package/template/claude-md/section.md

@@ -5,7 +5,7 @@
 
 ### Session 開始時
 
-- **檢查知識新鮮度**：讀 `.ade.json`，執行 `git ls-remote <source> HEAD`，若 hash 與 `commit` 不符，提醒使用者執行 update 後再繼續（勿自行修改 managed 內容）
+- **檢查知識新鮮度**：讀 `.ade.json`，執行 `git ls-remote <source> HEAD`，若 hash 與 `commit` 不符，提醒使用者用 `ade-update` skill 更新後再繼續（勿自行修改 managed 內容）
 - Session 一律從本目錄（hub 根）開啟；在 `workspaces/<service>/` 內開啟會失去 ade skills
 
 ### 知識分層
@@ -21,4 +21,4 @@
 
 ### 知識維護
 
-`.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域、視同唯讀；回流、註冊服務、建立流程等維護動作由 ade-* skills 引導。
+`.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域、視同唯讀；註冊服務、新增 skill／流程、建 PRD、更新 spec 等維護動作由 ade-* skills 引導，一律經 `ade-contribute` 改 `workspaces/` 下的 ADE 工作副本並開 PR。

package/template/dot-claude/skills/ade-feedback-upstream/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ade-feedback-upstream
-description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結構、流程設計）以 issue 回饋給上游 create-agentic-dev-env 框架。使用者說「回饋上游」「這個改良應該進框架」「feedback upstream」時使用。
+description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結構、流程設計）以 issue 回饋給上游 create-agentic-dev-env 框架。使用者說「回饋上游」「這個改良應該進框架」「feedback upstream」時使用。僅在 ADE repo 內使用。
 ---
 
 # 回饋上游
@@ -14,7 +14,7 @@ description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結
 
 ## 流程
 
-1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）
+1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程收尾沉澱時經 `ade-contribute` 開出，如 ade-dev 第 5 關）
 2. **查重**：查上游的 open issues（`gh issue list -R <upstream>`），同一改良已有記錄 → 在該 issue 留言補充使用經驗，不重複開
 3. 開 issue（`gh issue create -R <upstream>`），內容包含：
    - 這個改良解決什麼問題

package/template/knowledge/process/README.md

@@ -28,3 +28,4 @@
 ## 現有主題
 
 - [git-commit.md](./git-commit.md) — commit 訊息採 Conventional Commits
+- [ade-dev-workflow/](./ade-dev-workflow/README.md) — `ade-dev`／`ade-dev-auto` 的唯一事實來源：狀態、六關、審查契約、auto-pilot、批次、CHANGELOG；各規則的證據盤點在上游框架的 `docs/research/ade-dev/`

package/template/knowledge/process/ade-dev-workflow/CHANGELOG.md

@@ -0,0 +1,6 @@
+# ade-dev workflow CHANGELOG
+
+> 每次規則異動一節，**在下一顆任務跑之前**寫好「預期痕跡」——可對 `.ade-dev/` 檔案或 `~/.claude/projects/<proj>/<session>/subagents/agent-*.jsonl` 判定的述語。事後回顧只做三件事：找 `spec.md` 的 `ade_commit` 在本節 commit 之後的任務、對每個 Phase 跑述語、填「判定」。判定分四種：留／改形狀／刪（觸發 0 且事故 0）／刪（照做仍出事）。
+>
+> 本檔給維護者讀，agent 不載入。
+

package/template/knowledge/process/ade-dev-workflow/README.md

@@ -0,0 +1,28 @@
+# ade-dev workflow：唯一事實來源
+
+`ade-dev`／`ade-dev-auto` 兩支 skill 的全部規則住在本目錄；skill 本身只是觸發與指標，**不複述任何判準的值**（檢查法：任改一個閾值後 grep 全 repo，命中必須恰好 1 處）。每次規則變動記入 [CHANGELOG.md](./CHANGELOG.md)，任務的 `spec.md` 以 `ade_commit` 對應到當時版本。
+
+## 誰在什麼時候讀哪份
+
+按角色載入，不整包讀——規則對讀不到它的人只是噪音。
+
+| 角色／時機 | 讀 |
+|---|---|
+| 任何 session 起手（接手判讀、執行模式判讀） | [state.md](./state.md) |
+| 走第 1、2、4、5、6 關 | [state.md](./state.md)＋[gates.md](./gates.md) 對應關 |
+| 第 3 關實作 Phase 的 worker | [gates.md](./gates.md) 第 3 關＋任務檔（`spec.md`、`plan.md`、`notes.md` 全文、本 Phase 的 `phase-N.md`） |
+| 派兩軸審查的一方 | [review.md](./review.md) |
+| 兩軸審查的審查者（prompt 只含這個） | [review.md](./review.md) 契約段＋diff＋`spec.md`＋`phase-N.md` |
+| auto 模式的 orchestrator | [state.md](./state.md)＋[auto-pilot.md](./auto-pilot.md) |
+| `ade-dev-auto` 批次 | [state.md](./state.md)＋[batch.md](./batch.md) |
+| 維護者回顧某次優化是否有效 | [CHANGELOG.md](./CHANGELOG.md)＋上游 `docs/research/ade-dev/` |
+
+## 檔案
+
+- [state.md](./state.md) — 詞彙、`.ade-dev/` 任務檔定義、狀態規則（單一真相）、接手判讀、執行模式判讀
+- [gates.md](./gates.md) — 六關的產出與過關判準
+- [review.md](./review.md) — 兩軸審查的派工規則與審查者契約（手動與 auto 同用）
+- [auto-pilot.md](./auto-pilot.md) — Spec Ready G1–G8、auto-pilot 執行規則、任務層煞車
+- [batch.md](./batch.md) — 批次串接的流程、B1–B4、熔斷、`auto-run.md`
+- [CHANGELOG.md](./CHANGELOG.md) — 規則異動紀錄：每次改了什麼、假設、事前寫好的預期痕跡、事後判定。**agent 不載入**
+- 各項規則的證據盤點（研究參考，非規則）住在上游框架的 [docs/research/ade-dev/](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev)，不隨 ADE repo 複製；規則檔以 URL 引用，每份檔頭有採用標注指回規則所在。含 `research-skill-boundaries.md`（skill 間引用與內容歸屬原則，`ade-ship` 亦引用）

package/template/knowledge/process/ade-dev-workflow/auto-pilot.md

@@ -0,0 +1,45 @@
+# Spec Ready 判定與 auto-pilot 模式
+
+兩種執行模式：**手動（預設）**——規格關、規劃關由人簽核；**auto-pilot**——Spec Ready 全 PASS 的任務可無人中途把關跑完六關：簽核點降為回報點（frontmatter 寫 `status: approved`＋`approved_by: spec-ready`），所有關的判準與兩軸審查照跑。單顆任務由人明說啟用；批次串接由 `ade-dev-auto` 負責。
+
+**Spec Ready 判定**——逐條列 PASS／FAIL，不打分數；任一 FAIL 即不得 auto，並輸出一句話理由（如「G3 不過：沒有可執行的測試指令」）。每條 gate 都帶**評估時機**，時機到了才評；未到時機的 gate 輸出 `DEFERRED` 而非省略，讓清單永遠是完整的 G1–G8。**Gate ID 一旦發布不重編、不回收**：廢止留佔位、新增只往後加——歷史 `notes.md` 與批次總結靠 ID 比對，重編號會讓舊紀錄語意漂移。依據與數字出處：[research-autopilot-readiness.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-autopilot-readiness.md)（採用其 §1.1 的 G1–G8，其中「交付定義完整」併入 G5，G5、G6 移至 plan.md 定稿後評估）、[research-gate-integrity.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-gate-integrity.md)。
+
+**任務啟動前評估**（資訊在 `spec.md` 就齊備）：
+
+- **G1** 需求來自已確認的 PRD，且產品規格有對應的 🚧 區塊
+- **G2** `spec.md` 每個行為描述可判定（可直接寫成測試）並指名 ≥ 1 個具體檔案路徑或介面名；無未決 open question（後者只是前提不是充分條件——它可以靠不提問刷出來）
+- **G3** 有可執行的驗證指令，動工前基準是綠的，單次執行 < 10 分鐘
+- **G4** 驗收測試在 `spec.md` 已定名（展開時只是細化成 Given/When/Then，不是現場發明）
+- **G7** 預期改動路徑不碰黑名單：認證授權、金流、DB migration、CI/CD 設定、密鑰與環境變數、對外 API 契約
+- **G8** 交付通道受限，且 MR 上有 agent 以外的自動驗證：
+  - 只走 MR（`ade-ship`），不得 push 主幹、不得自行 merge，merge 由人執行
+  - 目標 repo 有 CI，且會被本任務的 MR 觸發（repo 設定或 CI 設定檔查得到）
+  - **無 CI、或 CI 不會在 MR 上跑 → FAIL**，不得 auto（手動模式不受影響）；解法是加一條跑 G3 驗證指令的最小 workflow，加完重評即 PASS
+  - 例外只能由人逐案明示並記進 `notes.md`（無 CI 但 MR 描述附可一鍵重跑的驗證指令與預期輸出，人 merge 前自行重跑）——這是人工放行，不得由 agent 自行認定適用
+
+**`plan.md` 定稿後評估**（逐 Phase 檢查，任一 Phase 不過＝整顆任務不 Ready）：
+
+- **G5** 每個 Phase 的交付定義完整到能估出規模（1–3 行寫得清楚、預期改動檔案列得出來），且估出的規模在該 Phase 適用的硬閾值內（400 行／10 檔）；auto 模式加嚴：> 3 檔要在 `plan.md` 寫明理由（寫了就算過——要求解釋，不是上限）
+- **G6** repo > 800 檔或 > 300K 行時，G5 硬閾值折半（200 行／5 檔）
+
+手動模式下 G5／G6 由規劃關的人簽核涵蓋；auto 模式的重檢規則見下。
+
+**規劃後就緒重檢（auto 模式必做）**：第 2 關產出 `plan.md` 後、進第 3 關前，逐 Phase 重跑 G5／G6，結果逐條寫進 `notes.md`（auto 模式沒有人簽核，這份紀錄就是規劃關的過關證據）。全 PASS 才進實作關。FAIL 依成因二分處置：
+
+- **規模超標**（交付定義清楚，但估出的規模超過適用硬閾值）→ 允許**重切一次**：只能把 Phase 拆更小，不得改 `spec.md`、不得靠合併或改寫交付定義來壓低估計值（與「不得改測試斷言」同類漏洞）。重切後重跑 G5／G6，仍 FAIL 即停、降回手動
+- **資訊不足**（3 行寫不清楚、列不出預期改動檔案）→ **零容忍立即停**，不重切——這是規格層問題，重試零幫助
+
+**Auto-pilot 執行規則**：每個 Phase 派一個乾淨 context 的 subagent（worker）執行（等同手動模式的 `/clear` 換手）；每 Phase 一個 commit（merge-safe，訊息依 `ade-commit`）疊在任務分支上，任務結束依 `ade-ship` 發 MR。派工的主 session（orchestrator）是**可拋棄的派工者**，依據 [research-orchestrator-subagent.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-orchestrator-subagent.md)：
+
+- 每個 Phase 邊界**重跑一次接手判讀**，依檔案行事、不憑記憶；orchestrator 自身的 compaction 不構成煞車，也不需要記錄
+- worker **不得向人提問**（subagent 等人輸入是最典型的卡死）——不明確處即 `spec-gap` 停；不再派 subagent；單 Phase wall-clock 上限 30 分鐘（校準值；實戰 `pnpm migrate` 互動確認曾無聲卡死），逾時由 orchestrator 停掉它並煞車
+- worker 回傳**固定短格式**：`done` 或 `halted: <原因碼>`、實際行數／檔案數、最後一次測試摘要；AC 證據寫進 `phase-N.md` 交付紀錄、一行量測寫進 `notes.md`，不回傳。orchestrator 只依回傳行事，細節去檔案讀
+- worker 的 compaction 次數以其 transcript（`~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl`）中的 `compact_boundary` 事件數為準——被 compaction 刪過記憶的 agent，對自己 compaction 過幾次的自述不可信；worker 自報僅供比對
+- **修正輪**：兩軸審查有 blocking → 以 agentId 續用原 worker（SendMessage，保留完整實作脈絡）修正 → 換新的乾淨審查者重審。**預設 1 輪、最多 2 輪**，仍有 blocking 才煞車（輪數是工程判斷：Phase ≤ 400 行，兩輪修不掉就是規格或規劃問題）
+
+**Auto-pilot 煞車**（任務層）：
+
+- 零容忍即停：修改既有測試的斷言使其變綠／diff 碰到 G7 黑名單路徑／要動產品行為但 spec 無依據／兩軸審查**經修正輪後仍有** blocking finding（僅限影響正確性或違反明訂需求者，其餘列為建議不煞車；審查者幾乎必報 finding，未經修正輪就停等於停在恆真訊號上）／規劃後 G5／G6 重檢不過（規模超標者可重切一次，仍不過即停）／實際規模超過**該 Phase 適用硬閾值的 2 倍**——即 800 行／20 檔，命中 G6 折半後為 400 行／10 檔；兩維度分別判定，任一超過即停；行數計法與豁免項沿用第 3 關
+- 有限重試（兩個計數器分開）：測試紅了連續 3 次停，**CI 紅併入此計數器**；測試跑不起來（環境問題）另計連續 3 次停，**CI 跑不起來或長時間 pending 併入此計數器**；subagent 逾時（worker 單 Phase 30 分鐘、審查者重派一次仍逾時）直接記 `test-env` 停，不計次；worker 的 context compaction > 1 次記進 `notes.md`、> 2 次停（計法見執行規則）
+- 停下時**第一個動作**是在 `plan.md` frontmatter 寫 `halted: <原因碼>`，取值對應煞車條款：`test-tampering`／`blacklist-path`／`spec-gap`／`review-blocking`／`plan-recheck`／`oversize`／`test-red`／`test-env`／`compaction`。**存在即為不得自動續跑**，人裁決處理完刪除該行
+- 停下必附情境：停在哪個 Phase、哪條判準、最後一次測試輸出（frontmatter 記機器判讀用的原因碼，`notes.md` 記完整情境）

package/template/knowledge/process/ade-dev-workflow/batch.md

@@ -0,0 +1,36 @@
+# 批次串接：ade-dev-auto
+
+本檔**不定義任何任務內的判準、執行規則、煞車或狀態判讀規則**——Spec Ready 判定、auto-pilot 執行、任務層煞車見 [auto-pilot.md](./auto-pilot.md)，接手判讀見 [state.md](./state.md)。這裡只管批次：選取、就緒把關、依序執行、批次層熔斷。
+
+## 流程
+
+1. **列任務**：掃 `.ade-dev/*/`，對每個目錄套 `ade-dev` 的**接手判讀規則**得出卡在哪一關。供人多選。
+2. **逐顆跑 `ade-dev` 的 Spec Ready 判定**，逐條列 PASS／FAIL；就緒報告固定列滿 G1–G8，G5／G6 標 `DEFERRED（待 plan.md 定稿）`，規劃關結束後補判。
+3. **不合格的任務**問人：**補齊**（降回 `ade-dev` 手動模式補缺的關，補完歸隊重評）或**剔除**（整顆移出本批，不支援 Phase 級加選）。
+4. 全數就緒後**依序**逐顆以 `ade-dev` auto-pilot 模式執行，直到全部完成或命中熔斷。每顆啟動前確認：執行模式判讀為 auto（兩份 `approved_by` 皆 `spec-ready` 且無 `halted:`）、批次累計時間未超 B4 上限。每顆 `plan.md` 定稿後，以實際檔案清單對其他已定稿任務**重驗一次 B1**（啟動時只有預估，真實清單此刻才確定）。
+
+## 批次層判準（僅在此定義；依據 [research-autopilot-readiness.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-autopilot-readiness.md) §1.2、[research-batch-safety.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-batch-safety.md)）
+
+- **B1** 批次內任務的預期改動檔案互不相交（兩兩交集為空）。依序執行下這條防的不是併發寫入，是 MR 被人以未知順序 merge 時的必然衝突，以及熔斷失效時的污染上限（cell 邊界）
+- **B2** 一批 ≤ 5 顆，**依序逐顆執行、不併發**——併發加速的是 agent 的 wall-clock，瓶頸卻是人 merge 的頻寬；且兩顆同時跑會讓熔斷的「連續」失去定義。批次規模另受積壓扣減：**本批顆數 ≤ 5 −（目前由 auto-pilot 開出、尚未 merge 也未關閉的 MR 數）**，差額 ≤ 0 就不開批次、先請人清積壓；扣減時明說原因（「本批只能開 2 顆，因為還有 3 個 MR 沒 merge」）
+- **B3** 逐顆獨立評估與執行，單顆不合格或失敗只影響該顆
+- **B4** 單顆任務 wall-clock ≤ 60 分鐘；**批次總 wall-clock ≤ 4 小時**——每顆任務**開始前**檢查批次累計時間，超過就不再啟動下一顆（軟停，不中斷進行中的任務），輸出總結與未跑的任務清單
+
+## 批次熔斷
+
+任務內何時停由 `ade-dev` 的煞車決定；停下的任務其 `plan.md` 帶 `halted: <原因碼>`。批次層**只讀原因碼**判定，不自己歸納相似度：
+
+- **失敗類別**：`ERROR`（判斷不出來）＝原因碼 `test-env`；其餘原因碼皆為 `FAIL`（產出或規劃是壞的）
+- `ERROR` 類**連續 2 顆** → 停整批，不論停在哪一關——環境問題會在不同關爆，用關來判會漏
+- `FAIL` 類**連續 2 顆命中同一條原因碼** → 停整批；只是停在同一關但原因碼不同，不算同因
+- 其餘單顆失敗 → 該顆降回手動，批次繼續下一顆
+- 累計 3 顆失敗（不分類別）→ 停整批
+- 環境阻塞（主幹紅、build 壞、依賴服務掛）→ 第一次命中即停整批
+- **熔斷狀態不落檔**——接手時依 `auto-run.md` 的順序與各顆 `halted:` 重跑一次本節判定；環境阻塞當下重新觀察，不沿用上一個 session 的結論
+
+## 紀錄
+
+- `.ade-dev/auto-run.md` 是**批次層的決定紀錄，append-only**，一個批次一個 `##` 區段，只記**不會再變的決定**：批次 id（`YYYYMMDD-HHMM`）與建立時間、選入的任務目錄名依執行順序排成有序清單、剔除或要求補齊的任務與一句話理由。**禁記**（全部可從各任務 frontmatter＋checkbox 導出，寫進來就是第二份真相）：各顆卡在哪關、完成與否、批次執行到第幾顆、進度數字、熔斷是否觸發；**本檔不得出現 checkbox**
+- **接手續跑**：讀 `auto-run.md` 取得清單與順序 → 對每顆套 `ade-dev` 的接手判讀規則得到現況 → 重跑一次熔斷判定 → 沒熔斷就從第一顆未完成的任務續跑
+- Spec Ready 評估結果記進各任務自己的 `notes.md`
+- 批次結束輸出總結：交付了哪些 MR、剔除或降手動了誰、每顆停下的原因碼與失敗類別、為什麼

package/template/knowledge/process/ade-dev-workflow/gates.md

@@ -0,0 +1,60 @@
+# 六關：產出與過關判準
+
+## 第 1 關：規格
+
+產出：`spec.md`（實作規格）。過關判準：
+
+- 有 PRD 時以 PRD＋產品規格為據（工作目錄的 `.claude/ade/knowledge/` 副本僅供導航，過期以 ADE repo 為準）；無 PRD 時以需求描述為據
+- 已比對相關既有規格與服務：關聯、衝突、系統層級不一致已列出，並解決或經人裁決
+- 每個行為描述具體到可直接寫成測試
+- 所有不明確處已向人提問並得到答案
+- **人簽核後過關**（frontmatter 改 `status: approved`），**此後凍結**
+
+## 第 2 關：規劃
+
+產出：`plan.md`（Phase 地圖——看見全貌、分而治之）。過關判準：
+
+- 每個 Phase 只寫 1–3 行**交付定義**：完成後可觀察到什麼行為、為何合併安全（天然惰性的實作順序，或 feature flag）
+- 交付定義 3 行內寫不清楚、或「會動到哪些地方」列不出來 → Phase 太大，再拆
+- 軟判準（命中＝回頭檢查邊界）：觸及 ≥ 3 個模組、預估超過一兩天人力當量、或依賴另一個未完成 Phase 的產出 → 優先重切
+- Phase 依賴構成 DAG；預設依序交付，是否並行、如何隔離是 agent 的自由，不在此規定
+- **人簽核後過關**（frontmatter 改 `status: approved`）。之後 agent 可修訂未來 Phase（在 `notes.md` 留痕原因）；動到已交付 Phase 的行為才回人
+
+## 第 3 關：實作（逐 Phase，輪到才展開）
+
+起手讀 `spec.md`＋`plan.md`＋`notes.md` 全文＋本 Phase 的 `phase-N.md`；其他 Phase 的 `phase-N.md` 不讀，除非 `plan.md` 的 checkbox 指過去。展開：建 `phase-N.md`，把交付定義細化為 Given/When/Then AC＋Tasks checklist。未輪到的 Phase 不展開。過關判準：
+
+- 每條 AC 可回溯到交付定義的某一句
+- 每完成一個 Task 即勾掉 `phase-N.md` 的 checkbox——這是 Phase 內唯一的進度紀錄，寫在任何 compaction 之前；Phase 內發生 compaction 後的**第一個動作**固定是重讀 `spec.md`＋`phase-N.md`，覆述當前 AC 與下一個未勾 Task 再續（文檔是真相、context 是快取）
+- 硬觸發（命中必拆，停下回報）：預估 diff **> 400 行**或改動**> 10 個檔案**——以「人要逐行讀的行數」計，整檔刪除、工具產生的機械 refactor、產生檔豁免。提示訊號（不強制拆但要說明理由）：AC > 8 條；AC 需要先建測試基礎設施才寫得出來 → 把基礎設施抽成前置 Phase。數字依據與校準方式見 [research-phase-sizing.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-phase-sizing.md)
+- Phase 交付後在 `notes.md` 記**一行量測**（固定欄位，供跨任務 grep）：`[量測] P<N> 行數=<n> 檔數=<n> 預估行數=<n> 分鐘=<n> compaction=<n> blocking=<真/不成立> 修正輪=<n> 人介入=<n> session=<$CLAUDE_CODE_SESSION_ID> agent=<id或main>`——session 與 agent 用來定位 transcript（`~/.claude/projects/<proj>/<session>/subagents/agent-<id>.jsonl`），回顧時據此判定 agent 實際讀了什麼、派了什麼；審查處置、預估 vs 實際的分析、AC 證據（測試檔名與結果摘要）寫進 `phase-N.md` 的「交付紀錄」段，不進 `notes.md`
+- 每條 AC 有自動化測試，且該測試在實作完成前**失敗過**（紅→綠，順序本身就是證據）
+- 既有代碼的順手優化僅限本 Phase 觸及的檔案；更大的重構記進 `notes.md`，不做
+- 交付前**兩軸審查**：派兩個乾淨 context 的 subagent 平行檢查、分開報告，不合併排名——(a) 規格符合度：對照 `spec.md`＋`phase-N.md`，找缺漏、越界、做錯；(b) 代碼品質：對照本 repo 的慣例與文件化標準。**派工規則**（手動與 auto 同用，依據 [research-orchestrator-subagent.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-orchestrator-subagent.md)）：
+  - 派工規則與審查者契約見 [review.md](./review.md)
+- 合併後主幹隨時可部署（merge-safe；實際部署節奏與本流程無關）
+
+## 第 4 關：測試審視
+
+全部 Phase 交付後，整體看一次測試。auto 模式由**乾淨 context 的 subagent** 執行（寫測試的人看不出自己的假綠；手動模式由人反問補上這一層）。過關判準：
+
+- 每條 AC 有測試覆蓋，測的是公開介面的行為，不是實作細節（重構不應弄壞測試）
+- 沒有恆真測試（期望值用與實作相同的方式算出，永遠通過）
+- 沒有驗證第三方套件已保證的行為；沒有重複測同一件事的測項
+
+## 第 5 關：沉澱
+
+過關判準：
+
+- 產品規格與實作一致：有 PRD 走 `ade-align-spec`；無 PRD 但動了產品行為 → 起草產品規格更新、**人確認後**依 `ade-contribute` 流程送出
+- `notes.md` 收整成清單給人審視：關鍵發現、決策、流程摩擦與改良建議
+- 清單中屬**機制層**的改良（skill 寫法、模板結構、流程設計，非本服務專屬），依 `ade-contribute` 在 ADE repo 開一則標題前綴 `[upstream-candidate]` 的 issue——內文只描述機制、不含服務名稱與程式碼；是否回饋上游由 ADE repo 維護者判斷，**不在本流程內執行**
+
+## 第 6 關：Ship
+
+產出：已發出的 Merge Request。過關判準：
+
+- 分支上的 commits 符合 `ade-commit` 解析出的慣例（專案自有規範優先，無則 ADE 預設）
+- MR 依 `ade-ship` 發出：專案有 PR／MR 範本用專案的，沒有用 ADE 內建預設範本
+- MR 描述涵蓋交付定義、AC 驗證證據、與規格的已知差異
+- 發出即過關；**merge 由人執行**，不等 merge 才勾（Phase 級的合併若也走 MR，同樣用 `ade-ship` 發）。**auto 模式加一條**：MR 發出後 CI 須轉綠才算交付完成——CI 未跑完就結束的任務標記為未完成，不計入批次成功

package/template/knowledge/process/ade-dev-workflow/review.md

@@ -0,0 +1,9 @@
+# 兩軸審查：派工規則與審查者契約
+
+適用手動與 auto 模式；審查者 prompt 只含本檔的契約段。依據 [research-orchestrator-subagent.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-orchestrator-subagent.md)。
+
+- 審查者由**派工的一方**派，不由實作者派——做的人不評自己；經實作者轉述的審查報告必然失真。只給 diff＋`spec.md`＋`phase-N.md`，不給實作過程的推理
+- 派 subagent **不傳 `name`**（agent teams 開啟時具名 subagent 會變成 teammate，完成只送不帶輸出的 idle 通知，等待結果的流程會卡死）；派出後**實際確認** transcript 在長，不被動等通知
+- 審查者之間、審查者與實作者之間**不得同時跑全套測試**——worktree 只隔離檔案，共用的 DB／port 互踩會讓測試被標 skipped 而非 failed；審查 prompt 明寫只跑單一 spec、跑前確認沒人在跑
+- 審查者**唯讀**（可跑指令重現，不得改 repo 檔案）、不再派 subagent。回傳**固定格式**：每條 finding 附 `file:line` 或「指令＋實際輸出片段」並標 blocking／建議；另列「查過但不存在」與「不確定、交派工方判斷」；未完成也按此格式回報已查部分。收到後**抽驗至少一條** finding 的證據真的存在——實戰有審查誤判。wall-clock 上限 20 分鐘（校準值），逾時重派一次
+- 審查者**幾乎必定**會報 finding，這是它被要求做的事；只把影響正確性或違反明訂需求者視為 blocking。有 blocking → **實作者修正**（續用原 context，它知道當初為何這樣寫）→ **換新的乾淨審查者**重審，不回給原審查者

package/template/knowledge/process/ade-dev-workflow/state.md

@@ -0,0 +1,40 @@
+# 狀態與檔案
+
+每一關只定義「產出＋過關判準」。判準是可檢查的狀態，不是動作；**如何達成由 agent 自行決定**。狀態全部活在檔案裡，任何 session 讀檔即可接手（每個 Phase 交付後建議 `/clear` 換新 session 接續，控管 context）。
+
+## 詞彙
+
+- **關**＝流程階段邊界；**Phase**＝可獨立交付的開發單位，輪到才展開；**Task**＝Phase 展開後的 checklist 項，無獨立契約
+- **產品規格**＝ADE `knowledge/specs/` 的長期資產，只有人能拍板；**實作規格**＝只描述本次開發範圍，簽核後凍結
+- **煞車**＝任務層的執行期停止條件（本 skill 定義）；**熔斷**＝批次層的停止條件（`ade-dev-auto` 定義），兩詞不混用
+
+## 檔案
+
+```
+.ade-dev/{YYYYMMDD}-{slug}/
+├── spec.md      # 實作規格（規格關簽核後凍結，不再更新）（frontmatter：status／approved_by／ade_commit）
+├── plan.md      # Phase 地圖（活的：每 Phase 1–3 行交付定義＋checkbox＋依賴）（frontmatter：status／approved_by／停機時 halted）
+├── phase-N.md   # 展開產物（輪到才建：AC＋Tasks checklist）＋交付紀錄（審查處置、預估 vs 實際的分析、AC 證據）——一個 Phase 的完整故事，只讀當前
+└── notes.md     # 跨 Phase 仍有效的事（append-only；每則以 [裁決]／[發現]／[摩擦]／[失敗]／[修訂] 開頭）：人裁決、規格關發現、環境坑、失敗路徑【做了什麼／預期／實際／推論】、plan 修訂原因、Spec Ready 結果、每 Phase 一行量測
+```
+
+狀態規則（單一真相，每個事實只記一處，不另設 status.json／progress.md——第二份真相必漂移，依據見 [research-devflow-state.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-devflow-state.md)、[research-auto-state.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-auto-state.md)）：
+
+- `spec.md`、`plan.md` 檔頭 YAML frontmatter `status: draft`，**過關時**改為 `status: approved`（逐字一致，工具靠精確匹配）
+- `spec.md` 建檔時寫 `ade_commit: <工作目錄 .ade.json 的 commit>`——任務跑在哪個版本的流程下；中途 `ade-update` 換版在 `notes.md` 記一則 `[修訂]`。這是日後回顧「某次流程優化是否有效」的分組依據
+- 同一次寫入 `approved_by`：人簽核寫 `human`，auto-pilot 由 Spec Ready 替代簽核寫 `spec-ready`。**此欄位一經寫入不得修改**——它記的是當時誰簽的，不是現在的模式；缺席視同 `human`。人事後補審 auto 簽的文件，在 `notes.md` append 一則，不回頭改本欄位
+- Phase 進度只記在 `plan.md` 的 checkbox（`- [ ]`／`- [x]`，小寫 x）；`phase-N.md` 不重複記自己的完成狀態
+- `plan.md` 底部固定三個收尾項：`- [ ] 測試審視`、`- [ ] 沉澱`、`- [ ] Ship`，對應第 4、5、6 關過關時勾掉
+- **留給後續的事項**（審查確認但不在本 Phase 修、交接點、留給第 4 關的）寫成 `plan.md` 目標 Phase 或收尾項底下的子 checkbox——待辦是活的，不進 append-only 的 `notes.md`
+
+**接手判讀**（任何 session 讀檔即可接手；依序判斷，**讀到能決定下一步就停**）：
+
+1. 沒有 `spec.md` → 從第 1 關開始
+2. `spec.md` 的 `status` 不是 `approved` → 卡在第 1 關
+3. 沒有 `plan.md`，或其 `status` 不是 `approved` → 卡在第 2 關
+4. `plan.md` 有 `halted:` → **停**。不論其他狀態如何都不得自動續跑；把原因碼與 `notes.md` 最後一則交給人裁決，人刪掉該行才恢復
+5. `plan.md` 有未勾的 Phase → 卡在第 3 關。該 Phase 已有 `phase-N.md` 就從未勾的 Task 續，沒有就展開它
+6. Phase 全勾 → 底部三個收尾項第一個未勾者即所在的關（測試審視＝第 4 關、沉澱＝第 5 關、Ship＝第 6 關）
+7. 全部勾完 → 已完成
+
+**執行模式判讀**：`spec.md` 與 `plan.md` 的 `approved_by` **皆為** `spec-ready`、且無 `halted:` → 續跑 auto-pilot；其餘一切情形（任一為 `human`、任一缺欄位、任一檔案不存在）→ **手動模式**。判不出來就是手動，不猜。

package/template/knowledge/specs/GLOSSARY.md

@@ -0,0 +1,13 @@
+# 產品域詞彙（canonical）
+
+產品規格共用的詞彙表。根目錄的 `CONTEXT.md` 是**開發流程**的詞彙，兩份互不重疊——流程詞講「怎麼做事」，本檔講「產品在講什麼」。
+
+寫 PRD 或 spec 時沿用這裡的詞；`_Avoid_` 列的是實際發生過混淆的同義詞，不是禁用字，而是「用了要自覺會被誤解」。
+
+## Language
+
+<!-- 一詞一條，格式：
+**詞（English）**:
+一句定義。
+_Avoid_: 實際發生過混淆的同義詞
+-->

package/template/knowledge/specs/README.md

@@ -17,3 +17,7 @@
 - 開發完成後由 `ade-align-spec` skill 核對實作、依 PRD 檔名精準移除
 
 讀 spec 時：無標記＝已上線的現況，有標記＝已定案但還沒做。
+
+## 詞彙
+
+產品域的共用詞彙在 [GLOSSARY.md](./GLOSSARY.md)（屬性、家族、規格值、型號…）。寫 spec 或 PRD 時沿用該檔的用詞；發現新詞或撞名時一併更新它，不要在各文件裡各自定義。根目錄的 `CONTEXT.md` 是**開發流程**的詞彙，兩份互不重疊。

package/template/skills/ade-add-process/SKILL.md

@@ -26,9 +26,9 @@ description: 為團隊建立或修改流程慣例並落地到 ADE 知識庫。
 
 ## 3. 落地
 
-1. 依 `ade-contribute` skill 流程 clone ADE repo、建分支（含查重：同一流程已有 issue/PR 就別重開）
-2. 寫 `knowledge/process/<主題>.md`（細節層，kebab-case 檔名）
-3. 需要 skill 的：依 `ade-add-skill` skill 建立（它管使用對象選擇、放置位置與命名規則）
-4. 需要常駐行的：在 `claude-md/section.md` 適當小節加一行指標
-5. 更新 `process/README.md` 的主題索引
-6. 依 `ade-contribute` 慣例開 PR；merge 後各工作目錄 update 即生效
+0. **判斷所在位置**：repo 根有 `knowledge/process/` → 你在 ADE repo 內，直接編輯本 repo 檔案；只有 `.claude/ade/knowledge/` → 你在工作目錄，依 `ade-contribute` skill 的流程取得 ADE 工作副本並建立分支（含查重：同一流程已有 issue/PR 就別重開），以下所有路徑都指工作副本內的檔案（絕不直接改 `.claude/ade/` 副本）
+1. 寫 `knowledge/process/<主題>.md`（細節層，kebab-case 檔名）
+2. 需要 skill 的：依 `ade-add-skill` skill 建立（它管使用對象選擇、放置位置與命名規則）
+3. 需要常駐行的：在 `claude-md/section.md` 適當小節加一行指標
+4. 更新 `process/README.md` 的主題索引
+5. 收尾：ADE repo 內 → 照一般 git 慣例 commit；工作目錄 → 依 `ade-contribute` 流程開 PR。merge 後各工作目錄 update 即生效

package/template/skills/ade-commit/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: ade-commit
+description: 在服務 repo 產生符合慣例的 git commit——專案自有規範優先，沒有就用 ADE 預設（Conventional Commits）。使用者說「commit」「提交」「幫我 commit」，或任何流程（ade-dev、ade-ship）需要 commit 時使用。
+---
+
+# ade-commit：commit 訊息慣例解析
+
+決定「這個 repo 的 commit 該長什麼樣」，依序找，找到第一個就停：
+
+1. **專案自述**：服務 repo 的 `CLAUDE.md`／`AGENTS.md`（有哪個讀哪個）、`CONTRIBUTING.md` 中的 commit 規範
+2. **專案設定檔**：commitlint 設定（`.commitlintrc*`、`commitlint.config.*`）、`.gitmessage` 範本
+3. **既有風格**：`git log --oneline -20` 的實際風格明顯一致時，沿用它
+4. **ADE 預設**：`.claude/ade/knowledge/process/git-commit.md`（Conventional Commits）
+
+規則：
+
+- 一個 commit 一件事；混雜多個意圖時拆開
+- body 說「為什麼改」，不重述 diff
+- 同一 repo 同一 session 內解析一次即可，不必每次 commit 重找

package/template/skills/ade-contribute/SKILL.md

@@ -1,20 +1,24 @@
 ---
 name: ade-contribute
-description: 將工作過程中發現的知識缺口、過期文件、新慣例回流到中央 ADE 知識庫。發現 .claude/ade/knowledge/ 內容與現實不符、缺少資訊，或使用者說「把這個記回知識庫」「更新 ADE」「回流」時使用。
+description: 從工作目錄修改中央 ADE 知識庫並開 PR——包含主動撰寫（新增或調整 spec、skill、process、服務描述檔）與被動回流（發現 .claude/ade/knowledge/ 內容過期或缺漏）。使用者說「改 ADE 的 spec／skill」「把這個記回知識庫」「更新 ADE」「回流」時使用。
 ---
 
 # ADE 知識回流
 
-本地 `.claude/ade/` 是 managed 區域，`update` 時會被整個覆蓋——**永遠不要直接修改本地副本**，把修正送回中央 ADE repo。
+本地 `.claude/ade/` 是 managed 區域，`update` 時會被整個覆蓋——**永遠不要直接修改本地副本**，一切修改都在 ADE repo 的工作副本上進行、走 PR 回去。
 
 ## 流程
 
 1. 讀工作目錄的 `.ade.json` 取得 `source`（ADE repo 的 git url；為 null 則請使用者補上）
-2. **查重**：查 ADE repo 的 open issues 與 open PRs（`gh issue list` / `gh pr list`），同一缺口已有記錄 → 在該 issue/PR 留言補充你的發現，到此結束，不重複開
-3. **開 issue 記錄缺口**：一段話描述缺什麼／哪裡過期、在哪個工作情境發現的——issue 是查重與追蹤的協調點
-4. Clone 到暫存目錄：`git clone <source> <tmpdir>/ade`，建立分支，修改 `knowledge/` 下對應文件
+2. **取得工作副本**：`workspaces/<ade-repo-name>/`（repo 名取自 `source`）已存在就直接用，不存在才 `git clone <source>` 到那裡——ADE repo 與服務 repo 一樣放 workspaces，不用 tmpdir，才不會每次重 clone、也保得住未 push 的工作
+   - 開工前 `git fetch origin` 並從最新主幹開分支：`git switch -c <branch> origin/main`
+3. **判斷起點**，兩種：
+   - **主動撰寫**（使用者明確要求新增或調整 spec、skill、process、服務描述檔）→ 不開 issue，直接進第 4 步
+   - **被動回流**（工作中發現知識庫過期或缺漏）→ 先查重：`gh issue list` / `gh pr list`，同一缺口已有記錄就在該 issue/PR 留言補充，到此結束；沒有才開 issue 描述缺什麼／哪裡過期／在哪個工作情境發現的，issue 是查重與追蹤的協調點
+4. 修改 `knowledge/` 下對應文件
    - 修改前先讀原文，沿用既有格式與詞彙
    - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）
-5. Commit、push 分支，開 PR 並連結 issue（描述加 `Closes #<issue 編號>`；GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）
+   - 新增或修改 skill 走 `ade-add-skill`，新增流程慣例走 `ade-add-process`——它們負責放置位置與 README 同步，收尾一樣回到本流程
+5. Commit、push 分支，開 PR（GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）；被動回流的 PR 描述加 `Closes #<issue 編號>`
    - gh/glab 不可用或未登入時的降級路徑：push 分支後，把 compare／new-MR 網址給使用者，請人手動開
-6. 告知使用者 PR 連結；merge 後在工作目錄執行 update 即可取得新版
+6. 告知使用者 PR 連結，並把工作副本切回主幹（`git switch main`）留給下次；merge 後在工作目錄執行 update 即可取得新版

package/template/skills/ade-create-prd/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ade-create-prd
+description: 依統一範本建立標準化 PRD，寫入 knowledge/prd/。想法還模糊就先用 Discovery 問成形，已想清楚就直接填。使用者說「建 PRD」「寫需求文件」「幫我寫一份 PRD」「把這個想法變成 PRD」「新的開發需求」「這個需求整理一下」「create PRD」時使用。bug fix／refactor／文字調整不用開 PRD。
+---
+
+# 建立 PRD
+
+PRD 的定位、生命週期與檔名規則見 `knowledge/prd/README.md`，欄位結構以 `knowledge/prd/_template.md` 為準。本檔只寫「怎麼跑」。
+
+0. **判斷所在位置**：repo 根有 `knowledge/prd/` → 你在 ADE repo 內，直接編輯本 repo 檔案；只有 `.claude/ade/knowledge/` → 你在工作目錄，依 `ade-contribute` skill 的流程取得 ADE 工作副本並建立分支，以下所有 `knowledge/...` 路徑都指工作副本內的檔案（絕不直接改 `.claude/ade/` 副本）
+
+## 1. Discovery——問到想法成形
+
+**已經有答案的題目直接跳過，不要重問**；使用者一開口就把七題講完就整段略過，直接進第 2 步。
+
+用 `AskUserQuestion` 分批問缺的題，**一批 2–3 題，等回答再追問**，不要一次丟完。七題都有實質答案（或明確說「這題不在範圍」）才能往下。
+
+1. 想做什麼？（一句話）
+2. 為誰做？（Persona 寫成敘述，不是人口統計）
+3. 解決什麼痛點？（**只寫痛點，不寫解方**）
+4. 為何是現在？（deadline／法規／客戶／競爭）
+5. 怎麼算成功？（可量測：baseline + target + 量測方式）
+6. 範圍：做什麼、**明確不做什麼**
+7. 影響哪些服務、相依哪些既有 PRD／spec？
+
+紅線：答案含糊就追問，不要幫使用者猜；沒答案的留著，第 3 步進「開放問題」；Discovery 階段不談實作與 schema。
+
+## 2. 對照既有知識
+
+讀 `knowledge/services/index.md`、相關 `knowledge/specs/`，以及 `knowledge/prd/` 下狀態非「已實作」的 PRD。用團隊既有詞彙、對照現有規格找出衝突；與進行中 PRD 重疊時當場請 PO 決定合併或劃清界線。
+
+## 3. 建檔
+
+複製 `knowledge/prd/_template.md` 為 `knowledge/prd/YYYY-MM-DD-<slug>.md`（slug 用 kebab-case，日期用今天），狀態設「草稿」，逐區塊填寫：
+
+| 範本區塊 | 來源 |
+|---|---|
+| 背景與目標 | Q3 痛點 + Q4 時機 + Q5 成功標準 |
+| 非目標 | Q6 明確不做的部分（**不可空白**） |
+| 需求描述 | Q1/Q2 展開成使用者故事與操作流程，具體到能開發 |
+| 影響服務 | Q7 對照 services/index.md，列出各服務要改什麼 |
+| 驗收條件 | 每條可測試，形容詞（好用／快）換成可驗證敘述 |
+| 開放問題 | Discovery 中沒答案、待 PO 拍板的 |
+
+「Spec 異動摘要」留空，那是 `ade-prd-to-spec` 的欄位。
+
+## 4. 盲點拷問
+
+逐項問到 PO 每題都有明確答案或明確說「不在範圍」，結果回填文件（範圍外的寫進「非目標」，未定的寫進「開放問題」）：
+
+- **邊界與錯誤**：輸入不合法、資源不存在、操作中斷、併發衝突時各是什麼行為？
+- **跨服務影響**：對照 services 總覽，有沒有漏列受影響的服務？服務間的呼叫順序與失敗處理？
+- **權限與安全**：誰能用這功能？資料存取邊界？
+- **相容性**：既有資料要遷移嗎？舊版本客戶端／既有 API 使用者會壞嗎？
+- **驗收條件**：每一條都可測試嗎？「好用」「快」這類形容詞要換成可驗證的敘述
+- **非目標**：最容易被誤以為包含在內的相鄰功能是什麼？明確排除
+
+## 5. 驗證與收尾
+
+```bash
+bash .claude/skills/ade-create-prd/validate-prd.sh <PRD 檔的實際路徑>
+```
+
+有缺漏就補完再跑。通過後**不要自動翻狀態**——狀態留在「草稿」，由 PO 確認後才改「已確認」。收尾：ADE repo 內 → 照一般 git 慣例 commit；工作目錄 → 依 `ade-contribute` 流程開 PR。最後提醒下一步跑 `ade-prd-to-spec` 更新規格。

package/template/skills/ade-create-prd/validate-prd.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# 檢查 PRD 是否可送出。用法:bash .claude/skills/ade-create-prd/validate-prd.sh <prd.md>
+set -u
+f="${1:?用法: validate-prd.sh <prd.md>}"
+[ -f "$f" ] || { echo "✗ 檔案不存在:$f"; exit 1; }
+bad=0
+
+# 每個必填區塊都要有實質內容(下一個 ## 之前有非空、非註解行)
+for sec in 背景與目標 非目標 需求描述 影響服務 驗收條件; do
+  body=$(awk -v s="## $sec" '$0==s{f=1;next} /^## /{f=0} f' "$f" | grep -vE '^\s*(<!--.*)?$')
+  [ -n "$body" ] || { echo "✗ 區塊沒內容:$sec"; bad=1; }
+done
+
+grep -qE '^- 狀態: (草稿|已確認|已實作)' "$f" || { echo "✗ 狀態欄位缺或不是三種合法值之一"; bad=1; }
+grep -qE '^- 提出者: *\S' "$f" || { echo "✗ 提出者未填"; bad=1; }
+grep -qE '^- 日期: [0-9]{4}-[0-9]{2}-[0-9]{2}' "$f" || { echo "✗ 日期未填或格式不對"; bad=1; }
+grep -qE '^- \[ \] .*\S' "$f" || { echo "✗ 驗收條件沒有 checkbox 項目"; bad=1; }
+placeholders=$(grep -nE "<標題>|YYYY-MM-DD|TODO|TBD|FIXME" "$f" || true)
+[ -z "$placeholders" ] || { echo "✗ placeholder 未清:"; echo "$placeholders"; bad=1; }
+
+[ "$bad" = 0 ] && echo "✓ 通過,PRD 可送出" || echo "✗ 未通過,補完再送"
+exit $bad

package/template/skills/ade-dev/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: ade-dev
+description: 判準制標準開發流程——針對 PRD 或自然語言需求，走「規格→規劃→逐 Phase 實作→測試審視→沉澱→Ship」六關開發；內建 Spec Ready 判定與 auto-pilot 模式（就緒即可無人中途把關跑完）。使用者說「開始開發」「照流程開發這個需求／PRD」「ade-dev」「繼續開發」「接手下一個 Phase」「這個任務 auto 跑」時使用。在服務工作目錄內使用。
+---
+
+# ade-dev
+
+規則全部在 ADE `knowledge/process/ade-dev-workflow/`（工作目錄內為 `.claude/ade/knowledge/process/ade-dev-workflow/`），本 skill 不複述。
+
+起手：讀該目錄的 `README.md`，依「誰在什麼時候讀哪份」只載入你這個角色需要的檔——起手一律先讀 `state.md` 做接手判讀與執行模式判讀，再依所在的關載入 `gates.md` 對應段；派審查讀 `review.md`；auto 模式的 orchestrator 另讀 `auto-pilot.md`。派出的 worker 與審查者 prompt 同樣只給它們那一片，不整包貼。

package/template/skills/ade-dev-auto/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: ade-dev-auto
+description: 串接多個 ade-dev 任務的批次執行器——列出工作目錄中未完成的開發任務、多選、逐顆確認 Spec Ready，全數就緒後依序以 ade-dev auto-pilot 模式跑完。使用者說「批次開發」「把這些任務自動跑完」「ade-dev-auto」時使用。在服務工作目錄內使用；單顆任務（含單顆 auto 跑）直接用 ade-dev。
+---
+
+# ade-dev-auto
+
+規則全部在 ADE `knowledge/process/ade-dev-workflow/`（工作目錄內為 `.claude/ade/knowledge/process/ade-dev-workflow/`），本 skill 不複述。
+
+起手：讀 `state.md`（接手判讀、執行模式判讀）與 `batch.md`（流程、B1–B4、熔斷、`auto-run.md`）；逐顆任務的 Spec Ready 判定與 auto-pilot 執行依 `auto-pilot.md`，其餘依 `ade-dev` 的角色載入規則。

package/template/skills/ade-help/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ade-help
+description: 列出當前位置可用的 ade-* skills 與各自用途。使用者說「有哪些 skill」「ade help」「我可以做什麼」「ADE 支援什麼」「skill 一覽」時使用。要列服務用 ade-list-service，不是這支。
+---
+
+# ADE skills 一覽
+
+清單一律從 `.claude/skills/` 現況掃出來，**不要憑記憶列**——skill 會搬家、會新增，寫死的清單必然過期。
+
+## 流程
+
+1. 執行：
+   ```bash
+   bash .claude/skills/ade-help/list-skills.sh
+   ```
+   輸出每行是 `name<TAB>description`。掃的就是當前位置真正載得到的 skills，所以在工作目錄列到的是注入的那套、在 ADE repo 列到的是 repo 內那套，不需要額外判斷
+2. 整理成表格給使用者：skill 名稱、一句話用途（把 description 的觸發語濃縮成「什麼時候用它」，不要整段照貼）
+3. 開頭一行說明當前位置：repo 根有 `knowledge/services/` → 「你在 ADE repo，以下是本 repo 內可用的 skills」；只有 `.claude/ade/knowledge/` → 「你在工作目錄，以下是注入的 skills」
+4. 使用者想知道某支細節時才讀那支的 `SKILL.md`——一次全讀進 context 是浪費
+
+在 ADE repo 內時補一句：`skills/` 下另有只注入工作目錄、本 repo 不載入的 skills（`bash skills/ade-help/list-skills.sh skills` 可列），要改它們用 `ade-add-skill`。

package/template/skills/ade-help/list-skills.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# 列出指定目錄下可用的 ade-* skills(名稱 TAB description)。
+# 用法:bash .claude/skills/ade-help/list-skills.sh [skills 目錄,預設 .claude/skills]
+set -u
+dir="${1:-.claude/skills}"
+n=0
+for f in "$dir"/ade-*/SKILL.md; do
+  [ -f "$f" ] || continue
+  n=$((n+1))
+  name=$(sed -n 's/^name: *//p' "$f" | head -1)
+  desc=$(sed -n 's/^description: *//p' "$f" | head -1)
+  printf '%s\t%s\n' "${name:-$(basename "$(dirname "$f")")}" "$desc"
+done
+[ "$n" -gt 0 ] || echo "找不到 ade-* skills($dir)" >&2
+exit 0

package/template/skills/ade-list-service/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: ade-list-service
+description: 列出 ADE 知識庫目前所有已註冊的服務。使用者說「列出服務」「有哪些服務」「目前註冊了哪些服務」「list services」時使用。只讀不改；要新增或修改服務用 ade-add-service。
+---
+
+# 列出已註冊服務
+
+1. **判斷所在位置**：repo 根有 `knowledge/services/` → 你在 ADE repo 內，讀 `knowledge/services/`；只有 `.claude/ade/knowledge/` → 你在工作目錄，讀 `.claude/ade/knowledge/services/`
+2. 讀該目錄的 `index.md` 總覽表，同時列出目錄下的 `*.yaml`（排除 `_template.yaml`）
+3. 兩者比對：`yaml` 存在但總覽表沒列（或反之）→ 一併回報為不一致，提示用 `ade-add-service` 補齊
+4. 輸出服務清單：每列「服務名｜定位（取自總覽表）｜描述檔路徑」。要看某服務細節時再讀對應 `<service>.yaml`，不要預先全部載入

package/template/{dot-claude/skills → skills}/ade-prd-to-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ade-prd-to-spec
-description: 將已確認的 PRD 融入 specs，標記尚未實作區塊，供 PO 確認 PRD 與 spec 對齊。使用者說「PRD 轉 spec」「更新規格」「把 PRD 落到 spec」時使用。僅在 ADE repo 內使用。
+description: 將已確認的 PRD 融入 specs，標記尚未實作區塊，供 PO 確認 PRD 與 spec 對齊。使用者說「PRD 轉 spec」「更新規格」「把 PRD 落到 spec」時使用。
 ---
 
 # PRD → Spec
@@ -9,6 +9,8 @@ description: 將已確認的 PRD 融入 specs，標記尚未實作區塊，供 P
 
 ## 流程
 
+0. **判斷所在位置**：repo 根有 `knowledge/specs/` → 你在 ADE repo 內，直接編輯本 repo 檔案；只有 `.claude/ade/knowledge/` → 你在工作目錄，依 `ade-contribute` skill 的流程取得 ADE 工作副本並建立分支，以下所有 `knowledge/...` 路徑都指工作副本內的檔案（絕不直接改 `.claude/ade/` 副本）
+
 1. 讀目標 PRD 與 `knowledge/specs/` 現況，找出受影響的 spec 檔（沒有對應檔就依 `specs/README.md` 慣例新建）
 2. 將 PRD 需求融入 spec：描述「功能完成後應有的樣子」，並在每個新增／變更的行為區塊上方加標記行，**格式逐字照抄、只替換檔名**（align-spec 靠精確匹配移除，變體會漏抓）：
    ```
@@ -18,6 +20,6 @@ description: 將已確認的 PRD 融入 specs，標記尚未實作區塊，供 P
 3. 只動這次 PRD 涉及的內容，spec 其餘部分一字不改
 4. 回填 PRD 的「Spec 異動摘要」：動了哪些檔、各自異動重點
 5. 帶 PO 逐項確認 spec 與預期相符，不符就修到對齊為止
-6. PO 確認後 commit（或依團隊慣例開 PR）
+6. PO 確認後收尾：ADE repo 內 → 照一般 git 慣例 commit；工作目錄 → 依 `ade-contribute` 流程開 PR
 
 完成後提醒：RD 開發完成後在工作目錄跑 `ade-align-spec` 收尾。

package/template/skills/ade-ship/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ade-ship
+description: 從服務 repo 的分支發出 Merge Request / Pull Request——用 gh 或 glab CLI（不可用時退 API），MR 內容依專案自有範本，沒有就用 ADE 內建預設範本。使用者說「發 MR」「開 PR」「ship」「送出 merge request」，或 ade-dev 第 6 關、ade-dev-auto 交付時使用。
+---
+
+# ade-ship：發出 MR
+
+## 1. 偵測平台與工具
+
+看 `git remote get-url origin`：GitHub → `gh`；GitLab（含 self-hosted）→ `glab`。CLI 不存在或未登入時退平台 API（環境有 token 才用），都不行就停下請人處理——不要偽造成功。
+
+## 2. 解析範本（找到第一個就停）
+
+檔名比對一律**大小寫不敏感**（`find -iname`）——GitHub／GitLab 文件未保證大小寫敏感，實務上兩種寫法都常見。
+
+**GitHub**（前六項在本地 clone 內，依序找）：
+
+1. `.github/pull_request_template.md`
+2. `pull_request_template.md`（repo 根）
+3. `docs/pull_request_template.md`
+4. `.github/PULL_REQUEST_TEMPLATE/` 目錄
+5. `PULL_REQUEST_TEMPLATE/` 目錄（repo 根）
+6. `docs/PULL_REQUEST_TEMPLATE/` 目錄
+7. 前六項全空 → 查一次組織預設：`gh api repos/<org>/.github/contents/.github/pull_request_template.md`（也試 root 與 `docs/`；404 就是沒有，不重試）
+
+目錄型（4–6）GitHub 不會自動套用、需人指定：恰好一份時直接用並在回報註明來源，多份時問人選哪份。
+
+**GitLab**（依 GitLab 文件的優先順序，設定層高於檔案層）：
+
+1. 專案設定的預設範本：`glab api projects/:id` 的 `merge_requests_template` 欄位非空 → 用它（Premium／Ultimate 才有此設定，其他方案此欄恆空，一次呼叫即可跳過）
+2. `.gitlab/merge_request_templates/Default.md`（檔名大小寫不敏感）
+3. `.gitlab/merge_request_templates/` 目錄下其他 `.md`（多份時問人）
+
+**都沒有** → 用本 skill 的 [`templates/mr.md`](templates/mr.md)（ADE 預設），並在回報中註明「未找到專案範本，使用 ADE 預設」。
+
+範本一律由本 skill 自己讀檔填寫後以 `--body-file` 送出；`gh pr create --template` 只提供空白起始文字、不做自動探索，非互動流程用不到。查找鏈依據見 [research-skill-boundaries.md](https://github.com/franKobayasi/agentic-dev-env/blob/main/docs/research/ade-dev/research-skill-boundaries.md) §3。
+
+## 3. 填寫與發出
+
+- 依分支實際 diff 填範本；範本欄位答不出來就問人，**不留 placeholder 發出**
+- 來自 `.ade-dev/` 任務的交付：描述須涵蓋交付定義、AC 驗證證據（測試輸出摘要）、與規格的已知差異
+- 發出前 commits 應符合 `ade-commit` 解析出的慣例
+- target 為 repo 預設分支（ADE 服務描述檔有指定 branch 時以它為準）
+- `gh pr create` / `glab mr create` 發出，回報 MR URL；**不自動 merge**——merge 是人的結果把關

package/template/skills/ade-ship/templates/mr.md

@@ -0,0 +1,17 @@
+<!-- ADE 預設 MR 範本：專案沒有自己的 PR/MR template 時使用 -->
+
+## 目的
+
+<為什麼有這個 MR：需求或問題，一兩句。有 PRD／spec／`.ade-dev/` 任務就附連結或路徑>
+
+## 變更內容
+
+- <重點變更，一條一件事>
+
+## 驗證
+
+<怎麼證明它是好的：測試指令與結果摘要，或手動驗證步驟>
+
+## 影響與風險
+
+<部署注意事項、相容性、feature flag 狀態；無則寫「無」>

package/template/skills/ade-update/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: ade-update
+description: 把工作目錄的 ADE managed 內容（.claude/ade/knowledge/、.claude/skills/ade-*、CLAUDE.md managed 區段）更新到中央 ADE repo 最新版。使用者說「更新 ADE」「拉最新知識」「ade update」「知識庫過期了」，或 session 開始時偵測到版本落後時使用。
+---
+
+# 更新 ADE
+
+只在**消費端工作目錄**（有 `.ade.json` 的 hub 根）執行；在 ADE repo 內沒有 managed 副本可更新，用一般 `git pull`。
+
+## 流程
+
+1. 讀 hub 根的 `.ade.json` 取得 `source`（為 null 則請使用者補上）
+2. **比對版本**：`git ls-remote <source> HEAD`，hash 與 `.ade.json` 的 `commit` 相同 → 已是最新，回報後結束，不必跑 update
+3. **先檢查有沒有未回流的修改**：`.claude/ade/` 與 `.claude/skills/ade-*/` 是 managed 區域，update 會整個覆蓋。有人手改過就先走 `ade-contribute` 把修改送回 ADE repo，否則會被蓋掉
+4. 在 hub 根執行（`<source>` 的 `git@host:org/repo.git` 要改寫成 `git+ssh://git@host/org/repo.git`——冒號換斜線）：
+   ```bash
+   pnpm dlx "git+ssh://git@github.com/ORG/REPO.git" update
+   ```
+5. 回報更新結果：`.ade.json` 的 `commit` 前後變化，以及這段期間 ADE repo 的 commit 摘要（`git log --oneline <舊 commit>..<新 commit>`，用 `git ls-remote`／既有 clone 取得皆可）——特別點出新增或改名的 skill，使用者才知道多了什麼能用

package/template/dot-claude/skills/ade-create-prd/SKILL.md

@@ -1,24 +0,0 @@
----
-name: ade-create-prd
-description: 協助 PO 依統一範本建立標準化 PRD，並拷問規格盲點。使用者說「建 PRD」「寫需求文件」「新的開發需求」「create PRD」時使用。僅在 ADE repo 內使用。
----
-
-# 建立 PRD
-
-## 流程
-
-1. 複製 `knowledge/prd/_template.md` 為 `knowledge/prd/YYYY-MM-DD-<slug>.md`，狀態設「草稿」
-2. 與 PO 對話逐區塊填寫，**先讀 `knowledge/services/index.md`、`knowledge/specs/` 相關文件，以及 `knowledge/prd/` 下狀態非「已實作」的 PRD**——用既有詞彙、對照現有規格找出衝突；與進行中 PRD 重疊時當場提醒 PO 決定合併或劃清界線
-3. 填完後進行盲點拷問（見下），問到 PO 每題都有明確答案或明確說「不在範圍」
-4. 拷問結果回填文件（範圍外的寫進「非目標」，未定的寫進「開放問題」）
-5. PO 確認後把狀態改為「已確認」
-6. Commit（或依團隊慣例開 PR），提醒下一步：跑 `ade-prd-to-spec` 更新規格
-
-## 盲點拷問清單
-
-- **邊界與錯誤**：輸入不合法、資源不存在、操作中斷、併發衝突時各是什麼行為？
-- **跨服務影響**：對照 services 總覽，有沒有漏列受影響的服務？服務間的呼叫順序與失敗處理？
-- **權限與安全**：誰能用這功能？資料存取邊界？
-- **相容性**：既有資料要遷移嗎？舊版本客戶端／既有 API 使用者會壞嗎？
-- **驗收條件**：每一條都可測試嗎？「好用」「快」這類形容詞要換成可驗證的敘述
-- **非目標**：最容易被誤以為包含在內的相鄰功能是什麼？明確排除