create-agentic-dev-env 1.3.1 → 1.3.2

package/README.md

@@ -36,7 +36,7 @@ pnpm dlx create-agentic-dev-env my-ade
 生成的 `my-ade/` 帶完整結構、十五支 skills、一份給團隊讀的 README（安裝步驟、核心概念、場景速查、逐支 skill 詳解都在裡面）。接著：
 
 1. 填 `my-ade/package.json` 的 `repository.url`——放 GitHub／GitLab 填 git url；只在本地填絕對路徑（見[本地模式](#本地模式ade-repo-不放-githubgitlab)）
-2. Push 到 GitHub／GitLab
+2. `git add -A && git commit`（init／update 都從 commit 取內容，沒有 commit 會被擋下），放 GitHub／GitLab 的再 push
 3. 在 `my-ade/` 開 Claude Code，說「新增服務」（`ade-add-service`）開始填 `knowledge/`
 
 ### 步驟 2：團隊成員安裝
@@ -73,13 +73,13 @@ pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" update
 
 ### 本地模式：ADE repo 不放 GitHub／GitLab
 
-ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用：`repository.url` 填絕對路徑，安裝與更新改用 `file:` 形式：
+ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用：`repository.url` 填絕對路徑、commit，安裝與更新改用 `file:` 形式：
 
 ```sh
 pnpm dlx "file:/Users/me/my-ade" init     # update 同形式；file: 必要，直接給目錄會找不到相依
 ```
 
-差別只在回流：沒有 issue／PR，`ade-contribute` 把分支 push 回 repo、回報分支名，由人在 ADE repo 內 `git merge`。其他機制照常。
+迭代迴圈：**日常直接在 ADE repo 內開 Claude Code 改、commit 到 main**（八支 skill 可用，不需要分支或 PR）；從工作目錄回流時 `ade-contribute` push 分支回 repo、由人 `git merge`。改完回工作目錄「更新 ADE」。要知道的三件事：先 commit（沒有 commit 會被擋下，不留殘局）、ADE repo 停在 main（update 取的是當下 checked-out 的 HEAD）、`[upstream-candidate]` 改記在根目錄 `UPSTREAM-CANDIDATES.md`。生成的 ADE repo README 有完整說明。
 
 ---
 

package/lib/runner.js

@@ -42,15 +42,26 @@ function update(cwd, ws) {
   try {
     // 本地路徑的 clone 不支援 --depth（只會印警告），其餘來源維持淺 clone
     const depth = fs.existsSync(cfg.source) ? '' : '--depth 1 '
-    execSync(`git clone ${depth}"${cfg.source}" "${path.join(tmp, 'repo')}"`, { stdio: 'inherit' })
+    const repo = path.join(tmp, 'repo')
+    execSync(`git clone ${depth}"${cfg.source}" "${repo}"`, { stdio: 'inherit' })
+    // 先驗證再清：clone 到沒有 commit 的 repo（本地模式常見）會是空目錄，此時清掉 managed 內容只會留下殘局
+    assertAdeRepo(repo)
     removeManaged(cwd)
-    install(cwd, path.join(tmp, 'repo'), ws)
+    install(cwd, repo, ws)
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true })
   }
   console.log('ADE update done')
 }
 
+function assertAdeRepo(dir) {
+  for (const rel of ['knowledge', path.join('claude-md', 'section.md')]) {
+    if (!fs.existsSync(path.join(dir, rel))) {
+      throw new Error(`${rel} not found in the ADE repo checkout — does the repo have a commit on its default branch?`)
+    }
+  }
+}
+
 function removeManaged(cwd) {
   fs.rmSync(path.join(cwd, '.claude', 'ade'), { recursive: true, force: true })
   const skillsDir = path.join(cwd, '.claude', 'skills')
@@ -75,6 +86,19 @@ function install(cwd, srcDir, wsOverride) {
   if (!source && !prev.source) {
     throw new Error('repository.url is not set in the ADE repo package.json; update would not work — fill it in and retry')
   }
+  // srcDir 可能沒有 .git（pnpm dlx file:<本地路徑> 打包時不帶），退而問 source 本身；
+  // 兩者都拿不到＝repo 還沒有 commit（或連不到），此時 .ade.json 的保鮮檢查永遠判定落後——寫任何檔案前先擋下
+  const src = source || prev.source
+  let commit = null
+  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 {}
+  }
+  if (!commit) {
+    throw new Error(`could not resolve the ADE repo commit from ${src} — make sure the repo has at least one commit (and is reachable), then retry`)
+  }
 
   // update 只清理 ade- 前綴，非前綴 skill 裝了就清不掉
   const srcSkills = path.join(srcDir, 'skills')
@@ -128,15 +152,6 @@ 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
-  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')
 }
 

package/package.json

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

package/template/README.md

@@ -26,8 +26,8 @@ ADE 把這兩件事抽出來共用：
 ## 初始設定（建 repo 後做一次）
 
 1. 填 `package.json` 的 `repository.url`——放 GitHub／GitLab 填 git url；**只在本地**填絕對路徑（見[本地模式](#本地模式ade-repo-不放-githubgitlab)）
-2. Push 到 GitHub／GitLab（本地模式跳過）
-3. 開始填 `knowledge/`：服務用 `ade-add-service` 註冊（或手填 `knowledge/services/_template.yaml` 格式並更新 `services/index.md`）
+2. `git add -A && git commit`（init／update 都從 commit 取內容，沒有 commit 會被擋下），放 GitHub／GitLab 的再 push
+3. 開始填 `knowledge/`：在本 repo 開 Claude Code 說「新增服務」（`ade-add-service`），或手填 `knowledge/services/_template.yaml` 格式並更新 `services/index.md`
 
 ---
 
@@ -120,14 +120,25 @@ update 直接 clone 最新版，不受 dlx 快取影響。
 
 ### 本地模式：ADE repo 不放 GitHub／GitLab
 
-ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用，步驟 1 跳過、步驟 2／4 的指令換成 `file:` 形式：
+ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用。步驟 1 跳過，步驟 2／4 的指令換成 `file:` 形式：
 
 ```sh
-# package.json 的 repository.url 填絕對路徑，例如 /Users/me/__ADE_NAME__
-pnpm dlx "file:/Users/me/__ADE_NAME__" init     # update 同形式；file: 必要，直接給目錄會找不到相依
+# 一次性：package.json 的 repository.url 填絕對路徑，commit，然後在工作目錄
+pnpm dlx "file:/Users/me/__ADE_NAME__" init      # update 同形式；file: 必要，直接給目錄會找不到相依
 ```
 
-差別只在回流：沒有 issue／PR，`ade-contribute` 會把分支 push 回這個 repo、回報分支名，由你在 ADE repo 內 `git merge` 後各工作目錄 update。其他 skill 與新鮮度檢查（`git ls-remote <路徑>`）照常。
+之後的迭代迴圈有兩條路，**日常以 A 為主**：
+
+- **A. 直接在本 repo 開 Claude Code** — `ade-add-service`／`ade-create-prd`／`ade-prd-to-spec`／`ade-add-skill`／`ade-add-process` 等八支 skill 都能用，改完 commit 到 main 即可，不需要分支或 PR
+- **B. 從工作目錄回流** — 開發服務時 agent 發現知識過期，`ade-contribute` 會 clone 到 `workspaces/__ADE_NAME__/`、開分支、push 回本 repo 並回報分支名；你回到本 repo `git merge` 即可（沒有 issue／PR）
+
+兩條路收尾都一樣：回工作目錄說「更新 ADE」。session 開始的新鮮度檢查（`git ls-remote <路徑> HEAD`）會自動提醒落後。
+
+三件要知道的：
+
+- **先 commit**：init／update 都從 commit 取內容，create 完沒 commit 會被擋下（不會留殘局）
+- **本 repo 停在 main**：`update` 取的是本 repo 當下 checked-out 的 HEAD；在分支上工作時先不要 update，merge 回 main 再更新
+- **機制改良沒有 issue 可開**：各流程沉澱出的 `[upstream-candidate]` 改為 append 到根目錄 `UPSTREAM-CANDIDATES.md`，`ade-feedback-upstream` 從那裡收
 
 ### 裝好之後，先記這兩支 skill
 
@@ -268,6 +279,7 @@ skills/          # init 時注入工作目錄的 .claude/skills/（十五支，
 .claude/skills/  # 在本 repo 內工作用的 skills（ade-feedback-upstream ＋ 七支的 symlink）
 claude-md/       # CLAUDE.md managed 區段的內容
 CONTEXT.md       # ADE 開發流程的統一詞彙表
+UPSTREAM-CANDIDATES.md  # 本地模式下 [upstream-candidate] 的落點（有 issue tracker 時留空）
 ```
 
 ## 維護原則

package/template/UPSTREAM-CANDIDATES.md

@@ -0,0 +1,15 @@
+# Upstream candidates
+
+各流程收尾沉澱時發現的**機制層**改良（skill 寫法、模板結構、流程設計——非本團隊服務專屬），等 `ade-feedback-upstream` 收割回饋給 create-agentic-dev-env。
+
+ADE repo 放 GitHub／GitLab 時用標題前綴 `[upstream-candidate]` 的 issue 記，本檔留空；**本地模式**（沒有 issue tracker）改 append 在此，一則一節。內文只描述機制，不含服務名稱與程式碼；回饋完成的節刪掉。
+
+本檔不會被複製進工作目錄（runner 只複製 `knowledge/`、`skills/`、`claude-md/`）。
+
+<!--
+## YYYY-MM-DD <一句話標題>
+
+- 解決什麼問題：
+- 在本 repo 的實際效果：
+- 建議的通用作法：
+-->

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` 開出，如 ade-dev 第 5 關）
+1. 取得上游 repo 位址：`package.json` 的 `ade.upstream`（為 null 則詢問使用者）。改良來源除了日常觀察，也包括本 repo 標題前綴 `[upstream-candidate]` 的 issues（各流程收尾沉澱時經 `ade-contribute` 開出，如 ade-dev 第 5 關），以及根目錄 `UPSTREAM-CANDIDATES.md`（本地模式的替代，回饋完把該節刪掉）
 2. **查重**：查上游的 open issues（`gh issue list -R <upstream>`），同一改良已有記錄 → 在該 issue 留言補充使用經驗，不重複開
 3. 開 issue（`gh issue create -R <upstream>`），內容包含：
    - 這個改良解決什麼問題

package/template/knowledge/process/ade-dev-workflow/gates.md

@@ -48,7 +48,7 @@
 
 - 產品規格與實作一致：有 PRD 走 `ade-align-spec`；無 PRD 但動了產品行為 → 起草產品規格更新、**人確認後**依 `ade-contribute` 流程送出
 - `notes.md` 收整成清單給人審視：關鍵發現、決策、流程摩擦與改良建議
-- 清單中屬**機制層**的改良（skill 寫法、模板結構、流程設計，非本服務專屬），依 `ade-contribute` 在 ADE repo 開一則標題前綴 `[upstream-candidate]` 的 issue——內文只描述機制、不含服務名稱與程式碼；是否回饋上游由 ADE repo 維護者判斷，**不在本流程內執行**
+- 清單中屬**機制層**的改良（skill 寫法、模板結構、流程設計，非本服務專屬），依 `ade-contribute` 在 ADE repo 開一則標題前綴 `[upstream-candidate]` 的 issue（本地模式沒有 issue：append 到 ADE repo 根的 `UPSTREAM-CANDIDATES.md`）——內文只描述機制、不含服務名稱與程式碼；是否回饋上游由 ADE repo 維護者判斷，**不在本流程內執行**
 
 ## 第 6 關：Ship
 

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

@@ -15,7 +15,7 @@ description: 從工作目錄修改中央 ADE 知識庫並開 PR（ADE repo 只
 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
+   - 〔本地〕查重改看 `git branch -r` 與 `git log origin/main --oneline -30` 有無同一缺口的分支或 commit；不開 issue，缺口描述（缺什麼／哪裡過期／在哪個情境發現）寫進 commit body；`[upstream-candidate]` 類的機制改良則 append 到 ADE repo 根的 `UPSTREAM-CANDIDATES.md`（同樣走分支）
 4. 修改 `knowledge/` 下對應文件
    - 修改前先讀原文，沿用既有格式與詞彙
    - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）