create-agentic-dev-env 0.2.5 → 0.2.6

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.5",
+  "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 快取影響）。
 

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-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）