create-agentic-dev-env 0.2.1 → 0.2.3

package/bin/create.js

@@ -18,6 +18,8 @@ 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')
 for (const rel of fs.readdirSync(dest, { recursive: true })) {
   const p = path.join(dest, rel)
   if (!fs.statSync(p).isFile()) continue

package/package.json

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

package/template/README.md

@@ -54,7 +54,7 @@ knowledge/
 ├── specs/       # 當前功能規格，持續迭代的真相來源
 └── prd/         # 一次開發一檔的需求文件，歷史文件不迭代
 skills/          # init 時注入工作目錄的 .claude/skills/（五支，見下方 Skills 一覽）
-.claude/skills/  # 在本 repo 內工作用的 skills（三支，見下方 Skills 一覽）
+.claude/skills/  # 在本 repo 內工作用的 skills（三支＋ade-add-service 的 symlink，見下方 Skills 一覽）
 claude-md/       # CLAUDE.md managed 區段的內容
 ```
 
@@ -64,7 +64,7 @@ claude-md/       # CLAUDE.md managed 區段的內容
 
 - **`ade-contribute`** — 知識回流的核心通道。當 agent 在工作中發現知識庫內容與現實不符（服務資訊過期、文件缺漏），或學到值得保存的新知識時觸發。它會先查 ADE repo 的 open issues／PRs 避免重複回流（已有記錄就留言補充），沒有才開 issue 記錄缺口，接著 clone 本 ADE repo、建分支、修改對應文件、開 PR 連結該 issue。人只需要 review PR。**注意：絕不直接改工作目錄裡的 `.claude/ade/` 副本**——那是 managed 區域，update 時會被覆蓋，改了等於白改；這支 skill 存在的意義就是把修改導向正確的地方。其他三支 skill 的「開 PR」動作也都委派給它，所以回流機制只需要維護這一份。
 
-- **`ade-add-service`** — 在知識庫註冊新服務。使用者說「新增服務」「把某某服務加進知識庫」時觸發。它會依 `knowledge/services/_template.yaml` 的欄位結構建立服務描述檔（`repo` 的 url 與 branch 為必填，因為 agent 之後要靠它自主 clone 服務），同步在 `services/index.md` 總覽表加一列，最後走 `ade-contribute` 流程開 PR。資訊不足時它會問人，不會留空猜測。
+- **`ade-add-service`** — 在知識庫註冊新服務。使用者說「新增服務」「把某某服務加進知識庫」時觸發。它會依 `knowledge/services/_template.yaml` 的欄位結構建立服務描述檔（`repo` 的 url 與 branch 為必填，因為 agent 之後要靠它自主 clone 服務），同步在 `services/index.md` 總覽表加一列。資訊不足時它會問人，不會留空猜測。**本 ADE repo 內也可用**（`.claude/skills/` 有 symlink，這是主要使用場景）：在本 repo 直接編輯、照一般 git 慣例收尾；在工作目錄則走 `ade-contribute` 流程開 PR。
 
 - **`ade-align-spec`** — 開發收尾的文件對齊。RD 完成一個 PRD 的開發後觸發。它對照 `workspaces/` 下的實際實作，逐一核對 spec 中屬於這次 PRD 的 `🚧 尚未實作` 標記：做完且行為一致的移除標記；實作與 spec 有出入的**以實作為準**修改 spec 並記下差異；沒做的保留。全部驗收項完成時把 PRD 狀態改為「已實作」。最後開 PR，把差異清單列給 PO 判斷是否接受。它只動屬於這次 PRD 的標記，同一份 spec 上其他進行中 PRD 的標記不會被誤刪。
 

package/template/knowledge/process/README.md

@@ -12,6 +12,14 @@
 
 原則：**預設 context 最小化**——常駐層只寫「何時做＋去哪看」（參考技巧），細節留在本目錄等被載入。用 `ade-add-process` skill 引導整個落地流程。
 
+## 流程的結構規則
+
+- **禁止孤兒文件**：本目錄的每份文件必須被某支 skill 或 section.md 常駐行引用——沒有指標指到的文件永遠不會在對的時機進入 context，是死知識
+- **執行入口**：每個「有觸發時機、有完成狀態」的流程都要有 skill 作為執行入口；貫穿性約束（如 commit 風格）例外——常駐一行 + 本目錄細節檔即可
+- **大流程拆階段**：步驟多或跨角色的流程，拆成多支**自足**的階段 skill（各自寫明前置條件與產出），另設一支薄的總覽 skill——只放階段地圖與「如何判斷目前進度」，是導航不是執行
+- **狀態外部化**：階段交接的狀態必須落在檔案（如 PRD 狀態欄、spec 的 🚧 標記）；任何階段 skill 開場先讀檔判斷進度，不依賴上一階段的 context 記憶——下一階段可能是新 session、甚至不同的人觸發
+- **Subagent 隔離**：執行痕跡重的階段（大量讀檔、跑指令、探索）交給 subagent 執行、只回傳結論，避免污染主 context
+
 ## 檔案慣例
 
 - 一個主題一個 md 檔，kebab-case 檔名（例：`git-commit.md`、`branching.md`、`release.md`）

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

@@ -15,11 +15,14 @@ description: 為團隊建立或修改流程慣例並落地到 ADE 知識庫。
 
 多數流程是組合：常駐一行（或一支 skill）＋ process 細節檔。
 
+**大流程要拆**：步驟多或跨角色的流程，拆成多支自足的階段 skill ＋ 一支薄總覽 skill（只放階段地圖與進度判斷）。階段交接狀態必須外部化到檔案，各階段 skill 開場先讀檔判斷進度；執行痕跡重的階段建議交 subagent 隔離（結構規則詳見 `knowledge/process/README.md`）。
+
 ## 2. Context 紀律（每一步都遵守）
 
 - **參考技巧**：常駐層與 skill body 只寫「何時做＋去哪看」，細節放 process/ 檔按需載入——預設 context 越小越好
 - section.md 常駐規則一條一行；**常駐規則超過 10 行時，新增前必須與使用者確認取捨**（合併、降級為 skill 觸發、或刪一條舊的）
 - skill 的 description 寫觸發語、body 精簡；超過一頁的細節拆到 process/ 檔並連結
+- **禁止孤兒**：新增的 process/ 文件必須被 skill 或常駐行引用，否則它永遠不會進入 context
 
 ## 3. 落地
 

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

@@ -5,10 +5,10 @@ description: 在 ADE 知識庫註冊新服務。使用者說「新增服務」
 
 # 新增服務
 
-1. **先確認尚未註冊**：讀 `knowledge/services/index.md` 與 `services/` 目錄，該服務（或同 repo 的別名）已存在時，改走 `ade-contribute` 更新既有描述檔，不要另建
-2. 依 `ade-contribute` skill 的流程 clone ADE repo 並建立分支
+1. **判斷所在位置**：repo 根有 `knowledge/services/` → 你就在 ADE repo 內，直接編輯本 repo 檔案；只有 `.claude/ade/knowledge/` → 你在工作目錄，依 `ade-contribute` skill 的流程 clone ADE repo 並建立分支（絕不直接改 `.claude/ade/` 副本）
+2. **確認尚未註冊**：讀 `knowledge/services/index.md` 與 `services/` 目錄，該服務（或同 repo 的別名）已存在時，改為更新既有描述檔，不要另建
 3. 複製 `knowledge/services/_template.yaml` 為 `knowledge/services/<service-name>.yaml`
 4. 逐欄位填寫。**`repo`（url、branch）為必填**——agent 之後要靠它自主 clone；bootstrap 流程不要寫進來，那歸服務 repo 自己的文件（分層規則見 `knowledge/README.md`）
    - 資訊不足時詢問使用者，不要留空、不要猜測
 5. 在 `knowledge/services/index.md` 的總覽表加入該服務（一～兩行：定位與關係）
-6. 依 `ade-contribute` 流程開 PR 回 ADE repo
+6. 收尾：在 ADE repo 內 → 依本 repo 一般 git 慣例 commit（是否開 PR 由使用者決定）；在工作目錄 → 依 `ade-contribute` 流程開 PR 回 ADE repo