tea-sdlc

以 tea 與 Gitea REST API 驅動 SDLC 全流程的跨平台指令組。 把規劃、分析、實作、修正、整併、工時回報六個階段，固定成可重複、可被任何 coding agent 執行的流程。

• 流程正本只有一份：平台中立 markdown 放在 prompts/，改規則不會出現各平台版本分歧。
• 副作用集中：所有對 Gitea 與 git 的呼叫下沉到 scripts/ 的零相依 Node 腳本，統一 JSON 輸入輸出。
• 產出有固定形狀：議題、PR、報表一律套 templates/ 的模板。

六個流程正本都到齊了，tea-sdlc install 會把它們一次佈署到偵測到的平台。 完整需求見議題 #1，進度見其底下的工作包。

---

六個指令

指令	做什麼
/sdlc-plan	把一段口語需求變成結構化的需求議題
/sdlc-analyze	逐題把可行性疑點問到共識，據以產出工作包
/sdlc-feat	領取工作包、開分支、逐項實作並開 PR
/sdlc-fix	處理 PR 上的留言
/sdlc-sync	把散落在留言裡的決策整併回議題描述
/sdlc-report	產出週／月／年工時報表

---

目錄結構

tea-sdlc/
├── prompts/                 # ★ 流程正本：六個指令的平台中立 markdown
├── scripts/                 # 所有 Gitea / git 副作用的唯一出口（Node，零相依）
├── templates/               # 議題、PR、報表、總覽網頁的輸出模板
├── references/              # 規則正本：實作規範、註解格式、可行性檢查清單
├── bin/tea-sdlc.js          # 單一指令入口：install / uninstall / prompt / status
├── skills/                  # 各助理原生 plugin 機制讀取的 skills（目前為空）
├── .claude-plugin/          # Claude Code 的 plugin / marketplace manifest
├── .codex-plugin/           # Codex 的 plugin manifest
├── .agents/plugins/         # Codex 的 marketplace manifest
├── plugin.json              # Antigravity 的 plugin manifest
├── package.json             # npm 打包與測試入口，無任何相依套件
├── AGENTS.md                # 給 AI 助理的模組邊界與慣例
└── README.md

---

前置需求

安裝與佈署（tea-sdlc install）只需要 Node；其餘是跑流程指令時才需要的。 本工具一律不替你安裝任何東西。

需求	用途	缺了會怎樣
Node.js ≥ 20	執行 tea-sdlc 與 scripts/	連 tea-sdlc 都跑不起來
git	分支與 commit 操作	install 照樣把轉接檔裝好，只在輸出裡列出缺的東西；流程指令中止並印出安裝指引
tea 並已登入	Gitea 議題、標籤、Milestone、留言、工時	同上；登入用 tea login add
目標 repo 已開啟時間追蹤	工時碼錶	流程指令中止，並指出 Settings → Advanced Settings → Enable Time Tracker
帳號對目標 repo 的 issues unit 有寫入權	建立與更新議題	流程指令中止；Gitea 的 unit 權限獨立於 push 權限

---

安裝

一行裝好，終端機就多出一個 tea-sdlc 指令：

npm i -g git+https://gitea.jsc.idv.tw/plugins/tea-sdlc.git

要裝特定版本就在網址後面接上 tag：...tea-sdlc.git#v0.1.0。不必設定任何 registry 或憑證。

git+ 前綴不能省。npm 只有看到 git+https:// 才會當成 git repo；寫成 https://….git 會被當成遠端壓縮檔下載，然後以 TAR_BAD_ARCHIVE: Unrecognized archive format 失敗。

接著把六個流程指令佈署到你裝了的每個 agent 平台：

tea-sdlc install

它會列出偵測到的平台讓你勾選（預設全勾），只寫進已經存在的平台目錄，不在沒裝的平台留下孤兒目錄。 沒有終端機可問時（CI、腳本）不會停下來等輸入，直接照預設全裝。 --platform 直接指定安裝對象，--dry-run 先看會動到哪些檔案：

tea-sdlc install --platform claude,codex
tea-sdlc install --dry-run

平台	偵測	轉接檔落點	形式
claude（Claude Code）	~/.claude/	~/.claude/commands/sdlc-*.md	command
codex（Codex）	~/.codex/	~/.codex/prompts/sdlc-*.md	command
opencode（OpenCode）	~/.config/opencode/	~/.config/opencode/command/sdlc-*.md	command
oh-my-pi	~/.omp/	~/.omp/commands/sdlc-*.md	command
antigravity（Antigravity）	~/.gemini/	~/.gemini/skills/sdlc-*/SKILL.md	skill
kiro（Kiro）	~/.kiro/	~/.kiro/skills/sdlc-*/SKILL.md	skill
copilot（GitHub Copilot）	專案裡的 .github/	.github/skills/sdlc-*/SKILL.md	skill

轉接檔裡沒有路徑，只有一句「執行 tea-sdlc prompt --name sdlc-plan」。正本在哪由 PATH 上的 tea-sdlc 自己回推——升級 Node、換版本管理器、改 npm prefix 都不會讓七個平台的轉接檔同時失效。

還沒裝 git 或 tea 也可以先裝：轉接檔的產生不需要它們， 安裝會把缺的東西列在輸出的 missingBinaries 與 warning 裡，但不會替你安裝，也不會因此中止。 真正需要它們的是流程指令本身，跑之前補上即可。

---

更新 / 移除

改流程正本、腳本、模板或規則，只要重裝套件，下一次叫用就讀到新的，不必重新佈署； 只有指令數量或轉接檔模板本身變了，才需要再跑一次 tea-sdlc install（轉接檔過時時， 叫用它會在輸出最前面提醒你）。

想做的事	指令
更新到最新版	npm i -g git+https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
指令數量變了之後重新佈署	tea-sdlc install
查目前版本、正本位置與環境	tea-sdlc status
只移除轉接檔（正本不動）	tea-sdlc uninstall
連套件一起移除	tea-sdlc uninstall → npm rm -g tea-sdlc

不要用 npm update -g。 這個套件是從 git URL 裝的，npm update -g 認不得它的來源， 不會有任何更新發生，也不會報錯——重裝（上表第一行）才是更新的方式。

移除的順序不能顛倒。 先 npm rm -g tea-sdlc 會把 tea-sdlc 指令一起帶走， 留在七個平台目錄裡的轉接檔就再也沒有東西能刪它們了，只能手動一個個找出來。

tea-sdlc uninstall 只刪自己產生的檔案：每份轉接檔裡都有產生標記，沒有標記的同名檔案一律留著， 並在輸出裡告訴你留了哪些。

---

給 agent 的入口

轉接檔指向的就是這一支。它把流程正本原樣印到 stdout，不包 JSON——那些內容是要給模型讀的。

tea-sdlc prompt --name sdlc-plan

其餘子指令與所有腳本一樣輸出單行 JSON {ok, data, error:{code, message}}，exit 0 或 1。

tea-sdlc status    # 版本、正本位置、是否 link 模式、node/git/tea/登入、各平台轉接檔現況

status 在環境不健康時指令本身仍算成功（ok 為 true、data.healthy 為 false）： 「查詢失敗」與「成功查到你環境有問題」的下一步完全不同，不該由同一個旗標表示。

---

附錄

其他安裝方式（plugin / marketplace 機制）

這些是各助理原生的 plugin / marketplace 機制。它們目前裝不出任何指令——skills/ 還是空的， 真正會生效的是上面 tea-sdlc install 產生的轉接檔。保留在這裡是因為這些機制本身有用 （自動更新、plugin 清單），等 skills/ 有內容時會回來。

Claude Code

claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
claude plugin install tea-sdlc@tea-sdlc

# 更新
claude plugin marketplace update tea-sdlc
claude plugin update tea-sdlc@tea-sdlc

# 移除
claude plugin uninstall tea-sdlc@tea-sdlc
claude plugin marketplace remove tea-sdlc

工作階段內 slash 版（等價）：把 claude plugin 換成 /plugin。 本機開發（免 push）：claude plugin marketplace add /root/plugins/tea-sdlc（本地路徑）後再 install。

Codex

codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
codex plugin add tea-sdlc@tea-sdlc

# 更新（重新抓取 marketplace 的 git 快照）
codex plugin marketplace upgrade tea-sdlc

# 移除
codex plugin remove tea-sdlc@tea-sdlc
codex plugin marketplace remove tea-sdlc

安裝 token tea-sdlc@tea-sdlc = plugin 名（.codex-plugin/plugin.json 的 name）@ marketplace 名（.agents/plugins/marketplace.json 的 name）。安裝後重啟 Codex。

Antigravity（agy）

agy plugin install <url> 目前只支援 github.com；Gitea 等自架 git 請先 clone 再用本地路徑安裝。

git clone https://gitea.jsc.idv.tw/plugins/tea-sdlc.git ~/plugins/tea-sdlc
agy plugin install ~/plugins/tea-sdlc

# 更新（agy 無 update 子指令 → git pull 後重裝）
git -C ~/plugins/tea-sdlc pull
agy plugin uninstall tea-sdlc
agy plugin install ~/plugins/tea-sdlc

GitHub Copilot CLI

copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/tea-sdlc.git
copilot plugin install tea-sdlc@tea-sdlc

# 更新
copilot plugin marketplace update tea-sdlc
copilot plugin update tea-sdlc@tea-sdlc

# 移除
copilot plugin uninstall tea-sdlc@tea-sdlc
copilot plugin marketplace remove tea-sdlc

OpenCode

OpenCode 的「plugin」是 TypeScript/npm 套件，不適用於本 repo；改用目錄安裝。 OpenCode 會讀 ~/.config/opencode/skills/（也會讀 ~/.claude/skills/、~/.agents/skills/）。

git clone https://gitea.jsc.idv.tw/plugins/tea-sdlc.git ~/plugins/tea-sdlc
mkdir -p ~/.config/opencode/skills
cp -r ~/plugins/tea-sdlc/skills/* ~/.config/opencode/skills/

Windows PowerShell：cp -r A B → Copy-Item A B -Recurse -Force、rm -rf X → Remove-Item X -Recurse -Force、~ → $HOME。

---

開發

npm test        # 等同 node --test，使用 Node 內建測試執行器，無任何外部套件

測試產生的暫存一律寫到 .tmp/（已被 git 忽略，也不會被測試探索掃到）。 模組邊界與其餘慣例見 AGENTS.md。