create-agentic-dev-env 1.1.0 → 1.3.0

package/README.md

@@ -53,10 +53,11 @@ knowledge/
 ├── process/     # 跨服務的團隊流程知識
 ├── specs/       # 當前功能規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-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 內也可用
+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 區段的內容
 ```
 
@@ -66,7 +67,9 @@ claude-md/       # CLAUDE.md managed 區段的內容
 - **服務 registry 兩層結構**：`index.md` 是全服務概覽（模擬工程師「先總覽定位、再查細節」的認知路徑），每個服務一份 YAML 記錄 repo 位址、技術棧、依賴關係——agent 據此自主 clone 與開發
 - **知識分層**：ADE 只收「跨服務知識、取得服務的最小資訊、產品規格」三類；bootstrap 流程與服務內部慣例歸服務 repo 自己的文件，不複製會過期的副本
 - **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（模糊想法先跑 Discovery，再盲點拷問，`validate-prd.sh` 機械檢查）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾；另有 `ade-spec-audit` 定期巡檢，抓 hotfix 等計畫外變更造成的規格漂移
+- **不綁 forge**：ADE repo 可以只是本機或共用磁碟上的 git repo（`repository.url` 填路徑、`pnpm dlx file:<path>` 安裝）；回流改為 push 分支交人 merge，其餘不變
 - **Managed 區塊覆蓋**：工作目錄裡的 ADE 內容視同唯讀，`update` 無條件覆蓋——想改就回 ADE repo 開 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

@@ -46,7 +46,7 @@ console.log(`
 Created ADE repo: ${name}/
 
 Next steps:
-  1. Set repository.url in ${name}/package.json
+  1. Set repository.url in ${name}/package.json (git url; or an absolute path for a local-only ADE repo)
   2. Start filling knowledge/ (service format: knowledge/services/_template.yaml)
   3. After pushing, team members run: pnpm dlx "git+ssh://git@github.com/ORG/${name}.git" init
 `)

package/lib/runner.js

@@ -34,13 +34,15 @@ function update(cwd, ws) {
   const cfgPath = path.join(cwd, '.ade.json')
   if (!fs.existsSync(cfgPath)) throw new Error('Not initialized here; run init first')
   const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'))
-  if (!cfg.source) throw new Error('.ade.json is missing source (the ADE repo git url); add it and retry')
+  if (!cfg.source) throw new Error('.ade.json is missing source (the ADE repo git url or local path); add it and retry')
 
   // pnpm dlx 有快取（預設 ~24h），cli.js 所在的套件目錄可能是舊版內容；
   // update 的任務是拿最新知識，因此一律無視 pkgDir、自行 clone source
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ade-'))
   try {
-    execSync(`git clone --depth 1 "${cfg.source}" "${path.join(tmp, 'repo')}"`, { stdio: 'inherit' })
+    // 本地路徑的 clone 不支援 --depth（只會印警告），其餘來源維持淺 clone
+    const depth = fs.existsSync(cfg.source) ? '' : '--depth 1 '
+    execSync(`git clone ${depth}"${cfg.source}" "${path.join(tmp, 'repo')}"`, { stdio: 'inherit' })
     removeManaged(cwd)
     install(cwd, path.join(tmp, 'repo'), ws)
   } finally {
@@ -126,16 +128,16 @@ function install(cwd, srcDir, wsOverride) {
   if (!gi.split('\n').some((l) => l.trim() === 'workspaces')) {
     fs.writeFileSync(giPath, (gi ? gi.trimEnd() + '\n' : '') + 'workspaces\n')
   }
+  // srcDir 可能沒有 .git（pnpm dlx file:<本地路徑> 打包時不帶），退而問 source 本身
+  const src = source || prev.source
   let commit = null
-  try {
-    commit = execSync('git rev-parse HEAD', { cwd: srcDir, stdio: ['ignore', 'pipe', 'ignore'] })
-      .toString()
-      .trim()
-  } catch {}
-  fs.writeFileSync(
-    prevPath,
-    JSON.stringify({ source: source || prev.source, commit, workspaces: ws }, null, 2) + '\n'
-  )
+  for (const cmd of ['git rev-parse HEAD', `git ls-remote "${src}" HEAD`]) {
+    try {
+      commit = execSync(cmd, { cwd: srcDir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().split(/\s/)[0] || null
+      if (commit) break
+    } catch {}
+  }
+  fs.writeFileSync(prevPath, JSON.stringify({ source: src, commit, workspaces: ws }, null, 2) + '\n')
 }
 
 module.exports = { run, init, update }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-dev-env",
-  "version": "1.1.0",
+  "version": "1.3.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

@@ -4,7 +4,7 @@
 
 ## 初始設定（建 repo 後做一次）
 
-1. 填 `package.json` 的 `repository.url`（init 會記錄它作為 update 的來源）
+1. 填 `package.json` 的 `repository.url`（init 會記錄它作為 update 的來源）——放 GitHub／GitLab 填 git url；**只在本地**填絕對路徑（見下方「本地模式」）
 2. Push 到 GitHub / GitLab
 3. 開始填 `knowledge/`：服務用 `knowledge/services/_template.yaml` 格式，一服務一檔，並更新 `services/index.md` 總覽
 
@@ -45,6 +45,17 @@ init 會在當前目錄建立：
 
 之後同指令改跑 `update` 拉取最新知識（update 會直接 clone 最新版，不受 dlx 快取影響）。
 
+### 本地模式：ADE repo 不放 GitHub／GitLab
+
+ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用，SSH 步驟跳過：
+
+```sh
+# package.json 的 repository.url 填絕對路徑，例如 /Users/me/team-ade
+pnpm dlx "file:/Users/me/team-ade" init     # 之後 update 同形式；file: 必要，直接給目錄會找不到相依
+```
+
+差別只在回流：沒有 issue／PR，`ade-contribute` 會把分支 push 回這個 repo、回報分支名，由你在 ADE repo 內 `git merge` 後各工作目錄 update。其他 skill 與新鮮度檢查（`git ls-remote <路徑>`）照常。
+
 ### 裝好之後，先記這兩支 skill
 
 - **`/ade-help`** — 「有哪些 skill 可以用？」問它。它即時掃描當前位置真正載得到的 `ade-*` skills 並列出用途，不會像文件一樣過期
@@ -59,9 +70,10 @@ knowledge/
 ├── process/     # 跨服務流程與團隊級慣例
 ├── specs/       # 產品規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-skills/          # init 時注入工作目錄的 .claude/skills/（十三支，見下方 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
@@ -79,6 +91,8 @@ claude-md/       # CLAUDE.md managed 區段的內容
 | **`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 一件事。 | — |
@@ -96,8 +110,9 @@ claude-md/       # CLAUDE.md managed 區段的內容
 
 1. PO 用 `ade-create-prd` 建立標準化 PRD（含 Discovery 與盲點拷問），定案後標「已確認」
 2. PO 用 `ade-prd-to-spec` 把 PRD 融入 `specs/`，新行為標 `🚧 尚未實作`，逐項確認對齊
-3. RD 在工作目錄開發（`workspaces/`），`ade-commit`／`ade-ship` 交付
+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。
 

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

@@ -14,7 +14,7 @@ description: 將本 ADE repo 演化出的機制改良（skill 寫法、模板結
 
 ## 流程
 
-1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程在收尾沉澱時經 `ade-contribute` 開出）
+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-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ade-commit
-description: 在服務 repo 產生符合慣例的 git commit——專案自有規範優先，沒有就用 ADE 預設（Conventional Commits）。使用者說「commit」「提交」「幫我 commit」，或任何流程（如 ade-ship）需要 commit 時使用。
+description: 在服務 repo 產生符合慣例的 git commit——專案自有規範優先，沒有就用 ADE 預設（Conventional Commits）。使用者說「commit」「提交」「幫我 commit」，或任何流程（ade-dev、ade-ship）需要 commit 時使用。
 ---
 
 # ade-commit：commit 訊息慣例解析

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

@@ -1,6 +1,6 @@
 ---
 name: ade-contribute
-description: 從工作目錄修改中央 ADE 知識庫並開 PR——包含主動撰寫（新增或調整 spec、skill、process、服務描述檔）與被動回流（發現 .claude/ade/knowledge/ 內容過期或缺漏）。使用者說「改 ADE 的 spec／skill」「把這個記回知識庫」「更新 ADE」「回流」時使用。
+description: 從工作目錄修改中央 ADE 知識庫並開 PR（ADE repo 只在本地時 push 分支交人 merge）——包含主動撰寫（新增或調整 spec、skill、process、服務描述檔）與被動回流（發現 .claude/ade/knowledge/ 內容過期或缺漏）。使用者說「改 ADE 的 spec／skill」「把這個記回知識庫」「更新 ADE」「回流」時使用。
 ---
 
 # ADE 知識回流
@@ -9,16 +9,18 @@ description: 從工作目錄修改中央 ADE 知識庫並開 PR——包含主
 
 ## 流程
 
-1. 讀工作目錄的 `.ade.json` 取得 `source`（ADE repo 的 git url；為 null 則請使用者補上）
+1. 讀工作目錄的 `.ade.json` 取得 `source`（ADE repo 的 git url 或本地路徑；為 null 則請使用者補上）。`source` 是檔案系統路徑（`/`、`~`、`.` 開頭或 `file://`）即**本地模式**：ADE repo 不在 GitHub／GitLab，沒有 issue 與 PR，下列標〔本地〕的替代做法適用
 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 是查重與追蹤的協調點
+   - 〔本地〕查重改看 `git branch -r` 與 `git log origin/main --oneline -30` 有無同一缺口的分支或 commit；不開 issue，缺口描述（缺什麼／哪裡過期／在哪個情境發現）寫進 commit body
 4. 修改 `knowledge/` 下對應文件
    - 修改前先讀原文，沿用既有格式與詞彙
    - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）
    - 新增或修改 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 連結，並把工作副本切回主幹（`git switch main`）留給下次；merge 後在工作目錄執行 update 即可取得新版
+   - 〔本地〕push 分支即止、不開 PR（非 bare 的本地 repo 也接受 push 到非 checked-out 的分支）；回報分支名與 diff 摘要，**merge 由人在 ADE repo 內執行**（`git -C <source> merge <branch>`），人當場要求才替他跑
+6. 告知使用者 PR 連結（〔本地〕分支名），並把工作副本切回主幹（`git switch main`）留給下次；merge 後在工作目錄執行 update 即可取得新版

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-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ade-ship
-description: 從服務 repo 的分支發出 Merge Request / Pull Request——用 gh 或 glab CLI（不可用時退 API），MR 內容依專案自有範本，沒有就用 ADE 內建預設範本。使用者說「發 MR」「開 PR」「ship」「送出 merge request」時使用。
+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
@@ -33,11 +33,12 @@ description: 從服務 repo 的分支發出 Merge Request / Pull Request——
 
 **都沒有** → 用本 skill 的 [`templates/mr.md`](templates/mr.md)（ADE 預設），並在回報中註明「未找到專案範本，使用 ADE 預設」。
 
-範本一律由本 skill 自己讀檔填寫後以 `--body-file` 送出；`gh pr create --template` 只提供空白起始文字、不做自動探索，非互動流程用不到。
+範本一律由本 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

@@ -2,7 +2,7 @@
 
 ## 目的
 
-<為什麼有這個 MR：需求或問題，一兩句。有 PRD／spec 就附連結或路徑>
+<為什麼有這個 MR：需求或問題，一兩句。有 PRD／spec／`.ade-dev/` 任務就附連結或路徑>
 
 ## 變更內容
 

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

@@ -16,4 +16,5 @@ description: 把工作目錄的 ADE managed 內容（.claude/ade/knowledge/、.c
    ```bash
    pnpm dlx "git+ssh://git@github.com/ORG/REPO.git" update
    ```
+   `source` 是本地路徑（ADE repo 不在 GitHub／GitLab）時改用 `file:` 協定——`pnpm dlx "file:<source>" update`；直接給目錄會以 link 模式執行、找不到相依
 5. 回報更新結果：`.ade.json` 的 `commit` 前後變化，以及這段期間 ADE repo 的 commit 摘要（`git log --oneline <舊 commit>..<新 commit>`，用 `git ls-remote`／既有 clone 取得皆可）——特別點出新增或改名的 skill，使用者才知道多了什麼能用