create-agentic-dev-env 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# create-agentic-dev-env
+
+為團隊打造 **Agentic Dev Environment（ADE）**：一個集中管理 domain 知識、流程知識、產品規格的知識庫 repo，讓 AI agent 在任何工作目錄都能取用團隊 knowhow、自主拉取服務進行開發，並把新知識持續回流——團隊的知識從「散落在成員腦中」變成「持久化、可迭代的資產」。
+
+## 運作模式
+
+```
+┌──────────────────┐   pnpm dlx … init/update    ┌──────────────────────┐
+│  ADE repo (xxx)   │ ──────────────────────────▶ │  工作目錄 (hub)       │
+│  你團隊的知識庫    │                              │  CLAUDE.md + skills  │
+│  knowledge/       │ ◀────────────────────────── │  workspaces/服務A     │
+│  skills/          │      contribute PR 回流      │  workspaces/服務B     │
+└──────────────────┘                              └──────────────────────┘
+```
+
+- **ADE repo**：每間公司／專案一個 private git repo，集中存放服務 registry、流程知識、規格與 PRD
+- **工作目錄**：任意目錄跑 `init` 即成為 agent 工作站；agent 讀服務總覽 → clone 服務到 `workspaces/` → 開發
+- **回流**：agent 發現知識過期或缺漏時，由內建 skill 引導開 PR 回 ADE repo，人只負責 review
+
+## 快速開始
+
+```sh
+# 1. 建立你的 ADE repo
+pnpm dlx create-agentic-dev-env my-ade
+
+# 2. 填 my-ade/package.json 的 repository.url，開始填 knowledge/，push 到 GitHub/GitLab
+
+# 3. 團隊成員在任一工作目錄安裝（SSH 設定見生成的 README）
+pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" init
+
+# 4. 之後拉取最新知識
+pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" update
+```
+
+`init` 之後的工作目錄：
+
+```
+work-dir/
+├── CLAUDE.md             # 原有內容不動，插入 <!-- ADE:BEGIN/END --> managed 區段
+├── .claude/
+│   ├── skills/ade-*/     # managed，update 整目錄覆蓋
+│   └── ade/knowledge/    # 知識庫副本
+├── .ade.json             # 來源 git url + commit（保鮮檢查用）
+└── workspaces/           # agent clone 服務 repo 的作業區（自動 gitignore）
+```
+
+## ADE repo 內容
+
+```
+knowledge/
+├── README.md    # 知識分層規則（canonical）
+├── services/    # 服務 registry：index.md 總覽導航 + 一服務一份 YAML
+├── process/     # 跨服務的團隊流程知識
+├── specs/       # 當前功能規格，持續迭代的真相來源
+└── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
+skills/          # init 時注入工作目錄（contribute / add-service / align-spec / spec-audit）
+.claude/skills/  # 在 ADE repo 內工作用（create-prd / prd-to-spec / feedback-upstream）
+claude-md/       # CLAUDE.md managed 區段的內容
+```
+
+### 設計重點
+
+- **服務 registry 兩層結構**：`index.md` 是全服務概覽（模擬工程師「先總覽定位、再查細節」的認知路徑），每個服務一份 YAML 記錄 repo 位址、技術棧、依賴關係——agent 據此自主 clone 與開發
+- **知識分層**：ADE 只收「跨服務知識、取得服務的最小資訊、產品規格」三類；bootstrap 流程與服務內部慣例歸服務 repo 自己的文件，不複製會過期的副本
+- **PRD → Spec 生命週期**：PO 用 skill 建標準化 PRD（含盲點拷問）→ 轉入 spec 並標 `🚧 尚未實作` → RD 開發完成後由 skill 核對實作、移除標記、開 PR 收尾
+- **Managed 區塊覆蓋**：工作目錄裡的 ADE 內容視同唯讀，`update` 無條件覆蓋——想改就回 ADE repo 開 PR，強迫知識回流中央
+- **機制回饋上游**：各 ADE repo 演化出的 skill／模板改良，由 `ade-feedback-upstream` skill 開 PR 回本專案（只回饋機制，公司知識絕不外流）
+
+## 開發
+
+```sh
+node test.js   # 端到端自測：create → init → update
+```
+
+零依賴、純 Node（>= 20）。架構與維護紀律見 [AGENTS.md](./AGENTS.md)。
+
+## License
+
+[MIT](./LICENSE)

package/bin/create.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+const { execSync } = require('child_process')
+
+const name = process.argv[2]
+if (!name || !/^[a-z0-9][a-z0-9._-]*$/i.test(name)) {
+  console.error('用法: create-agentic-dev-env <repo-name>')
+  process.exit(1)
+}
+const dest = path.resolve(name)
+if (fs.existsSync(dest)) {
+  console.error(`${name} 已存在`)
+  process.exit(1)
+}
+
+fs.cpSync(path.join(__dirname, '..', 'template'), dest, { recursive: true })
+// npm publish 會剝掉 dot 開頭的檔案/目錄，template 內以無點名稱存放，複製後改名
+fs.renameSync(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'))
+fs.renameSync(path.join(dest, 'dot-claude'), path.join(dest, '.claude'))
+for (const rel of fs.readdirSync(dest, { recursive: true })) {
+  const p = path.join(dest, rel)
+  if (!fs.statSync(p).isFile()) continue
+  const s = fs.readFileSync(p, 'utf8')
+  if (s.includes('__ADE_NAME__')) fs.writeFileSync(p, s.replaceAll('__ADE_NAME__', name))
+}
+// 記錄上游位址，供 ade-feedback-upstream skill 回饋機制改良
+let selfRepo = (require('../package.json').repository || {}).url || null
+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
+fs.writeFileSync(destPkgPath, JSON.stringify(destPkg, null, 2) + '\n')
+
+execSync('git init', { cwd: dest, stdio: 'inherit' })
+
+console.log(`
+已建立 ADE repo: ${name}/
+
+下一步:
+  1. 填 ${name}/package.json 的 repository.url
+  2. 開始填 knowledge/（服務格式見 knowledge/services/_template.md）
+  3. push 後團隊即可: pnpm dlx github:ORG/${name} init
+`)

package/lib/runner.js

@@ -0,0 +1,117 @@
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { execSync } = require('child_process')
+
+const BEGIN = '<!-- ADE:BEGIN -->'
+const END = '<!-- ADE:END -->'
+
+function run(cmd, pkgDir) {
+  try {
+    if (cmd === 'init') init(process.cwd(), pkgDir)
+    else if (cmd === 'update') update(process.cwd())
+    else {
+      console.error('用法: init | update')
+      process.exit(1)
+    }
+  } catch (e) {
+    console.error(e.message)
+    process.exit(1)
+  }
+}
+
+function init(cwd, srcDir) {
+  if (fs.existsSync(path.join(cwd, '.ade.json'))) {
+    throw new Error('此目錄已 init 過，請改用 update')
+  }
+  install(cwd, srcDir)
+  console.log('ADE init 完成')
+}
+
+function update(cwd) {
+  const cfgPath = path.join(cwd, '.ade.json')
+  if (!fs.existsSync(cfgPath)) throw new Error('此目錄尚未 init')
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'))
+  if (!cfg.source) throw new Error('.ade.json 缺少 source（ADE repo 的 git url），請補上後重試')
+
+  // 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' })
+    removeManaged(cwd)
+    install(cwd, path.join(tmp, 'repo'))
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+  console.log('ADE update 完成')
+}
+
+function removeManaged(cwd) {
+  fs.rmSync(path.join(cwd, '.claude', 'ade'), { recursive: true, force: true })
+  const skillsDir = path.join(cwd, '.claude', 'skills')
+  if (fs.existsSync(skillsDir)) {
+    for (const d of fs.readdirSync(skillsDir)) {
+      if (d.startsWith('ade-')) fs.rmSync(path.join(skillsDir, d), { recursive: true, force: true })
+    }
+  }
+}
+
+function install(cwd, srcDir) {
+  fs.cpSync(path.join(srcDir, 'knowledge'), path.join(cwd, '.claude', 'ade', 'knowledge'), { recursive: true })
+
+  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 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')
+  let md = fs.existsSync(claudePath) ? fs.readFileSync(claudePath, 'utf8') : ''
+  const b = md.indexOf(BEGIN)
+  const e = md.indexOf(END)
+  if (b !== -1 || e !== -1) {
+    if (b === -1 || e === -1 || e < b) {
+      throw new Error('CLAUDE.md 的 ADE 標記已損壞（BEGIN/END 不成對或順序顛倒），請手動修復後重試')
+    }
+    md = md.slice(0, b) + block + md.slice(e + END.length)
+  } else {
+    md = md ? md.trimEnd() + '\n\n' + block + '\n' : block + '\n'
+  }
+  fs.writeFileSync(claudePath, md)
+
+  fs.mkdirSync(path.join(cwd, 'workspaces'), { recursive: true })
+  const giPath = path.join(cwd, '.gitignore')
+  const gi = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : ''
+  if (!gi.split('\n').some((l) => l.trim().replace(/\/$/, '') === 'workspaces')) {
+    fs.writeFileSync(giPath, (gi ? gi.trimEnd() + '\n' : '') + 'workspaces/\n')
+  }
+
+  const prevPath = path.join(cwd, '.ade.json')
+  const prev = fs.existsSync(prevPath) ? JSON.parse(fs.readFileSync(prevPath, 'utf8')) : {}
+  let source = null
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(srcDir, 'package.json'), 'utf8'))
+    source = typeof pkg.repository === 'string' ? pkg.repository : (pkg.repository || {}).url || null
+    if (source) source = source.replace(/^git\+/, '')
+    if (source && source.includes('FILL_ME')) source = null
+  } catch {}
+  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 || null, commit }, null, 2) + '\n'
+  )
+  if (!source && !prev.source) {
+    console.warn('警告: ADE repo 的 package.json 未設定 repository.url，update 將無法運作，請手動補 .ade.json 的 source')
+  }
+}
+
+module.exports = { run, init, update }

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-agentic-dev-env",
+  "version": "0.1.0",
+  "description": "Scaffold and manage team Agentic Dev Environment (ADE) knowledge repos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/franKobayasi/agentic-dev-env.git"
+  },
+  "keywords": [
+    "agent",
+    "claude-code",
+    "knowledge-base",
+    "scaffold",
+    "ade"
+  ],
+  "author": "Frank Lin",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "create-agentic-dev-env": "bin/create.js"
+  },
+  "exports": {
+    "./runner": "./lib/runner.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "template"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "license": "MIT"
+}

package/template/CLAUDE.md

@@ -0,0 +1,15 @@
+# __ADE_NAME__（ADE 知識庫）
+
+這是團隊的 Agentic Dev Environment 知識庫 repo。結構與維護原則見 README.md。
+
+## PRD / Spec 生命週期
+
+- `knowledge/prd/`：一次開發一檔的需求文件，歷史文件不迭代（草稿 → 已確認 → 已實作）
+- `knowledge/specs/`：當前功能的真相來源，持續迭代；`🚧 尚未實作` 標記代表已定案未開發
+
+流程：PO 用 `ade-create-prd` 建 PRD → 確認後用 `ade-prd-to-spec` 更新 spec（標 🚧）→ RD 於工作目錄開發 → 開發完成 RD 跑 `ade-align-spec`（注入工作目錄的 skill）開 PR 回本 repo 收尾。
+
+## 編輯慣例
+
+- 服務描述檔必須符合 `knowledge/services/_template.yaml` 欄位結構，並同步更新 `services/index.md` 總覽；收錄範圍遵守 `knowledge/README.md` 的分層規則
+- 修改 spec 時沿用既有詞彙；PRD 只在「已實作」前可改

package/template/README.md

@@ -0,0 +1,72 @@
+# __ADE_NAME__
+
+由 [create-agentic-dev-env](https://github.com/franKobayasi/agentic-dev-env) 產生的 Agentic Dev Environment（ADE）知識庫：集中管理團隊的 domain 知識、流程知識與產品規格，讓 agent 在任何工作目錄都能取用並持續回流更新。
+
+## 初始設定（建 repo 後做一次）
+
+1. 填 `package.json` 的 `repository.url`（init 會記錄它作為 update 的來源）
+2. Push 到 GitHub / GitLab
+3. 開始填 `knowledge/`：服務用 `knowledge/services/_template.yaml` 格式，一服務一檔，並更新 `services/index.md` 總覽
+
+## 使用（團隊成員）
+
+### 首次使用前：設定 SSH
+
+init/update 透過 SSH 存取本 repo。先驗證：
+
+```sh
+ssh -T git@github.com   # GitLab 則為 git@gitlab.com；出現歡迎訊息即可跳過以下步驟
+```
+
+尚未設定金鑰：
+
+```sh
+ssh-keygen -t ed25519 -C "you@company.com"   # 一路 Enter 即可
+cat ~/.ssh/id_ed25519.pub                     # 複製輸出，貼到 GitHub/GitLab 帳號設定的 SSH Keys
+ssh -T git@github.com                         # 再次驗證
+```
+
+### 安裝
+
+在任一工作目錄執行：
+
+```sh
+pnpm dlx "git+ssh://git@github.com/ORG/__ADE_NAME__.git" init
+```
+
+（public repo 也可用短寫法 `pnpm dlx github:ORG/__ADE_NAME__ init`；private repo 走 `github:` 會因 tarball API 無認證而失敗，請一律用上方 git+ssh 形式）
+
+init 會在當前目錄建立：
+
+- `CLAUDE.md` 的 `<!-- ADE:BEGIN/END -->` managed 區段（原有內容不動）
+- `.claude/ade/knowledge/` 知識庫副本、`.claude/skills/ade-*/` skills
+- `workspaces/`（agent clone 服務 repo 的作業區，自動加入 .gitignore）
+- `.ade.json`（記錄來源與版本）
+
+之後同指令改跑 `update` 拉取最新知識（update 會直接 clone 最新版，不受 dlx 快取影響）。
+
+## 結構
+
+```
+knowledge/
+├── services/    # 服務 registry：index.md 總覽導航 + 一服務一檔
+├── process/     # 團隊流程知識
+├── specs/       # 當前功能規格，持續迭代的真相來源
+└── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
+skills/          # init 時注入工作目錄的 .claude/skills/
+.claude/skills/  # 在本 repo 內工作用的 skills（PO 建 PRD、轉 spec）
+claude-md/       # CLAUDE.md managed 區段的內容
+```
+
+## PRD / Spec 流程
+
+1. PO 在本 repo 用 `ade-create-prd` 建立標準化 PRD（含盲點拷問），定案後標「已確認」
+2. PO 用 `ade-prd-to-spec` 把 PRD 融入 `specs/`，新行為標 `🚧 尚未實作`，逐項確認對齊
+3. RD 在工作目錄開發（`workspaces/`）
+4. 開發完成 RD 跑 `ade-align-spec`：核對實作、移除 🚧、PRD 標「已實作」，開 PR 回本 repo
+
+## 維護原則
+
+- 工作目錄裡的 ADE 內容是唯讀副本，update 會覆蓋。所有修改都回到本 repo 走 PR——agent 端由 `ade-contribute` / `ade-add-service` skills 引導完成
+- 知識分層：本 repo 只收跨服務知識、取得服務的最小資訊、產品規格三類——完整規則見 `knowledge/README.md`（canonical）
+- 使用中演化出的**機制**改良（skill 寫法、模板、流程），用 `ade-feedback-upstream` skill 回饋給 create-agentic-dev-env 上游；公司知識內容絕不外流

package/template/claude-md/section.md

@@ -0,0 +1,26 @@
+<!-- 此區段由 ADE (__ADE_NAME__) 管理，update 時整段覆蓋。勿直接編輯；要修改請至 ADE repo 改，或使用 ade-contribute skill。 -->
+## ADE 工作區指引
+
+本目錄是 agent 工作站，知識庫位於 `.claude/ade/knowledge/`。
+
+### Session 開始時
+
+- **檢查知識新鮮度**：讀 `.ade.json`，執行 `git ls-remote <source> HEAD`，若 hash 與 `commit` 不符，提醒使用者執行 update 後再繼續（勿自行修改 managed 內容）
+- Session 一律從本目錄（hub 根）開啟；在 `workspaces/<service>/` 內開啟會失去 ade skills
+
+### 知識分層
+
+完整規則見 `.claude/ade/knowledge/README.md`。摘要：ADE 只收跨服務知識、取得服務的最小資訊、產品規格；服務內部一切以服務 repo（CLAUDE.md／AGENTS.md／code）為準。發現 ADE 側資訊過期：以服務 repo 為準繼續工作，任務收尾時用 `ade-contribute` 開 PR 修正，無需先徵詢。
+
+### 開發某個服務時
+
+1. 讀 `.claude/ade/knowledge/services/index.md`（全服務總覽）定位目標服務
+2. 讀 `.claude/ade/knowledge/services/<service>.yaml` 取得定位、repo、技術棧、依賴關係
+3. 若 `workspaces/<service>/` 不存在，依 `repo.url` / `repo.branch` clone 到 `workspaces/<service>/`
+4. 讀服務 repo 自身的 README／CLAUDE.md／AGENTS.md 完成安裝、啟動、測試；跨服務流程慣例見 `knowledge/process/`，功能規格見 `knowledge/specs/`
+
+### 知識維護
+
+- 發現知識過期、缺漏，或學到新慣例 → 用 `ade-contribute` skill 開 PR 回 ADE repo
+- 要註冊新服務 → 用 `ade-add-service` skill
+- `.claude/ade/` 與 `.claude/skills/ade-*/` 為 managed 區域，勿直接修改

package/template/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('create-agentic-dev-env/runner').run(process.argv[2], __dirname)

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

@@ -0,0 +1,23 @@
+---
+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/` 相關文件**，用既有詞彙、對照現有規格找出衝突
+3. 填完後進行盲點拷問（見下），問到 PO 每題都有明確答案或明確說「不在範圍」
+4. 拷問結果回填文件（範圍外的寫進「非目標」，未定的寫進「開放問題」）
+5. PO 確認後把狀態改為「已確認」，提醒下一步：跑 `ade-prd-to-spec` 更新規格
+
+## 盲點拷問清單
+
+- **邊界與錯誤**：輸入不合法、資源不存在、操作中斷、併發衝突時各是什麼行為？
+- **跨服務影響**：對照 services 總覽，有沒有漏列受影響的服務？服務間的呼叫順序與失敗處理？
+- **權限與安全**：誰能用這功能？資料存取邊界？
+- **相容性**：既有資料要遷移嗎？舊版本客戶端／既有 API 使用者會壞嗎？
+- **驗收條件**：每一條都可測試嗎？「好用」「快」這類形容詞要換成可驗證的敘述
+- **非目標**：最容易被誤以為包含在內的相鄰功能是什麼？明確排除

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

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

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

@@ -0,0 +1,23 @@
+---
+name: ade-prd-to-spec
+description: 將已確認的 PRD 融入 specs，標記尚未實作區塊，供 PO 確認 PRD 與 spec 對齊。使用者說「PRD 轉 spec」「更新規格」「把 PRD 落到 spec」時使用。僅在 ADE repo 內使用。
+---
+
+# PRD → Spec
+
+前提：PRD 狀態必須是「已確認」，否則請 PO 先走完 `ade-create-prd`。
+
+## 流程
+
+1. 讀目標 PRD 與 `knowledge/specs/` 現況，找出受影響的 spec 檔（沒有對應檔就依 `specs/README.md` 慣例新建）
+2. 將 PRD 需求融入 spec：描述「功能完成後應有的樣子」，並在每個新增／變更的行為區塊上方加標記行，**格式逐字照抄、只替換檔名**（align-spec 靠精確匹配移除，變體會漏抓）：
+   ```
+   > 🚧 尚未實作（PRD: ../prd/YYYY-MM-DD-slug.md）
+   ```
+   同一區塊已有其他 PRD 的標記時，堆疊一行新標記，勿合併、勿改動他人標記行
+3. 只動這次 PRD 涉及的內容，spec 其餘部分一字不改
+4. 回填 PRD 的「Spec 異動摘要」：動了哪些檔、各自異動重點
+5. 帶 PO 逐項確認 spec 與預期相符，不符就修到對齊為止
+6. PO 確認後 commit（或依團隊慣例開 PR）
+
+完成後提醒：RD 開發完成後在工作目錄跑 `ade-align-spec` 收尾。

package/template/gitignore

@@ -0,0 +1 @@
+node_modules/

package/template/knowledge/README.md

@@ -0,0 +1,27 @@
+# 知識分層規則（canonical）
+
+本檔是 ADE 知識分層的唯一權威定義；其他文件提到分層時一律指回這裡。
+
+ADE 只收錄三類知識：
+
+## 1. 跨服務知識
+
+單一服務無法自述、只有跨服務視角才成立的：服務定位、服務間依賴與呼叫關係（`services/`）、跨服務流程與團隊級慣例（`process/`）。
+
+## 2. 取得服務的最小資訊
+
+agent 進入服務 repo 之前必需的：repo URL、預設分支、技術棧概要（`services/<name>.yaml`）。技術棧屬低頻變動、可接受的少量重複。
+
+**Bootstrap 流程（安裝、啟動、測試）不在此列**——歸服務 repo 自己的文件，clone 之後即可取得，ADE 不複製一份會過期的副本。
+
+## 3. 產品規格與需求
+
+`specs/` 與 `prd/` 收**全部**產品規格，包含單一服務就能完成的功能。「服務可自述」的判準只適用於工程知識，不適用於產品視角——spec 的讀者是 PO，PRD 流程在 ADE repo 進行。
+
+## 此外的一切
+
+服務內部的規範、慣例、架構細節，歸服務 repo 自己的 CLAUDE.md 或 AGENTS.md（有哪個讀哪個，都有就都讀）；都沒有就讀 code。服務內部慣例**不回流**到 ADE。
+
+## 過期修正規則
+
+ADE 側資訊（定位、repo 位址／分支、技術棧、依賴關係）與服務 repo 現實不符時：**以服務 repo 為準**繼續手頭工作，**任務收尾時**用 `ade-contribute` 開 PR 修正 ADE，無需先徵詢——PR 本身就是 review 閘門。

package/template/knowledge/prd/README.md

@@ -0,0 +1,7 @@
+# PRD
+
+一次開發需求一檔：`YYYY-MM-DD-<slug>.md`，依 [_template.md](./_template.md) 格式撰寫（用 `ade-create-prd` skill 建立）。
+
+PRD 是**歷史文件**：狀態走到「已實作」後即封存，不再迭代。當前功能的真相在 `../specs/`。
+
+生命週期：`草稿`（撰寫中）→ `已確認`（PO 定案，可跑 `ade-prd-to-spec`）→ `已實作`（開發完成，`ade-align-spec` 收尾時標記）。

package/template/knowledge/prd/_template.md

@@ -0,0 +1,33 @@
+# PRD: <標題>
+
+- 日期: YYYY-MM-DD
+- 提出者:
+- 狀態: 草稿 <!-- 草稿 → 已確認 → 已實作 -->
+
+## 背景與目標
+
+為什麼要做這個、要達成什麼。
+
+## 非目標
+
+明確不做的事，避免範圍蔓延。
+
+## 需求描述
+
+使用者故事／操作流程，具體到能開發的程度。
+
+## 影響服務
+
+對照 `../services/index.md`，列出涉及的服務與各自要改什麼。
+
+## 驗收條件
+
+- [ ] 每條都要可測試、可驗證
+
+## 開放問題
+
+尚未定案的點，定案後移入上方對應區塊。
+
+## Spec 異動摘要
+
+<!-- ade-prd-to-spec 執行後填：動了哪些 spec 檔、各自的異動重點 -->

package/template/knowledge/process/README.md

@@ -0,0 +1,5 @@
+# 流程知識
+
+團隊怎麼工作：開發流程、分支與 PR 慣例、測試策略、PRD 怎麼寫、release 怎麼跑。
+
+每個主題一個 md 檔，放在本目錄下。

package/template/knowledge/services/_template.yaml

@@ -0,0 +1,21 @@
+# 服務描述檔模板：複製為 <service-name>.yaml 填寫，並同步更新 index.md 總覽
+# 只記「取得服務的最小資訊」與跨服務關係；bootstrap 流程與內部慣例歸服務 repo 自己的文件
+# （分層規則見 ../README.md）
+name: <service-name>
+description: |
+  定位：這個服務在整個產品中的角色、為什麼存在（一～兩句）。
+repo:
+  url: git@github.com:ORG/<service-name>.git
+  branch: main
+stack:
+  language: <例：TypeScript / NestJS>
+  package_manager: <例：pnpm>
+  runtime: <例：Node 22>
+dependencies:
+  calls:
+    - service: <service-b>
+      reason: <為了什麼呼叫它>
+  called_by:
+    - <api-gateway>
+specs:
+  - ../specs/<相關規格檔>.md

package/template/knowledge/services/index.md

@@ -0,0 +1,10 @@
+# 服務總覽
+
+> 導航用文件。每個服務只放一～兩行定位與關係，細節見各服務描述檔（YAML）。
+> Agent：開發前先在此定位目標服務，再讀對應的 `<service>.yaml`。
+
+| 服務 | 定位 | 細節 |
+|---|---|---|
+| (範例) service-a | 訂單核心服務，處理下單、庫存扣減；被 api-gateway 呼叫 | [service-a.yaml](./service-a.yaml) |
+
+新增服務請使用 `ade-add-service` skill，或依 [_template.yaml](./_template.yaml) 手動建立並更新本表。

package/template/knowledge/specs/README.md

@@ -0,0 +1,19 @@
+# 產品規格（spec）
+
+描述**當前**功能服務的規格，是長期維護、持續迭代的真相來源。每個功能／產品領域一個 md 檔。
+
+跨服務的功能請寫明由哪些服務構成，並連回 `../services/` 下的對應服務檔。
+
+## 尚未實作標記
+
+由 PRD 帶入、還沒開發完成的行為，在區塊上方標記，**格式必須逐字一致**（工具與 skill 靠精確匹配移除）：
+
+```
+> 🚧 尚未實作（PRD: ../prd/YYYY-MM-DD-slug.md）
+```
+
+- 一行只標一個 PRD；同一區塊有多個進行中 PRD 時堆疊多行
+- 標記行緊貼其描述的區塊（標題或段落）上方
+- 開發完成後由 `ade-align-spec` skill 核對實作、依 PRD 檔名精準移除
+
+讀 spec 時：無標記＝已上線的現況，有標記＝已定案但還沒做。

package/template/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "__ADE_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "bin": {
+    "__ADE_NAME__": "./cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "FILL_ME: git@github.com:ORG/__ADE_NAME__.git"
+  },
+  "ade": {
+    "upstream": null
+  },
+  "dependencies": {
+    "create-agentic-dev-env": "^0.1.0"
+  }
+}

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

@@ -0,0 +1,13 @@
+---
+name: ade-add-service
+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`）
+   - 資訊不足時詢問使用者，不要留空、不要猜測
+4. 在 `knowledge/services/index.md` 的總覽表加入該服務（一～兩行：定位與關係）
+5. 依 `ade-contribute` 流程開 PR 回 ADE repo

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

@@ -0,0 +1,21 @@
+---
+name: ade-align-spec
+description: 功能開發完成後，核對 spec 與實作是否一致，移除尚未實作標記並將 PRD 標為已實作。使用者說「開發完了更新 spec」「對齊 spec」「align spec」「收尾文件」時使用。
+---
+
+# Spec 與實作對齊
+
+開發完成後的文件收尾：讓 spec 回到「描述現況」的狀態。
+
+## 流程
+
+1. 確認這次開發對應的 PRD 與受影響 spec（從使用者、branch 或 PR 上下文取得；不確定就問）
+2. 找出本次 PRD 的標記：先用 `grep -n "🚧" <spec>` 列出**全部**標記行（寬鬆匹配，連格式變體一起抓），再逐行看 PRD 檔名判斷歸屬——只處理含本次 PRD 檔名的行，其他 PRD 的標記與其描述的內容一律不碰
+3. 逐項核對：對照 `workspaces/` 下的實際實作，檢查每個屬於本次 PRD 的 `🚧` 區塊
+   - 已實作且行為一致 → 移除該標記行（整行刪除，內容保留）
+   - 實作與 spec 不符 → 以**實作為準**修改 spec 內容，並記下差異
+   - 沒做的項目 → 保留標記，記下
+4. 依 `ade-contribute` skill 的流程 clone ADE repo 並修改：
+   - 移除已實作區塊的 🚧 標記、套用與實作對齊的修改
+   - 全部驗收項完成時，把 PRD 狀態改為「已實作」
+5. 開 PR，描述中列出：移除了哪些標記、spec 與原規劃的差異（給 PO 判斷是否接受）、未完成保留的項目

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

@@ -0,0 +1,19 @@
+---
+name: ade-contribute
+description: 將工作過程中發現的知識缺口、過期文件、新慣例回流到中央 ADE 知識庫。發現 .claude/ade/knowledge/ 內容與現實不符、缺少資訊，或使用者說「把這個記回知識庫」「更新 ADE」「回流」時使用。
+---
+
+# ADE 知識回流
+
+本地 `.claude/ade/` 是 managed 區域，`update` 時會被整個覆蓋——**永遠不要直接修改本地副本**，把修正送回中央 ADE repo。
+
+## 流程
+
+1. 讀工作目錄的 `.ade.json` 取得 `source`（ADE repo 的 git url）
+2. Clone 到暫存目錄：`git clone <source> <tmpdir>/ade`
+3. 在 clone 中建立分支，修改 `knowledge/` 下對應文件
+   - 修改前先讀原文，沿用既有格式與詞彙
+   - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則
+4. Commit 並開 PR（GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）
+   - PR 描述寫清楚：發現什麼缺口、在哪個工作情境發現的
+5. 告知使用者 PR 連結；merge 後在工作目錄執行 update 即可取得新版

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

@@ -0,0 +1,17 @@
+---
+name: ade-spec-audit
+description: 巡檢 spec 與各服務實作的一致性，找出計畫外變更（hotfix、直接改 code）造成的規格漂移。使用者說「巡檢 spec」「檢查規格漂移」「spec audit」「規格還對嗎」時使用。
+---
+
+# Spec 巡檢
+
+spec 平時只靠 PRD 流程更新；hotfix 與計畫外變更會讓 spec 悄悄漂移。本 skill 補上這條偵測路徑。
+
+## 流程
+
+1. 列出 `.claude/ade/knowledge/specs/` 下的 spec；範圍大時請使用者指定優先巡檢的部分（建議：最近有 release 的服務相關）
+2. 對每份 spec 找出涉及的服務（文內連結與 `services/index.md`），缺的 repo 依服務檔 clone 進 `workspaces/`
+3. 逐項對照實作與 spec 敘述，記錄不一致：行為已變、功能已移除、實作有但 spec 未記載
+   - `🚧 尚未實作` 區塊屬「已定案未開發」，不算漂移，跳過
+4. 向使用者報告漂移清單，確認哪些該修 spec（也可能是實作錯了該修 code）
+5. 確認後依 `ade-contribute` skill 流程開 PR 修正 spec