JefferyandClaude Opus 5
73b9cd9f75
install 寫完轉接檔後，把叫用鏈真的走一遍：轉接檔 → PATH 上的 tea-sdlc → 流程正本。
最脆弱的是中間那一環。套件裝在某個 Node 版本底下，換個版本就找不到了，而轉接檔本身
看起來完全正常——沒有這道驗證，使用者要到第一次打 /sdlc-plan 才發現，那時他已經離開
安裝的心智狀態很久了。所以不是查檔案在不在，而是真的到 PATH 上把 tea-sdlc 找出來執行
一次，再把取回的正本跟套件裡的那一份逐字比對：找不到、叫不動、或叫到的是另一份安裝，
三種都驗得出來。轉接檔則逐一回磁碟讀，比對存在且內容含正確的叫用行。
驗證不碰網路，也與 Gitea 登入、時間追蹤無關，所以無條件執行。
驗不過回 ok:false，但已經寫好的轉接檔一份都不刪。回滾在升級情境下是淨損失：原本有一組
能用的舊轉接檔，覆蓋後驗證失敗再刪掉，使用者就從「有點舊但能用」變成什麼都沒有；何況
最可能的病灶是「PATH 上找不到 tea-sdlc」，那不是轉接檔的問題。
為此 lib 多一個 Failure：有一種失敗是事情做完了、檔案也寫出去了，只是驗不過，那時最該
交出去的正是「已經寫了哪些、哪一段不通」。envelope 形狀不變，只是 {ok:false, error}
旁邊多一個 data，只讀 error.code 的呼叫端照常運作。
--dry-run 不寫入，也就沒有東西可驗，verify 標成 skipped。
Closes #59
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.7 KiB
3.7 KiB
tea-sdlc — 以 tea 驅動 SDLC 全流程的跨平台指令組
本 repo 提供六個顯式指令（/sdlc-plan、/sdlc-analyze、/sdlc-feat、/sdlc-fix、/sdlc-sync、/sdlc-report），
把軟體開發流程的各階段固定成可重複的步驟。流程正本只寫一份平台中立 markdown，
由 scripts/install.js 產生 Claude Code、Codex、Antigravity、Copilot、Kiro、oh-my-pi、OpenCode 各自的薄轉接檔。
本 repo 以 npm 佈署：npm i -g <git url> 裝出 tea-sdlc 指令，tea-sdlc install 產生各平台轉接檔。
轉接檔裡沒有路徑，只有一句 tea-sdlc prompt --name <指令名>，正本在哪由入口自己回推。
六個流程正本都到齊了；安裝器佈署的就是
prompts/裡的那六份。進度見 議題 #1 底下的工作包。
模組邊界
改動時請先確認要動的東西屬於哪一層，不要讓職責外溢到相鄰目錄。
| 目錄 | 職責 | 邊界 |
|---|---|---|
prompts/ |
流程正本（sdlc-{plan,analyze,feat,fix,sync,report}.md），唯一的事實來源 |
平台中立 markdown，不含任何平台專屬語法 |
scripts/ |
所有副作用（Gitea API、git、檔案系統）的唯一出口 | Node、零外部套件，僅用內建 fetch / child_process / fs |
templates/ |
所有產出格式（議題、PR、報表、總覽網頁） | 以 {{變數}} 佔位，不含邏輯。唯一例外是 overview-artifact.html：它是一份要在瀏覽器裡開的網頁，需要一段把 mermaid 圖畫出來的腳本 |
references/ |
規則正本（實作規範、註解格式對照表、可行性檢查清單） | 由流程正本指名讀取，不自行散落於 prompts |
bin/tea-sdlc.js |
指令入口：取走子指令，其餘 argv 原樣交出去 | 不含任何平台目錄知識，也不自己動手做事 |
scripts/install.js |
平台偵測與轉接檔產生／移除 | 唯一知道各平台目錄結構的地方 |
scripts/install-verify.js |
安裝後走一遍叫用鏈（轉接檔 → PATH 上的 tea-sdlc → 流程正本） | 只認拿到的轉接檔路徑，不自己推導平台目錄；不碰網路 |
skills/ |
各助理原生 plugin 機制讀取的 skills | 目前為空；指令以轉接檔形式佈署 |
慣例
- 零外部套件：
package.json不得出現dependencies或devDependencies。測試用 Node 內建node:test+node:assert。 - 契約以議題為正本：腳本的 flag 介面、JSON 輸出形狀、前置檢查與路徑定位規則，正本在議題 #1，實作時以該處為準；本檔不複寫，以免兩邊走鐘。
- 測試：
npm test（等同node --test）。測試產生的暫存一律寫到.tmp/，該目錄已被 git 忽略，也不會被測試探索掃到。 - 不改目標專案：本 plugin 只讀目標專案的程式碼，不寫入目標專案的
CLAUDE.md或任何設定檔。 唯一的例外是 git 自己的內部中繼資料——git worktree add一定會在目標 repo 的.git/worktrees/底下寫東西，那是 git 的機制，無法避免，也不是專案的內容檔。 - 工作樹集中在家目錄：每顆工作包的工作樹開在
~/.tea-sdlc/worktrees/{hash}， 路徑由owner/repo/分支名純函式推導（scripts/lib.js的worktreePath）， 不查表也不寫狀態檔。不開在目標專案裡（會出現在它的git status）， 也不開在它的兄弟目錄（那個目錄結構屬於使用者）。 - 不自動觸發：所有指令僅由使用者明確叫用；skill/command 的
description統一以「僅由 /sdlc-xxx 指令叫用。」起頭。