create-agentic-dev-env 1.2.0 → 1.3.0

package/README.md

@@ -67,6 +67,7 @@ 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`（平台偵測、專案範本優先）

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.2.0",
+  "version": "1.3.0",
   "description": "Scaffold and manage team Agentic Dev Environment (ADE) knowledge repos",
   "repository": {
     "type": "git",

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 並列出用途，不會像文件一樣過期

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-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，使用者才知道多了什麼能用