create-agentic-dev-env 0.2.8 → 1.1.0

package/README.md

@@ -53,8 +53,10 @@ 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 / align-spec / spec-audit / commit / ship /
+                 #   add-skill / add-process）；其中七支 symlink 進 .claude/skills/ 在 ADE repo 內也可用
+.claude/skills/  # 只在 ADE repo 內工作用（feedback-upstream）
 claude-md/       # CLAUDE.md managed 區段的內容
 ```
 
@@ -63,9 +65,10 @@ 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-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 })) {
@@ -36,6 +36,8 @@ if (selfRepo && selfRepo.includes('FILL_ME')) selfRepo = null
 const destPkgPath = path.join(dest, 'package.json')
 const destPkg = JSON.parse(fs.readFileSync(destPkgPath, 'utf8'))
 destPkg.ade.upstream = selfRepo ? selfRepo.replace(/^git\+/, '') : null
+// 鎖精確版本：ADE repo 建立後即與上游迭代解耦，升級是 ADE repo 內顯式改版號的決定
+destPkg.dependencies['create-agentic-dev-env'] = require('../package.json').version
 fs.writeFileSync(destPkgPath, JSON.stringify(destPkg, null, 2) + '\n')
 
 execSync('git init', { cwd: dest, stdio: 'inherit' })

package/package.json

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

package/template/README.md

@@ -45,52 +45,64 @@ 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 區段的內容
 ```
 
-## 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-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 在工作目錄開發（`workspaces/`），`ade-commit`／`ade-ship` 交付
 4. 開發完成 RD 跑 `ade-align-spec`：核對實作、移除 🚧、PRD 標「已實作」，開 PR 回本 repo
 
+步驟 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` 開出）
 2. **查重**：查上游的 open issues（`gh issue list -R <upstream>`），同一改良已有記錄 → 在該 issue 留言補充使用經驗，不重複開
 3. 開 issue（`gh issue create -R <upstream>`），內容包含：
    - 這個改良解決什麼問題

package/template/package.json

@@ -13,6 +13,6 @@
     "upstream": null
   },
   "dependencies": {
-    "create-agentic-dev-env": "^0.2.0"
+    "create-agentic-dev-env": "0.0.0-stamped-by-create"
   }
 }

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-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-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,43 @@
+---
+name: ade-ship
+description: 從服務 repo 的分支發出 Merge Request / Pull Request——用 gh 或 glab CLI（不可用時退 API），MR 內容依專案自有範本，沒有就用 ADE 內建預設範本。使用者說「發 MR」「開 PR」「ship」「送出 merge request」時使用。
+---
+
+# 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` 只提供空白起始文字、不做自動探索，非互動流程用不到。
+
+## 3. 填寫與發出
+
+- 依分支實際 diff 填範本；範本欄位答不出來就問人，**不留 placeholder 發出**
+- 發出前 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 就附連結或路徑>
+
+## 變更內容
+
+- <重點變更，一條一件事>
+
+## 驗證
+
+<怎麼證明它是好的：測試指令與結果摘要，或手動驗證步驟>
+
+## 影響與風險
+
+<部署注意事項、相容性、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 使用者會壞嗎？
-- **驗收條件**：每一條都可測試嗎？「好用」「快」這類形容詞要換成可驗證的敘述
-- **非目標**：最容易被誤以為包含在內的相鄰功能是什麼？明確排除