create-agentic-dev-env 1.3.2 → 1.4.0

package/README.md

@@ -9,7 +9,7 @@
 本工具生成並維護一種 repo（**ADE repo**）來把這兩件事抽出來共用：
 
 - **知識**（`knowledge/`）— 服務 registry、跨服務流程慣例、產品規格與 PRD。agent 需要時自己去讀，不用人轉述。
-- **方法**（`skills/`）— 十五支 `ade-*` skill，把「怎麼開需求、怎麼開發、怎麼交付、怎麼維護文件」寫成 agent 照著跑的流程。
+- **方法**（`skills/`）— 十六支 `ade-*` skill，把「怎麼開需求、怎麼開發、怎麼交付、怎麼維護文件」寫成 agent 照著跑的流程。
 
 再加一條讓它不會腐爛的機制：工作目錄裡的知識是**唯讀副本**，agent 用的過程中發現內容與現實不符，會**當場開 PR 修回來**，人只需要 review。
 
@@ -33,7 +33,7 @@
 pnpm dlx create-agentic-dev-env my-ade
 ```
 
-生成的 `my-ade/` 帶完整結構、十五支 skills、一份給團隊讀的 README（安裝步驟、核心概念、場景速查、逐支 skill 詳解都在裡面）。接著：
+生成的 `my-ade/` 帶完整結構、十六支 skills、一份給團隊讀的 README（安裝步驟、核心概念、場景速查、逐支 skill 詳解都在裡面）。接著：
 
 1. 填 `my-ade/package.json` 的 `repository.url`——放 GitHub／GitLab 填 git url；只在本地填絕對路徑（見[本地模式](#本地模式ade-repo-不放-githubgitlab)）
 2. `git add -A && git commit`（init／update 都從 commit 取內容，沒有 commit 會被擋下），放 GitHub／GitLab 的再 push
@@ -71,6 +71,8 @@ pnpm dlx "git+ssh://git@github.com/ORG/my-ade.git" update
 
 或在工作目錄對 agent 說「更新 ADE」（`ade-update`）：比對版本、提醒未回流的手改、更新後回報新增的 skill。session 開始偵測到落後時也會主動提醒。
 
+要換來源、切換本地／遠端、或把 `workspaces` 指到別處，說「ADE 設定」（`ade-config`）——它改 `.ade.json` 後直接重建；`.ade.json` 的 `source` 一經設定就以它為準，ADE repo 的 `repository.url` 只是 init 時的初值。
+
 ### 本地模式：ADE repo 不放 GitHub／GitLab
 
 ADE repo 只是本機（或共用磁碟）上的一個 git repo 也能用：`repository.url` 填絕對路徑、commit，安裝與更新改用 `file:` 形式：
@@ -138,12 +140,13 @@ PO 把想法問成 PRD（Discovery → 盲點拷問 → `validate-prd.sh`）→
 
 ## Skills
 
-ADE repo 帶十六支 skill，逐支詳解在生成的 ADE repo README；這裡只列用途。「兩邊」＝工作目錄與 ADE repo 內都可用。
+ADE repo 帶十七支 skill，逐支詳解在生成的 ADE repo README；這裡只列用途。「兩邊」＝工作目錄與 ADE repo 內都可用。
 
 | Skill | 一句話 | 可用處 |
 | --- | --- | --- |
 | `ade-help` | 即時掃描列出當前位置可用的 ade-* skills | 兩邊 |
 | `ade-update` | 比對版本、提醒未回流手改、更新並回報新增 skill | 工作目錄 |
+| `ade-config` | 看／改工作目錄安裝設定 `.ade.json`：本地／遠端模式、來源 url 或路徑、workspaces 位置；改完直接 update 重建 | 兩邊 |
 | `ade-contribute` | 修改 ADE 知識庫的唯一通道：工作副本、查重、開 PR（本地模式 push 分支交人 merge） | 工作目錄 |
 | `ade-add-service` | 依 `_template.yaml` 註冊服務並同步總覽 | 兩邊 |
 | `ade-list-service` | 列出已註冊服務，回報總覽與描述檔不一致處 | 兩邊 |

package/bin/create.js

@@ -21,7 +21,7 @@ fs.cpSync(path.join(__dirname, '..', 'template'), dest, { recursive: true })
 fs.renameSync(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'))
 fs.renameSync(path.join(dest, 'dot-claude'), path.join(dest, '.claude'))
 // 這些 skill 在 ADE repo 內也要可觸發，symlink 進 .claude/skills/（單一真相在 skills/）
-for (const s of ['ade-add-service', 'ade-add-skill', 'ade-add-process', 'ade-create-prd', 'ade-prd-to-spec', 'ade-help', 'ade-list-service']) {
+for (const s of ['ade-add-service', 'ade-add-skill', 'ade-add-process', 'ade-create-prd', 'ade-prd-to-spec', 'ade-help', 'ade-list-service', 'ade-config']) {
   fs.symlinkSync(path.join('..', '..', 'skills', s), path.join(dest, '.claude', 'skills', s), 'dir')
 }
 for (const rel of fs.readdirSync(dest, { recursive: true })) {

package/lib/runner.js

@@ -86,9 +86,10 @@ 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')
   }
+  // 工作目錄已設定的 source 優先（ade-config 可把它改成本地路徑或另一個 url）；ADE repo 的 repository.url 只在 init 時當初值
+  const src = prev.source || source
   // 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 {
@@ -141,6 +142,8 @@ function install(cwd, srcDir, wsOverride) {
     let st = null
     try { st = fs.lstatSync(wsDir) } catch {}
     if (st && st.isSymbolicLink()) fs.unlinkSync(wsDir)
+    // init 預設建的是空的實體目錄；之後改指向別處（ade-config）時空目錄直接換成 symlink，有東西才要人搬
+    else if (st && st.isDirectory() && fs.readdirSync(wsDir).length === 0) fs.rmdirSync(wsDir)
     else if (st) throw new Error('workspaces already exists and is not a symlink; move its contents into the target folder and remove it, then retry')
     fs.symlinkSync(ws, wsDir, 'dir')
   } else {

package/package.json

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

package/template/README.md

@@ -9,7 +9,7 @@
 ADE 把這兩件事抽出來共用：
 
 - **知識**（`knowledge/`）— 服務 registry、跨服務流程慣例、產品規格與 PRD。agent 需要時自己去讀，不用人轉述。
-- **方法**（`skills/`）— 十五支 `ade-*` skill，把「我們怎麼開需求、怎麼開發、怎麼交付、怎麼維護文件」寫成 agent 照著跑的流程。
+- **方法**（`skills/`）— 十六支 `ade-*` skill，把「我們怎麼開需求、怎麼開發、怎麼交付、怎麼維護文件」寫成 agent 照著跑的流程。
 
 再加一條讓它不會腐爛的機制：工作目錄裡的知識是**唯讀副本**，agent 用的過程中發現內容與現實不符，會**當場開 PR 修回來**，人只需要 review。
 
@@ -39,7 +39,7 @@ ADE 把這兩件事抽出來共用：
 
 | | 是什麼 | 誰在動它 |
 | --- | --- | --- |
-| **ADE repo**（就是本 repo） | 團隊知識與 skills 的**唯一真相來源**，全隊共用一份。 | 一律走 PR（agent 端由 `ade-contribute` 引導） |
+| **ADE repo**（就是本 repo） | 團隊知識與 skills 的**唯一真相來源**，全隊共用一份。 | 一律走 PR（agent 端由 `ade-contribute` 引導）；[本地模式](#本地模式ade-repo-不放-githubgitlab)沒有 PR，在本 repo 內直接 commit、或由人 merge 回流分支 |
 | **工作目錄**（hub） | 你自己電腦上的一個資料夾，是**開 Claude Code 的起點**。裡面有一份 ADE 的唯讀副本＋全部 skills，底下的 `workspaces/` 放實際要開發的服務 repo。 | 副本不要手改（update 會整個覆蓋）；`workspaces/` 下的服務 repo 照平常方式開發 |
 
 ### 步驟 1：設定 SSH（只做一次）
@@ -105,7 +105,7 @@ init 在**當前目錄**建立以下內容，既有檔案不會被覆蓋：
 pnpm dlx "git+ssh://git@github.com/ORG/__ADE_NAME__.git" init --workspaces ~/projects
 ```
 
-`workspaces/` 會建成該資料夾的 symlink：`cd workspaces` 就到 `~/projects`，底下已下載的 repo 直接沿用。實際位置記在 `.ade.json` 的 `workspaces`，事後改這個欄位再跑一次 update 即可重建 symlink。
+`workspaces/` 會建成該資料夾的 symlink：`cd workspaces` 就到 `~/projects`，底下已下載的 repo 直接沿用。實際位置記在 `.ade.json` 的 `workspaces`；事後要換位置、換來源或切換本地／遠端模式，對 agent 說「ADE 設定」（`ade-config`）即可。
 
 ### 步驟 4：日後更新
 
@@ -231,6 +231,7 @@ flowchart LR
 | 發現 ADE 的知識有錯或缺漏 | 「把這個記回知識庫」 | `ade-contribute` |
 | 想把某個做法定成團隊慣例 | 「以後都這樣做」 | `ade-add-process` |
 | 想把某個流程做成 skill | 「新增 skill」 | `ade-add-skill` |
+| 看或改安裝設定：本地／遠端、來源、作業區位置 | 「ADE 設定」「改成本地模式」「workspaces 指到…」 | `ade-config` |
 
 ---
 
@@ -244,6 +245,7 @@ flowchart LR
 | --- | --- | --- |
 | **`ade-help`** | 列出當前位置可用的 ade-* skills 與各自用途（「有哪些 skill」「ADE 支援什麼」）。清單由 `list-skills.sh` 掃 `.claude/skills/ade-*/SKILL.md` 的 frontmatter 即時產生——**不寫死清單**，skill 搬家或新增都不用回頭改；掃的是當前位置真正載得到的目錄，工作目錄與 ADE repo 自然列出各自那套。 | ✅ |
 | **`ade-update`** | 把工作目錄的 managed 內容拉到本 repo 最新版（「更新 ADE」，或 session 開始偵測到落後時）。先用 `git ls-remote` 比對 `.ade.json` 的 `commit`（一樣就不跑）、提醒把 managed 區域的手改先走 `ade-contribute` 回流，才執行 `pnpm dlx <source> update`，最後回報版本變化與期間新增的 skill。**只在消費端工作目錄用**——本 repo 內沒有 managed 副本，用一般 `git pull`。 | — |
+| **`ade-config`** | 查看或修改工作目錄的安裝設定 `.ade.json`（「ADE 設定」「改成本地模式」「作業區換位置」）：模式（由 `source` 是路徑還是 url 判定）、來源 repo、`workspaces` 位置。改完直接跑 update 重建；`.ade.json` 的 `source` 一經設定就以它為準，不會被本 repo 的 `repository.url` 蓋回——所以可以用自己的本地 clone 當來源快速迭代、再切回遠端。在本 repo 內則是看／改 `package.json` 的 `repository.url`（init 的初值）與 `ade.upstream`。 | ✅ |
 | **`ade-contribute`** | 從工作目錄修改本知識庫的**唯一通道**（「改 ADE 的 spec／skill」「回流」）。主動撰寫直接建分支開工；被動回流先查 open issues／PRs 避免重複，沒有才開 issue 記錄缺口、PR 再連回該 issue。工作副本放 `workspaces/<ade-repo-name>/`，已存在就重用、收尾切回主幹，人只需 review PR。本地模式（`source` 是路徑）沒有 issue／PR：push 分支交人 merge。**絕不直接改工作目錄的 `.claude/ade/` 副本**——那是 managed 區域，update 時會被覆蓋。其他 skill 的「開 PR」動作都委派給它。 | — |
 | **`ade-add-service`** | 在知識庫註冊新服務（「新增服務」）。依 `knowledge/services/_template.yaml` 建描述檔（`repo` 的 url 與 branch 必填，agent 之後要靠它自主 clone），並同步 `services/index.md` 總覽表。資訊不足會問人，不留空猜測。在本 repo 直接編輯收尾，在工作目錄則走 `ade-contribute`。 | ✅ |
 | **`ade-list-service`** | 列出目前所有已註冊的服務（「有哪些服務」）。讀 `services/index.md` 並與目錄下的描述檔比對，回報清單與兩者不一致處。只讀不改。 | ✅ |
@@ -275,8 +277,8 @@ knowledge/
 ├── process/     # 跨服務流程與團隊級慣例（含 ade-dev-workflow/ 開發流程規則）
 ├── specs/       # 產品規格，持續迭代的真相來源；GLOSSARY.md 是產品域詞彙
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
-skills/          # init 時注入工作目錄的 .claude/skills/（十五支，見上方 Skills）
-.claude/skills/  # 在本 repo 內工作用的 skills（ade-feedback-upstream ＋ 七支的 symlink）
+skills/          # init 時注入工作目錄的 .claude/skills/（十六支，見上方 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/skills/ade-config/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ade-config
+description: 查看或修改工作目錄的 ADE 安裝設定（.ade.json）——本地或遠端模式、來源 ADE repo 的 git url 或本地路徑、workspaces 作業區位置；在 ADE repo 內則是 package.json 的 repository.url。使用者說「ADE 設定」「ade config」「看目前設定」「改成本地模式」「來源改成…」「workspaces 指到…」「作業區換位置」時使用。
+---
+
+# ADE 設定
+
+1. **判斷所在位置**：當前目錄有 `.ade.json` → 工作目錄（hub）；repo 根有 `knowledge/` 與帶 `ade` 欄位的 `package.json` → ADE repo 內；都不是 → 請使用者到 hub 根或 ADE repo 根再執行
+
+## 工作目錄：`.ade.json`
+
+2. **查看**：讀 `.ade.json`，顯示
+   - **模式**：`source` 是檔案系統路徑（`/`、`~`、`.` 開頭或 `file://`）→ 本地模式；否則遠端模式（列出 host）
+   - `source`、`commit`（對照 `git ls-remote <source> HEAD` 標示是否最新）
+   - `workspaces`：`null` ＝ 就在 hub 底下；有值時列出目標，並確認 `workspaces` 真的是指向它的 symlink
+3. **修改**：改 `.ade.json` 對應欄位後，**直接**執行 update（不經 `ade-update` 的版本比對——換來源或換作業區時即使 commit 相同也要重建）：
+   ```bash
+   pnpm dlx "<dlx 形式的 source>" update
+   ```
+   dlx 形式：`git@host:org/repo.git` → `git+ssh://git@host/org/repo.git`（冒號換斜線）；本地路徑 → `file:<絕對路徑>`
+   - **切換本地／遠端、換來源**：`source` 改成新的 git url 或絕對路徑。本地路徑必須是有 commit 的 git repo（runner 會擋沒有 commit 的）。runner 以 `.ade.json` 的 `source` 為準，不會被 ADE repo 的 `repository.url` 蓋回——所以「團隊 repo 在 GitHub、我本機用自己的 clone 當來源快速迭代」是可行的，改回 url 即回到遠端
+   - **換作業區**：`workspaces` 改成目標路徑（相對 hub 根或絕對）。`workspaces/` 是空目錄或 symlink 時 runner 直接換成新 symlink；**實體目錄且非空**會被拒絕——先請使用者把內容搬到目標再試；改回 `null` 時先 `rm workspaces`（舊 symlink），update 才會建回實體目錄
+4. 回報 `.ade.json` 前後差異與 update 結果；來源換了就順帶列新舊 commit 之間的變化（同 `ade-update` 第 5 步）
+
+## ADE repo 內：`package.json`
+
+5. 顯示／修改 `repository.url`（init 時寫進各工作目錄 `.ade.json.source` 的**初值**，git url 或絕對路徑；已 init 過的工作目錄不受影響，要換用上面的流程）與 `ade.upstream`（`ade-feedback-upstream` 的回饋對象）。改完照一般 git 慣例 commit

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

@@ -11,11 +11,11 @@ description: 從工作目錄修改中央 ADE 知識庫並開 PR（ADE repo 只
 
 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`
+   - 開工前 `git fetch origin` 並從最新主幹開分支：`git switch -c <branch> origin/HEAD`（`origin/HEAD` 即遠端預設分支，不假設叫 `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；`[upstream-candidate]` 類的機制改良則 append 到 ADE repo 根的 `UPSTREAM-CANDIDATES.md`（同樣走分支）
+   - 〔本地〕查重改看 `git branch -r` 與 `git log origin/HEAD --oneline -30` 有無同一缺口的分支或 commit；不開 issue，缺口描述（缺什麼／哪裡過期／在哪個情境發現）寫進 commit body；`[upstream-candidate]` 類的機制改良則 append 到 ADE repo 根的 `UPSTREAM-CANDIDATES.md`（同樣走分支）
 4. 修改 `knowledge/` 下對應文件
    - 修改前先讀原文，沿用既有格式與詞彙
    - 服務描述檔必須符合 `knowledge/services/_template.yaml` 的欄位結構；收錄範圍遵守 `knowledge/README.md` 的分層規則與「底層原則：Context 管理」（常駐最小、細節分檔按需載入）
@@ -23,4 +23,4 @@ description: 從工作目錄修改中央 ADE 知識庫並開 PR（ADE repo 只
 5. Commit、push 分支，開 PR（GitHub 用 `gh pr create`，GitLab 用 `glab mr create`）；被動回流的 PR 描述加 `Closes #<issue 編號>`
    - gh/glab 不可用或未登入時的降級路徑：push 分支後，把 compare／new-MR 網址給使用者，請人手動開
    - 〔本地〕push 分支即止、不開 PR（非 bare 的本地 repo 也接受 push 到非 checked-out 的分支）；回報分支名與 diff 摘要，**merge 由人在 ADE repo 內執行**（`git -C <source> merge <branch>`），人當場要求才替他跑
-6. 告知使用者 PR 連結（〔本地〕分支名），並把工作副本切回主幹（`git switch main`）留給下次；merge 後在工作目錄執行 update 即可取得新版
+6. 告知使用者 PR 連結（〔本地〕分支名），並把工作副本切回主幹（`git switch <預設分支>`）留給下次；merge 後在工作目錄執行 update 即可取得新版