create-agentic-dev-env 0.2.4 → 0.2.6

package/bin/create.js

@@ -20,8 +20,10 @@ 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'))
-// add-service 主要使用場景在 ADE repo 內，symlink 進 .claude/skills/ 讓它在本 repo 也可觸發（單一真相在 skills/）
-fs.symlinkSync(path.join('..', '..', 'skills', 'ade-add-service'), path.join(dest, '.claude', 'skills', 'ade-add-service'), 'dir')
+// 這些 skill 在 ADE repo 內也要可觸發，symlink 進 .claude/skills/（單一真相在 skills/）
+for (const s of ['ade-add-service', 'ade-add-skill']) {
+  fs.symlinkSync(path.join('..', '..', 'skills', s), path.join(dest, '.claude', 'skills', s), 'dir')
+}
 for (const rel of fs.readdirSync(dest, { recursive: true })) {
   const p = path.join(dest, rel)
   if (!fs.statSync(p).isFile()) continue

package/lib/runner.js

@@ -8,10 +8,12 @@ const END = '<!-- ADE:END -->'
 
 function run(cmd, pkgDir) {
   try {
-    if (cmd === 'init') init(process.cwd(), pkgDir)
-    else if (cmd === 'update') update(process.cwd())
+    const i = process.argv.indexOf('--workspaces')
+    const ws = i !== -1 ? process.argv[i + 1] : undefined
+    if (cmd === 'init') init(process.cwd(), pkgDir, ws)
+    else if (cmd === 'update') update(process.cwd(), ws)
     else {
-      console.error('Usage: init | update')
+      console.error('Usage: init | update  [--workspaces <path>]')
       process.exit(1)
     }
   } catch (e) {
@@ -20,15 +22,15 @@ function run(cmd, pkgDir) {
   }
 }
 
-function init(cwd, srcDir) {
+function init(cwd, srcDir, ws) {
   if (fs.existsSync(path.join(cwd, '.ade.json'))) {
     throw new Error('Already initialized here; run update instead')
   }
-  install(cwd, srcDir)
+  install(cwd, srcDir, ws)
   console.log('ADE init done')
 }
 
-function update(cwd) {
+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'))
@@ -40,7 +42,7 @@ function update(cwd) {
   try {
     execSync(`git clone --depth 1 "${cfg.source}" "${path.join(tmp, 'repo')}"`, { stdio: 'inherit' })
     removeManaged(cwd)
-    install(cwd, path.join(tmp, 'repo'))
+    install(cwd, path.join(tmp, 'repo'), ws)
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true })
   }
@@ -57,7 +59,7 @@ function removeManaged(cwd) {
   }
 }
 
-function install(cwd, srcDir) {
+function install(cwd, srcDir, wsOverride) {
   // 先驗證再動手：update 只清理 ade- 前綴，非前綴 skill 裝了就清不掉
   const srcSkills = path.join(srcDir, 'skills')
   const skillDirs = fs.existsSync(srcSkills)
@@ -90,15 +92,20 @@ function install(cwd, srcDir) {
   }
   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')) : {}
+
+  // 作業區可指向既有的 repo 存放資料夾（--workspaces 或 .ade.json 的 workspaces），避免重複 clone
+  const ws = wsOverride || prev.workspaces || 'workspaces'
+  fs.mkdirSync(path.resolve(cwd, ws), { recursive: true })
+  const rel = path.relative(cwd, path.resolve(cwd, ws)).split(path.sep).join('/')
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+    const giPath = path.join(cwd, '.gitignore')
+    const gi = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : ''
+    if (!gi.split('\n').some((l) => l.trim().replace(/\/$/, '') === rel)) {
+      fs.writeFileSync(giPath, (gi ? gi.trimEnd() + '\n' : '') + rel + '/\n')
+    }
+  }
   let source = null
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(srcDir, 'package.json'), 'utf8'))
@@ -114,7 +121,7 @@ function install(cwd, srcDir) {
   } catch {}
   fs.writeFileSync(
     prevPath,
-    JSON.stringify({ source: source || prev.source || null, commit }, null, 2) + '\n'
+    JSON.stringify({ source: source || prev.source || null, commit, workspaces: ws }, null, 2) + '\n'
   )
   if (!source && !prev.source) {
     console.warn('Warning: repository.url is not set in the ADE repo package.json; update will not work — set source in .ade.json manually')

package/package.json

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

package/template/README.md

@@ -40,8 +40,8 @@ init 會在當前目錄建立：
 
 - `CLAUDE.md` 的 `<!-- ADE:BEGIN/END -->` managed 區段（原有內容不動）
 - `.claude/ade/knowledge/` 知識庫副本、`.claude/skills/ade-*/` skills
-- `workspaces/`（agent clone 服務 repo 的作業區，自動加入 .gitignore）
-- `.ade.json`（記錄來源與版本）
+- 作業區（agent clone 服務 repo 的位置；預設 `workspaces/` 並自動加入 .gitignore。已有固定放 repo 的資料夾時用 `init --workspaces <path>` 指向它，可為相對或絕對路徑，已下載的 repo 直接沿用不重 clone；路徑在本目錄外就不動 .gitignore）
+- `.ade.json`（設定檔：`source` 來源、`commit` 版本、`workspaces` 作業區路徑。直接編輯即可改設定，改 `workspaces` 後不需重跑任何指令）
 
 之後同指令改跑 `update` 拉取最新知識（update 會直接 clone 最新版，不受 dlx 快取影響）。
 
@@ -53,8 +53,8 @@ knowledge/
 ├── process/     # 團隊流程知識
 ├── specs/       # 當前功能規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-skills/          # init 時注入工作目錄的 .claude/skills/（五支，見下方 Skills 一覽）
-.claude/skills/  # 在本 repo 內工作用的 skills（三支＋ade-add-service 的 symlink，見下方 Skills 一覽）
+skills/          # init 時注入工作目錄的 .claude/skills/（六支，見下方 Skills 一覽）
+.claude/skills/  # 在本 repo 內工作用的 skills（三支＋add-service、add-skill 的 symlink，見下方 Skills 一覽）
 claude-md/       # CLAUDE.md managed 區段的內容
 ```
 
@@ -70,6 +70,8 @@ claude-md/       # CLAUDE.md managed 區段的內容
 
 - **`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。
 
 ### 在本 ADE repo 內工作用的 skills（PO／維護者在本 repo 開 Claude Code 使用）

package/template/claude-md/section.md

@@ -6,7 +6,7 @@
 ### Session 開始時
 
 - **檢查知識新鮮度**：讀 `.ade.json`，執行 `git ls-remote <source> HEAD`，若 hash 與 `commit` 不符，提醒使用者執行 update 後再繼續（勿自行修改 managed 內容）
-- Session 一律從本目錄（hub 根）開啟；在 `workspaces/<service>/` 內開啟會失去 ade skills
+- Session 一律從本目錄（hub 根）開啟；在作業區的服務 repo 內開啟會失去 ade skills
 
 ### 知識分層
 
@@ -16,7 +16,7 @@
 
 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>/`
+3. 服務 repo 放在作業區（路徑見 `.ade.json` 的 `workspaces`，預設 `workspaces/`）；`<作業區>/<service>/` 已存在就直接用，不存在才依 `repo.url` / `repo.branch` clone 進去
 4. 讀服務 repo 自身的 README／CLAUDE.md／AGENTS.md 完成安裝、啟動、測試；跨服務流程慣例見 `knowledge/process/`，功能規格見 `knowledge/specs/`
 
 ### 知識維護

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

@@ -19,6 +19,6 @@
 
 ## Agent 執行時
 
-- 在 `workspaces/` 下任何服務 repo commit 都遵守本慣例
+- 在作業區（`.ade.json` 的 `workspaces` 路徑）下任何服務 repo commit 都遵守本慣例
 - 一個 commit 一件事；混雜多個意圖時拆開
 - 服務 repo 自己的 CLAUDE.md／AGENTS.md 若另有 commit 規範，以服務 repo 為準（分層規則見 `../README.md`）

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

@@ -28,7 +28,7 @@ description: 為團隊建立或修改流程慣例並落地到 ADE 知識庫。
 
 1. 依 `ade-contribute` skill 流程 clone ADE repo、建分支（含查重：同一流程已有 issue/PR 就別重開）
 2. 寫 `knowledge/process/<主題>.md`（細節層，kebab-case 檔名）
-3. 需要 skill 的：在 `skills/` 下建立，**目錄名必須 `ade-` 前綴**——runner 只管理此前綴，非前綴會被拒裝
+3. 需要 skill 的：依 `ade-add-skill` skill 建立（它管使用對象選擇、放置位置與命名規則）
 4. 需要常駐行的：在 `claude-md/section.md` 適當小節加一行指標
 5. 更新 `process/README.md` 的主題索引
 6. 依 `ade-contribute` 慣例開 PR；merge 後各工作目錄 update 即生效

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

@@ -0,0 +1,16 @@
+---
+name: ade-add-skill
+description: 為 ADE 生態新增 skill（供 ADE repo 內或消費端工作目錄使用）。使用者說「新增 skill」「建一支 skill」「把這個做成 skill」「這個 skill 消費端也要能用」時使用。
+---
+
+# 新增 skill
+
+1. **判斷所在位置**：repo 根有 `knowledge/services/` → 你在 ADE repo 內，直接編輯本 repo 檔案；只有 `.claude/ade/knowledge/` → 你在工作目錄，依 `ade-contribute` skill 的流程 clone ADE repo 並建立分支（絕不直接改 `.claude/ade/` 副本）
+2. **選使用對象**——這決定放哪，不確定就問使用者：
+   - **消費端工作目錄用** → `skills/ade-<name>/`。init/update 會注入各工作目錄的 `.claude/skills/`；**目錄名必須 `ade-` 前綴**，runner 只管理此前綴，非前綴會被拒裝
+   - **ADE repo 內用**（PO／維護者）→ `.claude/skills/ade-<name>/`
+   - **兩邊都用** → 放 `skills/ade-<name>/`，再建 symlink：`ln -s ../../skills/ade-<name> .claude/skills/ade-<name>`（單一真相在 `skills/`，維護只改一份）
+3. 寫 `SKILL.md`：frontmatter 的 `name` 與目錄同名；`description` 寫觸發語（使用者會說什麼、什麼情境該觸發）；body 遵守 context 紀律——只寫「何時做＋去哪看」，超過一頁的細節拆到 `knowledge/process/` 檔並連結（禁止孤兒：細節檔必須被引用）
+4. skill 內需要「開 PR 回 ADE repo」的動作一律寫「依 `ade-contribute` 流程」，不要重複實作回流機制
+5. 更新本 repo `README.md` 的 Skills 一覽
+6. 收尾：ADE repo 內 → 照一般 git 慣例 commit；工作目錄 → 依 `ade-contribute` 流程開 PR

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

@@ -12,7 +12,7 @@ description: 功能開發完成後，核對 spec 與實作是否一致，移除
 1. 確認這次開發對應的 PRD 與受影響 spec（從使用者、branch 或 PR 上下文取得；不確定就問）
 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 的 `🚧` 區塊
+4. 逐項核對：對照作業區（`.ade.json` 的 `workspaces` 路徑）下的實際實作，檢查每個屬於本次 PRD 的 `🚧` 區塊
    - 已實作且行為一致 → 移除該標記行（整行刪除，內容保留）
    - 實作與 spec 不符 → 以**實作為準**修改 spec 內容，並記下差異
    - 沒做的項目 → 保留標記，記下

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

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