create-agentic-dev-env 0.1.0 → 0.2.1

package/README.md

@@ -60,9 +60,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 收尾
+- **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（含盲點拷問）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾；另有 `ade-spec-audit` 定期巡檢，抓 hotfix 等計畫外變更造成的規格漂移
 - **Managed 區塊覆蓋**：工作目錄裡的 ADE 內容視同唯讀，`update` 無條件覆蓋——想改就回 ADE repo 開 PR，強迫知識回流中央
 - **機制回饋上游**：各 ADE repo 演化出的 skill／模板改良，由 `ade-feedback-upstream` skill 開 PR 回本專案（只回饋機制，公司知識絕不外流）
 

package/bin/create.js

@@ -39,6 +39,6 @@ console.log(`
 
 下一步:
   1. 填 ${name}/package.json 的 repository.url
-  2. 開始填 knowledge/（服務格式見 knowledge/services/_template.md）
-  3. push 後團隊即可: pnpm dlx github:ORG/${name} init
+  2. 開始填 knowledge/（服務格式見 knowledge/services/_template.yaml）
+  3. push 後團隊即可: pnpm dlx "git+ssh://git@github.com/ORG/${name}.git" init
 `)

package/lib/runner.js

@@ -58,15 +58,22 @@ function removeManaged(cwd) {
 }
 
 function install(cwd, srcDir) {
-  fs.cpSync(path.join(srcDir, 'knowledge'), path.join(cwd, '.claude', 'ade', 'knowledge'), { recursive: true })
-
+  // 先驗證再動手：update 只清理 ade- 前綴，非前綴 skill 裝了就清不掉
   const srcSkills = path.join(srcDir, 'skills')
-  if (fs.existsSync(srcSkills)) {
-    for (const d of fs.readdirSync(srcSkills)) {
-      fs.cpSync(path.join(srcSkills, d), path.join(cwd, '.claude', 'skills', d), { recursive: true })
+  const skillDirs = fs.existsSync(srcSkills)
+    ? fs.readdirSync(srcSkills).filter((d) => fs.statSync(path.join(srcSkills, d)).isDirectory())
+    : []
+  for (const d of skillDirs) {
+    if (!d.startsWith('ade-')) {
+      throw new Error(`skills/${d}: ADE repo 的 skill 目錄必須以 ade- 前綴命名（update 只管理此前綴）`)
     }
   }
 
+  fs.cpSync(path.join(srcDir, 'knowledge'), path.join(cwd, '.claude', 'ade', 'knowledge'), { recursive: true })
+  for (const d of skillDirs) {
+    fs.cpSync(path.join(srcSkills, d), path.join(cwd, '.claude', 'skills', d), { recursive: true })
+  }
+
   const section = fs.readFileSync(path.join(srcDir, 'claude-md', 'section.md'), 'utf8').trim()
   const block = `${BEGIN}\n${section}\n${END}`
   const claudePath = path.join(cwd, 'CLAUDE.md')

package/package.json

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

package/template/CLAUDE.md

@@ -4,12 +4,10 @@
 
 ## PRD / Spec 生命週期
 
-- `knowledge/prd/`：一次開發一檔的需求文件，歷史文件不迭代（草稿 → 已確認 → 已實作）
-- `knowledge/specs/`：當前功能的真相來源，持續迭代；`🚧 尚未實作` 標記代表已定案未開發
-
-流程：PO 用 `ade-create-prd` 建 PRD → 確認後用 `ade-prd-to-spec` 更新 spec（標 🚧）→ RD 於工作目錄開發 → 開發完成 RD 跑 `ade-align-spec`（注入工作目錄的 skill）開 PR 回本 repo 收尾。
+PO 用 `ade-create-prd` 建 PRD → 確認後用 `ade-prd-to-spec` 更新 spec（標 🚧）→ RD 於工作目錄開發 → 開發完成 RD 跑 `ade-align-spec`（注入工作目錄的 skill）開 PR 回本 repo 收尾。文件定位與狀態規則見 `knowledge/prd/README.md`、`knowledge/specs/README.md`。
 
 ## 編輯慣例
 
+- **任何文件或流程的設計都遵守 `knowledge/README.md` 的「底層原則：Context 管理」**——常駐最小化、細節按需載入、導航短細節深
 - 服務描述檔必須符合 `knowledge/services/_template.yaml` 欄位結構，並同步更新 `services/index.md` 總覽；收錄範圍遵守 `knowledge/README.md` 的分層規則
 - 修改 spec 時沿用既有詞彙；PRD 只在「已實作」前可改

package/template/README.md

@@ -53,11 +53,33 @@ knowledge/
 ├── process/     # 團隊流程知識
 ├── specs/       # 當前功能規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-skills/          # init 時注入工作目錄的 .claude/skills/
-.claude/skills/  # 在本 repo 內工作用的 skills（PO 建 PRD、轉 spec）
+skills/          # init 時注入工作目錄的 .claude/skills/（五支，見下方 Skills 一覽）
+.claude/skills/  # 在本 repo 內工作用的 skills（三支，見下方 Skills 一覽）
 claude-md/       # CLAUDE.md managed 區段的內容
 ```
 
+## 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-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-process`** — 為團隊建立或修改流程慣例的 meta-skill。使用者說「以後都這樣做」「定一個慣例」時觸發。它依三層機制選載體：無條件約束 → `claude-md/section.md` 加一行指標；有觸發時機的程序 → 新增一支 `ade-` 前綴 skill；細節 → `process/` 一主題一檔。並執行 context 紀律：常駐層只寫「何時做＋去哪看」（參考技巧）、常駐規則超過 10 行時新增前必須與使用者確認取捨。最後走 `ade-contribute` 流程開 PR。
+
+### 在本 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`。
+
 ## PRD / Spec 流程
 
 1. PO 在本 repo 用 `ade-create-prd` 建立標準化 PRD（含盲點拷問），定案後標「已確認」

package/template/claude-md/section.md

@@ -21,6 +21,4 @@
 
 ### 知識維護
 
-- 發現知識過期、缺漏，或學到新慣例 → 用 `ade-contribute` skill 開 PR 回 ADE repo
-- 要註冊新服務 → 用 `ade-add-service` skill
-- `.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域，勿直接修改
+`.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域、視同唯讀；回流、註冊服務、建立流程等維護動作由 ade-* skills 引導。

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

@@ -8,10 +8,11 @@ description: 協助 PO 依統一範本建立標準化 PRD，並拷問規格盲
 ## 流程
 
 1. 複製 `knowledge/prd/_template.md` 為 `knowledge/prd/YYYY-MM-DD-<slug>.md`，狀態設「草稿」
-2. 與 PO 對話逐區塊填寫，**先讀 `knowledge/services/index.md` 與 `knowledge/specs/` 相關文件**，用既有詞彙、對照現有規格找出衝突
+2. 與 PO 對話逐區塊填寫，**先讀 `knowledge/services/index.md`、`knowledge/specs/` 相關文件，以及 `knowledge/prd/` 下狀態非「已實作」的 PRD**——用既有詞彙、對照現有規格找出衝突；與進行中 PRD 重疊時當場提醒 PO 決定合併或劃清界線
 3. 填完後進行盲點拷問（見下），問到 PO 每題都有明確答案或明確說「不在範圍」
 4. 拷問結果回填文件（範圍外的寫進「非目標」，未定的寫進「開放問題」）
-5. PO 確認後把狀態改為「已確認」，提醒下一步：跑 `ade-prd-to-spec` 更新規格
+5. PO 確認後把狀態改為「已確認」
+6. Commit（或依團隊慣例開 PR），提醒下一步：跑 `ade-prd-to-spec` 更新規格
 
 ## 盲點拷問清單
 

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

@@ -1,20 +1,23 @@
 ---
 name: ade-feedback-upstream
-description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結構、流程設計）回饋給上游 create-agentic-dev-env 框架。使用者說「回饋上游」「這個改良應該進框架」「feedback upstream」時使用。
+description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結構、流程設計）以 issue 回饋給上游 create-agentic-dev-env 框架。使用者說「回饋上游」「這個改良應該進框架」「feedback upstream」時使用。
 ---
 
 # 回饋上游
 
-本 repo 由 create-agentic-dev-env 產生後即與上游脫鉤；在日常使用中演化出的好機制，透過 PR 回饋上游，讓所有 ADE repo 受益。
+本 repo 由 create-agentic-dev-env 產生後即與上游脫鉤；在日常使用中演化出的好機制，透過**開 issue** 回饋上游，由上游維護者決定是否採納實作，讓所有 ADE repo 受益。
 
 ## 界線（最重要）
 
 - 只回饋**機制**：skill 的寫法改良、模板結構、流程設計、runner 行為建議
-- **絕不回饋內容**：`knowledge/` 下的公司知識、服務資訊、規格、PRD 全屬機密，一個字都不能出現在上游 PR。送出前逐行檢查 diff，公司名稱、服務名稱、內部詞彙都要抽換成通用範例
+- **絕不回饋內容**：`knowledge/` 下的公司知識、服務資訊、規格、PRD 全屬機密，一個字都不能出現在上游 issue。送出前逐行檢查 issue 內文，公司名稱、服務名稱、內部詞彙都要抽換成通用範例
 
 ## 流程
 
 1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）
-2. Clone 上游、建立分支，找到對應檔案（機制多在 `template/` 下）
-3. 把改良以通用形式套上：去除公司語彙，範例改用佔位內容
-4. 開 PR，說明：這個改良解決什麼問題、在本 ADE repo 實際使用的效果如何
+2. **查重**：查上游的 open issues（`gh issue list -R <upstream>`），同一改良已有記錄 → 在該 issue 留言補充使用經驗，不重複開
+3. 開 issue（`gh issue create -R <upstream>`），內容包含：
+   - 這個改良解決什麼問題
+   - 在本 ADE repo 實際使用的效果
+   - 建議的通用作法（範例一律用佔位內容，不含公司語彙）
+4. 告知使用者 issue 連結

package/template/knowledge/README.md

@@ -2,6 +2,16 @@
 
 本檔是 ADE 知識分層的唯一權威定義；其他文件提到分層時一律指回這裡。
 
+## 底層原則：Context 管理
+
+**這是貫穿 ADE 一切文件與流程設計的核心邏輯**，任何新增或修改設計時都先過這一關：agent 的 context 是最稀缺的資源，每一份文件都要回答「這段內容值得在什麼時機、以什麼成本進入 context？」
+
+- **常駐內容最小化**：CLAUDE.md 區段只寫「何時做＋去哪看」，一條一行
+- **參考技巧**：細節分檔存放、按需載入；skill body 精簡，超過一頁的細節拆出去引用
+- **導航短、細節深**：總覽檔（index）給定位用的一兩行，細節留在單體檔案（services 的 index/yaml 雙層就是這個原則的體現）
+
+本檔以下的分層規則、process 的放置決策規則（`process/README.md`），都是這個原則在各自領域的應用。
+
 ADE 只收錄三類知識：
 
 ## 1. 跨服務知識
@@ -14,6 +24,8 @@ agent 進入服務 repo 之前必需的：repo URL、預設分支、技術棧概
 
 **Bootstrap 流程（安裝、啟動、測試）不在此列**——歸服務 repo 自己的文件，clone 之後即可取得，ADE 不複製一份會過期的副本。
 
+服務退役時：刪除其 yaml 並從 `index.md` 移除，git history 即封存——registry 只描述當前存活的服務，不設狀態欄，退役服務留著只會誤導 agent 去 clone 死掉的 repo。
+
 ## 3. 產品規格與需求
 
 `specs/` 與 `prd/` 收**全部**產品規格，包含單一服務就能完成的功能。「服務可自述」的判準只適用於工程知識，不適用於產品視角——spec 的讀者是 PO，PRD 流程在 ADE repo 進行。

package/template/knowledge/process/README.md

@@ -2,4 +2,21 @@
 
 團隊怎麼工作：開發流程、分支與 PR 慣例、測試策略、PRD 怎麼寫、release 怎麼跑。
 
-每個主題一個 md 檔，放在本目錄下。
+## 流程的落地層（放置決策規則）
+
+為環境建立流程時，依強制力需求選載體——強制力與 context 成本成正比：
+
+1. **無條件約束**（任何任務都適用）→ `claude-md/section.md` 加一行指標。section 是每個 session 的固定 context 成本：一條一行、總量克制
+2. **有觸發時機的程序** → `skills/` 一支 skill（目錄名必須 `ade-` 前綴），description 寫觸發語
+3. **細節**（清單、範例、規格）→ 本目錄一主題一檔，被上兩層引用、按需載入
+
+原則：**預設 context 最小化**——常駐層只寫「何時做＋去哪看」（參考技巧），細節留在本目錄等被載入。用 `ade-add-process` skill 引導整個落地流程。
+
+## 檔案慣例
+
+- 一個主題一個 md 檔，kebab-case 檔名（例：`git-commit.md`、`branching.md`、`release.md`）
+- 框架預載的預設檔會在檔頭標示；與團隊實況不符時直接修改，勿讓錯誤的預設值留在庫裡
+
+## 現有主題
+
+- [git-commit.md](./git-commit.md) — commit 訊息採 Conventional Commits

package/template/knowledge/process/git-commit.md

@@ -0,0 +1,24 @@
+# Git commit 慣例
+
+> 此為框架預載的預設值，請依團隊實況修改；與團隊既有慣例不符時，改這份文件而不是遷就它。
+
+採用 [Conventional Commits](https://www.conventionalcommits.org/)：
+
+```
+<type>(<scope>): <subject>
+
+[body（選填）]
+```
+
+## 規則
+
+- **type**（必填）：`feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`
+- **scope**（選填）：影響範圍，如模組或子系統名，例：`feat(auth): ...`
+- **subject**：英文、祈使句、小寫開頭、不加句號，例：`fix(order): prevent duplicate submission on retry`
+- **body**：說明「為什麼改」而非「改了什麼」（diff 已經說了改什麼）；破壞性變更以 `BREAKING CHANGE:` 開頭註明
+
+## Agent 執行時
+
+- 在 `workspaces/` 下任何服務 repo commit 都遵守本慣例
+- 一個 commit 一件事；混雜多個意圖時拆開
+- 服務 repo 自己的 CLAUDE.md／AGENTS.md 若另有 commit 規範，以服務 repo 為準（分層規則見 `../README.md`）

package/template/package.json

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

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

@@ -0,0 +1,31 @@
+---
+name: ade-add-process
+description: 為團隊建立或修改流程慣例並落地到 ADE 知識庫。使用者說「建立一個流程」「定一個慣例」「以後都這樣做」「每次都要」「把這個做法固定下來」時使用。
+---
+
+# 建立／修改流程
+
+把一個流程沉澱進 ADE，讓所有工作目錄的 agent 都 follow。核心是**選對載體**——強制力與 context 成本成正比（放置規則詳見 `knowledge/process/README.md`）。
+
+## 1. 分類：這個流程是哪一種？
+
+- **無條件約束**（任何任務都適用，如 commit 風格）→ `claude-md/section.md` 加**一行**指標
+- **有觸發時機的多步驟程序**（如 release、開發收尾）→ `skills/` 新增一支 skill
+- **被引用的細節**（清單、範例、規格）→ `knowledge/process/<主題>.md`
+
+多數流程是組合：常駐一行（或一支 skill）＋ process 細節檔。
+
+## 2. Context 紀律（每一步都遵守）
+
+- **參考技巧**：常駐層與 skill body 只寫「何時做＋去哪看」，細節放 process/ 檔按需載入——預設 context 越小越好
+- section.md 常駐規則一條一行；**常駐規則超過 10 行時，新增前必須與使用者確認取捨**（合併、降級為 skill 觸發、或刪一條舊的）
+- skill 的 description 寫觸發語、body 精簡；超過一頁的細節拆到 process/ 檔並連結
+
+## 3. 落地
+
+1. 依 `ade-contribute` skill 流程 clone ADE repo、建分支（含查重：同一流程已有 issue/PR 就別重開）
+2. 寫 `knowledge/process/<主題>.md`（細節層，kebab-case 檔名）
+3. 需要 skill 的：在 `skills/` 下建立，**目錄名必須 `ade-` 前綴**——runner 只管理此前綴，非前綴會被拒裝
+4. 需要常駐行的：在 `claude-md/section.md` 適當小節加一行指標
+5. 更新 `process/README.md` 的主題索引
+6. 依 `ade-contribute` 慣例開 PR；merge 後各工作目錄 update 即生效

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

@@ -5,9 +5,10 @@ description: 在 ADE 知識庫註冊新服務。使用者說「新增服務」
 
 # 新增服務
 
-1. 依 `ade-contribute` skill 的流程 clone ADE repo 並建立分支
-2. 複製 `knowledge/services/_template.yaml` 為 `knowledge/services/<service-name>.yaml`
-3. 逐欄位填寫。**`repo`（url、branch）為必填**——agent 之後要靠它自主 clone；bootstrap 流程不要寫進來，那歸服務 repo 自己的文件（分層規則見 `knowledge/README.md`）
+1. **先確認尚未註冊**：讀 `knowledge/services/index.md` 與 `services/` 目錄，該服務（或同 repo 的別名）已存在時，改走 `ade-contribute` 更新既有描述檔，不要另建
+2. 依 `ade-contribute` skill 的流程 clone ADE repo 並建立分支
+3. 複製 `knowledge/services/_template.yaml` 為 `knowledge/services/<service-name>.yaml`
+4. 逐欄位填寫。**`repo`（url、branch）為必填**——agent 之後要靠它自主 clone；bootstrap 流程不要寫進來，那歸服務 repo 自己的文件（分層規則見 `knowledge/README.md`）
    - 資訊不足時詢問使用者，不要留空、不要猜測
-4. 在 `knowledge/services/index.md` 的總覽表加入該服務（一～兩行：定位與關係）
-5. 依 `ade-contribute` 流程開 PR 回 ADE repo
+5. 在 `knowledge/services/index.md` 的總覽表加入該服務（一～兩行：定位與關係）
+6. 依 `ade-contribute` 流程開 PR 回 ADE repo

package/template/skills/ade-align-spec/SKILL.md

@@ -10,12 +10,11 @@ description: 功能開發完成後，核對 spec 與實作是否一致，移除
 ## 流程
 
 1. 確認這次開發對應的 PRD 與受影響 spec（從使用者、branch 或 PR 上下文取得；不確定就問）
-2. 找出本次 PRD 的標記：先用 `grep -n "🚧" <spec>` 列出**全部**標記行（寬鬆匹配，連格式變體一起抓），再逐行看 PRD 檔名判斷歸屬——只處理含本次 PRD 檔名的行，其他 PRD 的標記與其描述的內容一律不碰
-3. 逐項核對：對照 `workspaces/` 下的實際實作，檢查每個屬於本次 PRD 的 `🚧` 區塊
+2. 依 `ade-contribute` skill 的流程 clone ADE repo——**核對與修改都以這份 fresh clone 為唯一基準**。工作目錄的 `.claude/ade/` 副本可能過期（例如 PO merge 了 prd-to-spec 之後沒人跑過 update，本地根本沒有那些標記），只能當導航用
+3. 找出本次 PRD 的標記：在 clone 的 spec 上先用 `grep -n "🚧" <spec>` 列出**全部**標記行（寬鬆匹配，連格式變體一起抓），再逐行看 PRD 檔名判斷歸屬——只處理含本次 PRD 檔名的行，其他 PRD 的標記與其描述的內容一律不碰
+4. 逐項核對：對照 `workspaces/` 下的實際實作，檢查每個屬於本次 PRD 的 `🚧` 區塊
    - 已實作且行為一致 → 移除該標記行（整行刪除，內容保留）
    - 實作與 spec 不符 → 以**實作為準**修改 spec 內容，並記下差異
    - 沒做的項目 → 保留標記，記下
-4. 依 `ade-contribute` skill 的流程 clone ADE repo 並修改：
-   - 移除已實作區塊的 🚧 標記、套用與實作對齊的修改
-   - 全部驗收項完成時，把 PRD 狀態改為「已實作」
-5. 開 PR，描述中列出：移除了哪些標記、spec 與原規劃的差異（給 PO 判斷是否接受）、未完成保留的項目
+5. 在 clone 中套用修改；全部驗收項完成時，把 PRD 狀態改為「已實作」
+6. 依 `ade-contribute` 的慣例開 PR（含查重與 gh/glab 降級路徑），描述中列出：移除了哪些標記、spec 與原規劃的差異（給 PO 判斷是否接受）、未完成保留的項目

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

@@ -9,11 +9,12 @@ description: 將工作過程中發現的知識缺口、過期文件、新慣例
 
 ## 流程
 
-1. 讀工作目錄的 `.ade.json` 取得 `source`（ADE repo 的 git url）
-2. Clone 到暫存目錄：`git clone <source> <tmpdir>/ade`
-3. 在 clone 中建立分支，修改 `knowledge/` 下對應文件
+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/` 下對應文件
    - 修改前先讀原文，沿用既有格式與詞彙
-   - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則
-4. Commit 並開 PR（GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）
-   - PR 描述寫清楚：發現什麼缺口、在哪個工作情境發現的
-5. 告知使用者 PR 連結；merge 後在工作目錄執行 update 即可取得新版
+   - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）
+5. Commit、push 分支，開 PR 並連結 issue（描述加 `Closes #<issue 編號>`；GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）
+   - gh/glab 不可用或未登入時的降級路徑：push 分支後，把 compare／new-MR 網址給使用者，請人手動開
+6. 告知使用者 PR 連結；merge 後在工作目錄執行 update 即可取得新版

package/template/skills/ade-spec-audit/SKILL.md

@@ -9,9 +9,10 @@ spec 平時只靠 PRD 流程更新；hotfix 與計畫外變更會讓 spec 悄悄
 
 ## 流程
 
-1. 列出 `.claude/ade/knowledge/specs/` 下的 spec；範圍大時請使用者指定優先巡檢的部分（建議：最近有 release 的服務相關）
-2. 對每份 spec 找出涉及的服務（文內連結與 `services/index.md`），缺的 repo 依服務檔 clone 進 `workspaces/`
-3. 逐項對照實作與 spec 敘述，記錄不一致：行為已變、功能已移除、實作有但 spec 未記載
+1. **先確保副本最新**：執行 update（或確認 `.ade.json` 的 commit 與遠端 HEAD 一致）——拿過期的 spec 副本去比對會誤報漂移
+2. 列出 `.claude/ade/knowledge/specs/` 下的 spec；範圍大時請使用者指定優先巡檢的部分（建議：最近有 release 的服務相關）
+3. 對每份 spec 找出涉及的服務（文內連結與 `services/index.md`），缺的 repo 依服務檔 clone 進 `workspaces/`
+4. 逐項對照實作與 spec 敘述，記錄不一致：行為已變、功能已移除、實作有但 spec 未記載
    - `🚧 尚未實作` 區塊屬「已定案未開發」，不算漂移，跳過
-4. 向使用者報告漂移清單，確認哪些該修 spec（也可能是實作錯了該修 code）
-5. 確認後依 `ade-contribute` skill 流程開 PR 修正 spec
+5. 向使用者報告漂移清單，確認哪些該修 spec（也可能是實作錯了該修 code）
+6. 確認後依 `ade-contribute` skill 流程開 PR 修正 spec