diff --git a/README.md b/README.md index 0f73fe0..fc1a107 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,8 @@ shared/ | Skill | 用途 | 使用方法 | | --- | --- | --- | | `models` | 查詢目前可用哪些模型並依 `spec-model` 的標籤體系標註，維護 `~/.claude/jsc/models.json` 快取，依任務類型推薦模型或檢查當前模型是否符合指定模型。是 `spec-model` 的唯一可執行入口——其他 skill 需要模型清單或推薦時一律呼叫本 skill，不自行重寫探測或推薦邏輯 | `/jsc-shared:models`；可帶 `--refresh`（重跑探測與 smoke test）、`--task `（依對映表推薦模型）、`--check `（比對指定模型與當前模型）、`--json` | -| `todo` | 把「需求 → 分析 → 產生 `todo.md` → 交給指定模型實作」固定成可重複執行的流程：先依 `spec-model` 的「需求分析」任務挑分析模型（不符就先停下要求切換）、讀取來源（需求描述、本機檔案或 Gitea 議題）釐清需求、再挑一個實作模型，最後產生帶 `model`／`model_alias`／`model_reason` 等 frontmatter 的 `todo.md`，供另開一個以該模型執行的 session 落地實作 | `/jsc-shared:todo`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--file `、`--impl-model `、`--append\|--overwrite`、`--yes` | +| `plan-wiki` | 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁；全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone | `/jsc-shared:plan-wiki`；可帶 `--wiki-repo `、`--index <目錄頁title>`、`--project <計畫名稱>`、`--page <計畫頁title>`、`--host `、`--yes` | +| `todo-wiki` | 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程；不產生本機 `todo.md`，只寫入指定 wiki 目錄頁與 todo 頁 | `/jsc-shared:todo-wiki`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--impl-model `、`--wiki-repo `、`--wiki-index <目錄頁title>`、`--wiki-project <計畫名稱>`、`--wiki-page `、`--append\|--overwrite`、`--yes` | ### 整組 plugin 安裝管理 @@ -178,4 +179,3 @@ shared/ - Copilot：`copilot plugin marketplace update shared && copilot plugin update jsc-shared@shared` > 本 repo 只放純 `SKILL.md` 內容，不含可執行腳本或 hook。 - diff --git a/skills/models/SKILL.md b/skills/models/SKILL.md index bd15e6a..625bbe8 100644 --- a/skills/models/SKILL.md +++ b/skills/models/SKILL.md @@ -1,12 +1,12 @@ --- name: models -description: 查詢目前可用哪些模型並依 spec-model 的固定標籤體系標註（能力等級／成本／延遲／上下文／用途／可用性），維護 `~/.claude/jsc/models.json` 快取，並依任務類型推薦模型或檢查當前模型是否符合指定模型。提供 `--refresh`（重跑探測與 smoke test 並重寫快取）、`--task `（依對映表推薦模型＋一行理由＋次選）、`--check `（比對指定模型與當前模型，不符則依強制切換規則輸出錯誤並回非零狀態）、`--json`（結構化輸出）四個參數，預設模式讀快取（過期或不存在則自動探測）輸出模型 × 標籤表格。當使用者問現在有哪些模型可用、要幫某個任務選模型、要檢查目前模型對不對、要重新驗證模型可用性、或提到 `models` skill、模型標籤、模型快取、`~/.claude/jsc/models.json` 時觸發。不適用於：切換模型本身（使用者自行執行 `/model`）、產生指定模型的 `todo.md`（用 `/jsc-shared:todo`，它會呼叫本 skill 取推薦）、與模型選型無關的一般查詢。 +description: 查詢目前可用哪些模型並依 spec-model 的固定標籤體系標註（能力等級／成本／延遲／上下文／用途／可用性），維護 `~/.claude/jsc/models.json` 快取，並依任務類型推薦模型或檢查當前模型是否符合指定模型。提供 `--refresh`（重跑探測與 smoke test 並重寫快取）、`--task `（依對映表推薦模型＋一行理由＋次選）、`--check `（比對指定模型與當前模型，不符則依強制切換規則輸出錯誤並回非零狀態）、`--json`（結構化輸出）四個參數，預設模式讀快取（過期或不存在則自動探測）輸出模型 × 標籤表格。當使用者問現在有哪些模型可用、要幫某個任務選模型、要檢查目前模型對不對、要重新驗證模型可用性、或提到 `models` skill、模型標籤、模型快取、`~/.claude/jsc/models.json` 時觸發。不適用於：切換模型本身（使用者自行執行 `/model`）、產生指定模型的 wiki TODO（用 `/jsc-shared:todo-wiki`，它會呼叫本 skill 取推薦）、與模型選型無關的一般查詢。 argument-hint: "[--refresh] [--task ] [--check ] [--json]" --- # models — 取得可用模型並加上標籤 -依 `/jsc-shared:spec-model` 的標籤體系與來源優先序，查詢目前帳號／CLI 可用的模型、標註標籤、維護快取，並提供任務推薦與模型檢查兩種決策輔助。**本 skill 是 spec-model 的唯一可執行入口**——其他 skill（如 `/jsc-shared:todo`、`worklog --tune`）需要模型清單或推薦時，一律呼叫本 skill，不得自行重寫探測或推薦邏輯。 +依 `/jsc-shared:spec-model` 的標籤體系與來源優先序，查詢目前帳號／CLI 可用的模型、標註標籤、維護快取，並提供任務推薦與模型檢查兩種決策輔助。**本 skill 是 spec-model 的唯一可執行入口**——其他 skill（如 `/jsc-shared:todo-wiki`、`worklog --tune`）需要模型清單或推薦時，一律呼叫本 skill，不得自行重寫探測或推薦邏輯。 | 模式 | 用途 | 是否重跑探測 | | --- | --- | --- | diff --git a/skills/plan-wiki/SKILL.md b/skills/plan-wiki/SKILL.md new file mode 100644 index 0000000..6f1bc53 --- /dev/null +++ b/skills/plan-wiki/SKILL.md @@ -0,0 +1,159 @@ +--- +name: plan-wiki +description: 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁，全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone。使用者要建立計畫、把計畫加入 wiki 目錄、指定 Gitea wiki repo／目錄頁／計畫頁、要求邊問邊同步 wiki、要求計畫檔案不落地、或提到 plan-wiki、計畫 wiki、wiki 目錄頁時觸發。適用於：需求尚未完整、需要逐題釐清並保存到 wiki 的計畫文件。不適用於：產生本機 plan.md／todo.md、拆 Gitea issue（用 /jsc-doc:issues-analyze）、或非 Gitea wiki。 +argument-hint: "[--wiki-repo ] [--index <目錄頁title>] [--project <計畫名稱>] [--page <計畫頁title>] [--host ] [--yes]" +--- + +# plan-wiki — 逐步建立計畫並同步到 Gitea wiki + +把「逐步詢問 → 彙整計畫 → 同步 wiki 目錄與頁面 → 繼續詢問」固定成可重複流程。每次使用者回答一輪問題後，都必須把目前已確認內容同步到 Gitea wiki，直到使用者明確表示計畫完成；全程不建立本機計畫檔或草稿檔。 + +| 階段 | 動作 | +| --- | --- | +| A. 前置設定 | 確認 Gitea host、token、wiki repo、目錄頁、計畫名稱與計畫頁 | +| B. 讀取 wiki 現況 | 讀取目錄頁與計畫頁，保留既有內容 | +| C. 逐步詢問 | 每輪只問 1～3 個必要問題，使用者回答後整理計畫草稿 | +| D. 同步 wiki | 每輪都更新目錄頁與計畫頁 | +| E. 完成收斂 | 使用者確認計畫完成後輸出 wiki 連結與摘要 | + +## 共用規範（必要前置） + +先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝， +依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。 +本 skill 需要的規範：`spec-output`、`spec-execution`、`spec-gitea`、`spec-ask-user`、`spec-time-log`、`spec-no-scratch-files`、`spec-skill-invocation` + +本 skill 特有補充： + +- 本 skill 會寫入外部 Gitea wiki；目標 wiki repo、目錄頁、計畫頁不明時必須詢問，不得臆測。 +- **不落地絕對規則**：不得建立本機 `plan.md`、`todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。 +- 使用者已用參數指定 `--wiki-repo`、`--index`、`--project`、`--page` 時跳過對應詢問。 +- 每一輪使用者回答後都要同步 wiki。同步失敗時停止下一輪詢問，先回報錯誤與待使用者處理的點。 +- 不要求使用者把 token 貼進對話；token 依 `spec-gitea` 從環境變數或既有設定取得。 + +## 參數 + +`[--wiki-repo ] [--index <目錄頁title>] [--project <計畫名稱>] [--page <計畫頁title>] [--host ] [--yes]` + +| 參數 | 說明 | +| --- | --- | +| `--wiki-repo` | Gitea wiki 所屬 repo，例如 `knowledges/Plan`。未帶且無法從目前 repo 推得時詢問使用者。 | +| `--index` | 目錄頁 title，預設可詢問使用者；若使用者明確說「目錄」可用 `目錄`。 | +| `--project` | 計畫名稱，用於目錄頁 H1、說明與預設頁名。 | +| `--page` | 計畫頁 title；未帶時用 ` 計畫`，但需先告知使用者。 | +| `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 | +| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突或使用者尚未確認的計畫完成判斷。 | + +## 階段 A：前置設定 + +1. 依 `spec-gitea` 決定 host 與 token，只輸出 token「已設定／未設定」。 +2. 確認 `--wiki-repo` 是否為 `owner/repo` 格式；不符合時詢問使用者修正。 +3. 確認目錄頁 title、計畫名稱、計畫頁 title。 +4. 用 `GET /repos//` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。 + +## 階段 B：讀取 wiki 現況 + +1. 依 `spec-gitea` 分頁讀取 `GET /repos///wiki/pages`。 +2. 以 title 查表取得目錄頁與計畫頁的 `sub_url`，不得自行猜測轉義規則。 +3. 讀取頁面：`GET /repos///wiki/page/`，將 `content_base64` 解成 UTF-8 Markdown。 +4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的內容；計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。 + +## 目錄頁格式 + +目錄頁必須維持下列結構；更新時保留既有列，只新增或更新本計畫相關列： + +```markdown +# 計畫 + +<一段計畫說明。> + +| 頁面 | 內容 | +|------|------| +| []() | <頁面內容摘要> | + +產出日期：yyyy-MM-dd +``` + +若目錄頁已存在且不是單一計畫專用目錄，仍以同一張 `| 頁面 | 內容 |` 表格為準：保留原標題與說明，只在表格中 upsert 本計畫頁面列。連結文字用頁面 title；連結 target 用 `encodeURIComponent(title).replace(/%20/g, "%20")` 的結果，不使用 API `sub_url` 反推人工連結。 + +## 計畫頁格式 + +計畫頁使用 Markdown，至少包含： + +```markdown +# + +## 目標 + +## 背景與限制 + +## 範圍 + +## 方案 + +## 待確認 + +## TODO +- [ ] ... +``` + +已有計畫頁時保留使用者明確保留的內容；每輪只更新本 skill 管理的章節。需求不明的部分放在 `## 待確認`，不得自行補完。 + +## 階段 C：逐步詢問 + +每輪最多問 1～3 個問題，問題必須能推進計畫內容。建議順序： + +1. 計畫目標與成功標準。 +2. 使用者、情境、限制條件。 +3. 功能範圍與明確不做的範圍。 +4. 方案拆解、資料流、外部依賴。 +5. 里程碑、驗收項目、風險與待確認。 + +每輪回答後： + +- 將回答整合進計畫頁。 +- 把仍不明確的點列入 `## 待確認`。 +- 產出或更新 `## TODO` checklist，格式依 `spec-todo-list`。 +- 詢問使用者下一輪問題前，先完成階段 D 的 wiki 同步。 + +使用者明確表示「完成」「先到這裡」「計畫完成」時，進入階段 E；不要再追問非必要細節。 + +## 階段 D：同步 wiki + +每輪同步順序固定： + +1. 更新計畫頁。 +2. 更新目錄頁，確保表格中有本計畫頁連結與摘要。 +3. 再次讀回兩個頁面確認內容已更新。 + +API 寫入方式： + +- 建立新頁：`POST /repos///wiki/new`，body 帶 `title`、`content`、`message`。 +- 更新既有頁：先查表取得 `sub_url`，再用 `PATCH /repos///wiki/page/`，body 帶 `title`、`content`、`message`。 +- request body 必須由工具呼叫或記憶中內容直接送出，不得先寫成本機 JSON 或 Markdown 檔。 +- message 用繁體中文，例如 `更新 `。 + +若站台不支援 REST wiki 寫入端點，回報「此站台不支援不落地 wiki 寫入」並停止，不得改用 wiki git clone。 + +## 階段 E：完成收斂 + +輸出摘要表格： + +| 項目 | 內容 | +| --- | --- | +| Wiki repo | `` | +| 目錄頁 | `` | +| 計畫頁 | `` | +| 同步次數 | 本輪實際寫入次數 | +| 待確認 | `## 待確認` 剩餘項目數 | + +最後附上目錄頁與計畫頁 URL。 + +## 呼叫方式 + +依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例： + +| 助理 | 呼叫 | +| --- | --- | +| Claude Code / Antigravity | `/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --index 目錄 --project Kokorone --page "Kokorone 系統架構計畫"` | +| Codex | `$plan-wiki --wiki-repo knowledges/Plan --index 目錄 --project Kokorone` | +| OpenCode | 描述需求（如「逐步問我計畫內容，並同步到 Gitea wiki 目錄與頁面」）自動觸發 | diff --git a/skills/spec-model/SKILL.md b/skills/spec-model/SKILL.md index 843425e..cc2b83e 100644 --- a/skills/spec-model/SKILL.md +++ b/skills/spec-model/SKILL.md @@ -74,7 +74,7 @@ description: JSC plugins 共用「取得可用模型並加上標籤」規範： - **過期規則**：`verified_at` 距今**超過 30 天視為過期**（沿用 worklog 快取的年限慣例），過期記錄需重新走〔三、取得清單的權威來源優先序〕更新，不得直接沿用。 - **內容邊界（重要）**：快取檔**只准存模型中繼資料**（上述欄位），**不得寫入任何工作內容或使用者資料**（例如對話內容、專案路徑、議題內容、任何個資）。任何要寫進這份快取的內容，寫入前都要檢查是否落在這個邊界內。 -## 五、強制切換規則（供 `/jsc-shared:todo` 與其他 skill 使用） +## 五、強制切換規則（供 `/jsc-shared:todo-wiki` 與其他 skill 使用） 任何 skill 宣告了必要標籤（依〔二〕的對映表）或直接指定模型時，執行者當前模型不符就**停止並要求使用者切換**： @@ -100,4 +100,4 @@ description: JSC plugins 共用「取得可用模型並加上標籤」規範： **具體操作步驟（可直接照做，不需另外解讀）**：開啟一份 `.md` 檔案、發現其 YAML frontmatter 含 `model` 欄位時，**在做任何修改前**先自我回報目前模型 id，並與 frontmatter 的 `model` 欄位比對；不符就依〔五、強制切換規則〕的錯誤訊息格式中斷，本次不進行任何修改；相符才繼續往下執行檔案內容。 -本節會被 `/jsc-shared:todo`（產生指定模型 `todo.md` 的 skill）與其他消費這類清單檔的 skill（例如處理 `TARGET.md`、處理議題 TODO 的 skill）引用，各消費端不必重抄本節內容，直接引用本節即可。 +本節會被 `/jsc-shared:todo-wiki`（產生指定模型 wiki TODO 頁的 skill）與其他消費這類清單檔的 skill（例如處理 `TARGET.md`、處理議題 TODO 的 skill）引用，各消費端不必重抄本節內容，直接引用本節即可。 diff --git a/skills/todo-wiki/SKILL.md b/skills/todo-wiki/SKILL.md new file mode 100644 index 0000000..165191e --- /dev/null +++ b/skills/todo-wiki/SKILL.md @@ -0,0 +1,182 @@ +--- +name: todo-wiki +description: 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程：先依 `/jsc-shared:spec-model` 的「需求分析」任務挑出分析模型，當前模型不符就停止；接著讀取來源（需求描述、本機檔案，或走 `/jsc-shared:spec-issue-read` 讀取的 Gitea 議題）並釐清需求，任何不清楚之處依 `/jsc-shared:spec-ask-user` 詢問；再依「依清單實作」任務挑出實作模型或採用使用者指定；最後把帶 `model`／`model_alias`／`model_reason`／`analyzed_by`／`analyzed_at`／`scope` frontmatter 與強制規則區塊的 TODO 內容直接同步到指定 Gitea wiki 目錄頁與 todo 頁。當使用者說要把需求整理成 wiki TODO、同步 todo 到 Gitea wiki、需求轉 todo-wiki、指定模型 todo wiki、或提到 todo-wiki skill 時觸發。不適用於：產生本機 todo.md、把需求拆分成多個 Gitea 議題（用 `/jsc-doc:issues-analyze`）、實作既有 Gitea 議題的 TODO（用 `/jsc-code:issues`）。 +argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index <目錄頁title>] [--wiki-project <計畫名稱>] [--wiki-page ] [--append|--overwrite] [--yes]" +--- + +# todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki + +把「需求 → 分析 → 產生 TODO wiki 頁 → 交給指定模型實作」固定成七個階段。全程不建立本機 `todo.md`、草稿檔、暫存 JSON body 或 wiki clone；唯一輸出位置是指定 Gitea wiki。 + +| 階段 | 做什麼 | 產出 | +| --- | --- | --- | +| 1. 選分析模型 | 依 `spec-model`「需求分析」任務取得推薦模型，比對當前模型 | 相符才繼續，不符則停止 | +| 2. 分析需求 | 讀取來源、釐清不清楚之處 | 需求彙整（目標／驗收條件／限制／`scope`） | +| 3. 選實作模型 | 依 `spec-model`「依清單實作」任務取得推薦模型，或採用使用者指定 | 實作模型 id／alias／理由 | +| 4. 產生 TODO wiki 內容 | 依固定格式產生 frontmatter＋強制規則區塊＋checklist | 僅存在於對話記憶中的 Markdown 內容 | +| 5. 讀取既有 wiki 頁 | 依既有 wiki 頁 frontmatter 決定建立／附加／詢問覆蓋 | 寫入策略 | +| 6. 同步 Gitea wiki | 寫入 todo 頁並 upsert 目錄頁列 | wiki 目錄頁與 todo 頁 | +| 7. 交付 | 輸出摘要表格，提醒以哪個模型開新 session 執行 | 面向使用者的總結 | + +## 共用規範（必要前置） + +先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝， +依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。 +本 skill 需要的規範：`spec-model`、`spec-output`、`spec-execution`、`spec-issue-read`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-no-scratch-files`、`spec-skill-invocation` + +本 skill 特有補充： + +- **不落地絕對規則**：不得建立或更新本機 `todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。 +- `--source` 指向本機檔案時可以唯讀讀取來源檔；這不是輸出落地。`--source` 指向 Gitea 議題附件時，僅可依 `spec-issue-read` 的附件唯讀暫存例外讀取，讀完立即刪除。 +- 本 skill 產生的 wiki todo 頁就是 `spec-model` 第六節所述「帶 `model:` frontmatter 的清單檔」的源頭；本 skill 只負責產生與同步清單，不執行清單內容。 +- 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是寫進 wiki 頁給未來另一個 session 用。 +- 目標 wiki repo、目錄頁、計畫名稱不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。 + +## 參數 + +`[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index <目錄頁title>] [--wiki-project <計畫名稱>] [--wiki-page ] [--append|--overwrite] [--yes]` + +| 參數 | 說明 | +| --- | --- | +| `--source` | 需求來源。未帶時視為必要決策，詢問使用者要用描述／檔案路徑／議題編號哪一種，不得臆測。 | +| `--impl-model` | 直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 | +| `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 | +| `--wiki-index` | wiki 目錄頁 title，例如 `目錄`。 | +| `--wiki-project` | 目錄頁中的計畫名稱，用於目錄頁標題、說明或 upsert 摘要。 | +| `--wiki-page` | todo 頁 title；未帶時用 ` 實作清單`，並在同步摘要中明確列出。 | +| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 | +| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、或對外寫入目標不明等必要決策。 | + +## 階段 1：選分析模型 + +1. 依 `/jsc-shared:spec-model` 第三節取得可用模型清單與標籤。 +2. 依「需求分析／拆 TODO／架構決策」任務列比對必要標籤 `#深度推理` `#分析` `#本機可用`，選出推薦模型。 +3. 確認當前執行本 skill 的模型 id；無法確定時請使用者以 `/status` 確認，不要用猜的。 +4. 當前模型不符時，依 `spec-model` 第五節格式停止並要求使用者切換；不得先做階段 2 分析。 +5. 相符時記錄此模型 id 供階段 4 的 `analyzed_by` 使用。 + +## 階段 2：分析需求 + +1. 判斷來源型態： + - 對應到本機可讀取的檔案路徑 → 視為檔案，唯讀讀取全文，不寫任何衍生檔。 + - 純數字、`#123`、或 Gitea 議題 URL → 視為議題編號，走 `/jsc-shared:spec-issue-read` 讀取描述、所有留言、所有附件。 + - 都不是 → 視為需求描述本文。 +2. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者。 +3. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 `scope`。 +4. 若來源本身有既有 Markdown checklist，依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。 + +## 階段 3：選實作模型 + +1. `--impl-model` 有帶時，以使用者指定為準；盡可能驗證其存在性與可用性，無法驗證也不得拒絕，改在 `model_reason` 註明未能於本機驗證。 +2. 未指定時，依 `/jsc-shared:spec-model`「依清單實作／規格落地」任務列比對必要標籤 `#均衡實作` `#實作` `#本機可用`，選出推薦模型。 +3. 記下最終 `model`、`model_alias`、`model_reason`。 + +## 階段 4：產生 TODO wiki 內容 + +產生 Markdown 內容但不得寫入本機檔案。 + +### frontmatter + +```yaml +--- +model: <實作模型 id> +model_alias: <實作模型 alias，若無 alias 則省略此欄> +model_reason: <階段 3 產出的理由> +analyzed_by: <階段 1 確認的分析模型 id> +analyzed_at: +scope: <階段 2 產出的 scope> +--- +``` + +### 強制規則區塊 + +固定加入： + +```markdown +## 0. 給執行本清單 Agent 的強制規則（先讀完再動手） + +| 規則 | 內容 | +| --- | --- | +| **模型鎖定** | 本頁 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 | +| **不符就停** | 當前模型 ≠ `` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。 | +| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 | +| **附加不覆蓋** | 若之後要往本頁追加新需求：`model` 相同 → 附加到頁面末尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 | +| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei）。不得留待多項一起補勾。 | + +[][模型檢查][ERR]: 本清單指定 （），當前模型為 。 +請執行 /model 切換後重新載入本 wiki 頁，本次不進行任何修改。 +``` + +### checklist + +- 逐項使用 `- [ ] **編號 短標題**：具體內容`。 +- 內容需動詞＋對象＋驗收條件齊備，並能舉證對應 `path:line` 或需求彙整中的哪一句。 +- 依影響範圍由小到大排序；範圍相同時前置依賴排前面。 +- 不得加入需求來源未提及、也無法合理推得的項目；有疑慮者標「需人工確認」。 + +## 階段 5：讀取既有 wiki 頁並決定寫入策略 + +1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。 +2. 確認 `--wiki-repo`、`--wiki-index`、`--wiki-project`；缺少就詢問。 +3. 分頁讀取 `GET /repos///wiki/pages`，以 title 查表取得目錄頁與 todo 頁 `sub_url`。 +4. 讀取既有 todo 頁；若不存在，策略為「建立」。 +5. 既有 todo 頁存在時解析 frontmatter： + +| 狀況 | 動作 | +| --- | --- | +| 頁面不存在 | 建立新 todo 頁。 | +| 頁面存在且 frontmatter `model` 相同 | 附加到頁面最後：加 `---` 分隔與 `## 追加（）` 標題，接新的 checklist 項目；frontmatter 只更新 `analyzed_at`。 | +| 頁面存在且 frontmatter `model` 不同 | 停下來詢問使用者是否覆蓋、沿用舊模型附加、或取消；未得同意不得寫入。 | +| 頁面存在但沒有 frontmatter | 視為不同模型處理。 | + +`--append`／`--overwrite` 已明確回答不同模型分支時，依該旗標執行；`--yes` 不算回答。 + +## 階段 6：同步 Gitea wiki + +同步順序固定： + +1. 寫入 todo 頁。 +2. upsert 目錄頁表格列。 +3. 讀回兩個頁面確認內容已更新。 + +目錄頁表格列格式： + +```markdown +| []() | todo wiki： 實作清單——執行規則、需求彙整、分群任務與驗收條件 | +``` + +API 寫入方式： + +- 建立新頁：`POST /repos///wiki/new`，body 帶 `title`、`content`、`message`。 +- 更新既有頁：先查表取得 `sub_url`，再用 `PATCH /repos///wiki/page/`，body 帶 `title`、`content`、`message`。 +- request body 必須由工具呼叫或記憶中內容直接送出，不得先寫成本機 JSON 或 Markdown 檔。 + +不得自行猜測 Gitea wiki title 到 `sub_url` 的轉義規則；找既有頁一律查表。若 REST wiki 寫入端點不可用，回報「此站台不支援不落地 wiki 寫入」並停止，不得改用 wiki git clone。 + +## 階段 7：交付 + +輸出摘要表格： + +| 項目 | 內容 | +| --- | --- | +| 分析模型 | `analyzed_by` | +| 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 | +| 項目數 | 本次新增的 checklist 項目數 | +| Wiki repo | `` | +| 目錄頁 | URL | +| Todo 頁 | URL | +| 本次動作 | 建立／附加／覆蓋 | + +最後提醒： + +> 請以 ``（找不到 alias 時用完整 id）模型開新 session 執行本 wiki 頁：``。 + +## 呼叫方式 + +依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例： + +| 助理 | 呼叫 | +| --- | --- | +| Claude Code / Antigravity | `/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-index 目錄 --wiki-project Kokorone` | +| Codex | `$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-index 目錄 --wiki-project Kokorone` | +| OpenCode | 描述需求（如「幫我把這段需求分析清楚，直接同步成 Gitea wiki TODO，不要落地檔案」）自動觸發 | diff --git a/skills/todo/SKILL.md b/skills/todo/SKILL.md deleted file mode 100644 index d9af003..0000000 --- a/skills/todo/SKILL.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -name: todo -description: 把「需求 → 分析 → 產生 todo.md → 交給指定模型實作」整條路徑固定成可重複執行的流程：先依 `/jsc-shared:spec-model` 的「需求分析」任務挑出分析模型，當前模型不符就停止並要求切換、不得先分析再說；接著讀取來源（需求描述、本機檔案，或走 `/jsc-shared:spec-issue-read` 讀取的 Gitea 議題）並釐清需求，任何不清楚之處一律依 `/jsc-shared:spec-ask-user` 詢問使用者、絕不臆測或編造；再依「依清單實作」任務挑出實作模型（使用者可用 `--impl-model` 指定，會在 `model_reason` 註明是使用者指定）；最後產生（或視既有檔案 frontmatter 的 `model` 是否相同，決定附加或詢問是否覆蓋）一份帶 `model`／`model_alias`／`model_reason`／`analyzed_by`／`analyzed_at`／`scope` frontmatter 與「給執行本清單 Agent 的強制規則」區塊的 `todo.md`，供使用者另開一個以該模型執行的 session 落地實作。當使用者說要把需求整理成待辦清單交給指定模型做、產生或更新 `todo.md`、幫需求選一個實作模型並寫成清單、要一份鎖定模型的執行清單，或提到 todo skill、需求轉 todo.md、指定模型 todo 時觸發。不適用於：把需求拆分成多個 Gitea 議題（用 `/jsc-doc:issues-analyze`）、實作既有 Gitea 議題的 TODO（用 `/jsc-code:issues`）。 -argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--file ] [--impl-model ] [--append|--overwrite] [--yes]" ---- - -# todo — 需求分析並產生指定模型執行的 todo.md - -把「需求 → 分析 → 產生 `todo.md` → 交給指定模型實作」固定成六個階段，全程強制模型一致性：分析本身要用夠強的模型做，產出的清單要鎖定一個實作模型，執行清單的 agent 開工前必須自我核對模型，不符就停。 - -| 階段 | 做什麼 | 產出 | -| --- | --- | --- | -| 1. 選分析模型 | 依 `spec-model`「需求分析」任務取得推薦模型，比對當前模型 | 相符才繼續，不符則停止 | -| 2. 分析需求 | 讀取來源、釐清不清楚之處 | 需求彙整（目標／驗收條件／限制／`scope`） | -| 3. 選實作模型 | 依 `spec-model`「依清單實作」任務取得推薦模型，或採用使用者指定 | 實作模型 id／alias／理由 | -| 4. 產生 `todo.md` | 依固定格式寫出 frontmatter＋強制規則區塊＋checklist | 草稿內容（尚未寫檔） | -| 5. 檔案已存在的處理 | 依既有檔案 frontmatter 決定建立／附加／詢問覆蓋 | 實際寫入的檔案 | -| 6. 交付 | 輸出摘要表格，提醒以哪個模型開新 session 執行 | 面向使用者的總結 | - ---- - -## 共用規範（必要前置） - -先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝， -依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。 -本 skill 需要的規範：`spec-model`、`spec-output`、`spec-execution`、`spec-issue-read`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-skill-invocation` - -本 skill 特有補充： - -- 本 skill 產生的 `todo.md` 就是 `spec-model` 第六節所述「帶 `model:` frontmatter 的清單檔」的**源頭**；本 skill 自己只負責產生這份清單，不執行清單內容。 -- 全程不落地草稿檔以外的臨時檔案；`--source` 若指向 Gitea 議題附件需要暫存讀取時，比照 `spec-issue-read` 的唯讀暫存例外，讀完立即刪除。 -- 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是**寫進檔案給未來另一個 session 用的**，兩者是不同的模型、不同的檢查時機，不要混淆。 - ---- - -## 參數 - -`[--source <需求描述|檔案路徑|議題編號>] [--file ] [--impl-model ] [--append|--overwrite] [--yes]` - -| 參數 | 說明 | -| --- | --- | -| `--source` | 需求來源。未帶時視為「目標不明」的必要決策（依 `spec-execution`），詢問使用者要用描述／檔案路徑／議題編號哪一種，不得臆測。 | -| `--file` | 產出路徑，**預設 `./todo.md`**（相對於執行本 skill 當下的工作目錄）。 | -| `--impl-model` | 直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 | -| `--append` / `--overwrite` | 針對階段 5「檔案存在且 `model` 不同」情境**提前作答**，用於跳過該次 `AskUserQuestion`；不影響「`model` 相同」時固定附加的規則（見階段 5）。二擇一，同時提供視為衝突，仍需詢問使用者。 | -| `--yes` | 依 `spec-execution` 略過一般性確認（例如「要不要現在就寫檔」）；**不得**用來略過階段 5 對「模型不同是否覆蓋」的詢問——那是破壞性決策，依 `spec-ask-user` 一律必須真的問到答案，除非已用 `--append`／`--overwrite` 明確作答。 | - ---- - -## 階段 1：選分析模型 - -1. 依 `/jsc-shared:spec-model` 第三節取得可用模型清單與標籤（`claude-api` skill → CLI 自陳 → 使用痕跡 → smoke test，前一項取得就不必往下）。 -2. 依第二節「需求分析／拆 TODO／架構決策」任務列比對必要標籤 `#深度推理` `#分析` `#本機可用`，選出推薦模型（加分標籤 `#長上下文`）。 -3. 確認**當前執行本 skill 的模型 id**：agent 依自身系統提示所述的 exact model id 自我回報；無法確定時請使用者以 `/status` 確認，不要用猜的。 -4. 當前模型 ≠ 推薦模型 → 依 `spec-model` 第五節格式**停止並要求使用者切換**，不得先做階段 2 的任何分析： - - ``` - [yyyy/MM/dd HH:mm:ss][模型檢查][ERR]: 本次需求分析建議使用 <推薦 model>（），當前模型為 。 - 請執行 /model 切換後重新呼叫本 skill，本次不進行任何分析。 - ``` - -5. 相符 → 記錄此模型 id（含變體標記，如 `[1m]`，依自我回報原樣記錄）供階段 4 的 `analyzed_by` 使用，繼續階段 2。 - -## 階段 2：分析需求 - -1. **判斷來源型態**（`--source` 未帶則先依〔參數〕表詢問使用者）： - - 對應到本機可讀取的檔案路徑 → 視為**檔案**，讀取全文。 - - 純數字、`#123`、或 Gitea 議題 URL → 視為**議題編號**，走 `/jsc-shared:spec-issue-read`（含描述、所有留言、所有附件；分頁規則依 `spec-gitea`）；議題所在 repo 無法從目前工作目錄的 git remote 推斷時，詢問使用者 `owner/repo`，不得臆測。 - - 都不是 → 視為**需求描述**本文，直接採用 `--source` 的文字內容。 -2. **釐清需求**：依 `/jsc-shared:spec-execution`「不臆測／需人工確認」——目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者（單選／多選判斷時機、選項上限 4、必含「其他」），**不得自行補完或用常見做法代填**。 -3. 產出**需求彙整**：目標、驗收條件、限制條件，以及本次 `todo.md` 的 `scope`（受影響的目錄／repo／模組範圍，供階段 4 frontmatter 使用）。 -4. 若來源本身有既有 Markdown checklist（例如議題描述或既有文件），依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。 - -## 階段 3：選實作模型 - -1. **使用者指定**（`--impl-model` 有帶）：以使用者指定為準。依 `spec-model` 第三節盡可能驗證其存在性與可用性（CLI 自陳比對，可行時 smoke test）；無法驗證也不得拒絕使用者的選擇，改在 `model_reason` 註明「使用者以 `--impl-model` 指定，未能於本機驗證可用性」。`model_reason` 必須明確寫出**這是使用者指定，非本 skill 推薦結果**。 -2. **未指定**：依 `/jsc-shared:spec-model` 第二節「依清單實作／規格落地」任務列比對必要標籤 `#均衡實作` `#實作` `#本機可用`（加分標籤 `#中成本`），選出推薦模型；`model_reason` 寫成一段自然語言理由，**結合階段 2 的需求彙整內容**判斷（例如任務量體、是否需要跨檔案架構判斷、粒度是否已拆解到可直接動手），而不是照抄標籤名稱。 -3. 記下最終的實作模型 `id`、`alias`（若有）、`model_reason`，供階段 4 使用。 - -## 階段 4：產生 todo.md - -格式**完全比照** `/home/coder/plugins/todo.md` 現有樣式，逐項對齊： - -### frontmatter - -```yaml ---- -model: <實作模型 id> -model_alias: <實作模型 alias，若無 alias 則省略此欄> -model_reason: <階段 3 產出的理由，含「使用者指定」註記時比照> -analyzed_by: <階段 1 確認的分析模型 id，原樣含變體標記> -analyzed_at: -scope: <階段 2 產出的 scope> ---- -``` - -### 「給執行本清單 Agent 的強制規則」區塊 - -固定內容，只代換 ``／`` 與時間戳，五條規則與錯誤訊息格式**逐字比照**、不可簡化或改寫措辭： - -````markdown -## 0. 給執行本清單 Agent 的強制規則（先讀完再動手） - -| 規則 | 內容 | -| --- | --- | -| **模型鎖定** | 本檔 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 | -| **不符就停** | 當前模型 ≠ `` 時，**立刻停止、不做任何檔案修改**，輸出下方錯誤訊息並要求使用者切換。 | -| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 | -| **附加不覆蓋** | 若之後要往本檔追加新需求：`model` 相同 → 附加到檔尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 | -| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei，依 `/jsc-shared:spec-time-log`）。**不得留待多項一起補勾**；無法安全完成的項目維持未勾選並標註「需人工確認」，不得略而不報。 | - -``` -[][模型檢查][ERR]: 本清單指定 （），當前模型為 。 -請執行 /model 切換後重新載入本清單，本次不進行任何修改。 -``` - -> 當前模型 id 的取得方式：Claude Code 沒有提供模型 id 的環境變數，agent 依自身系統提示所述的 exact model ID 自我回報即可；無法確定時請使用者以 `/status` 確認，**不要用猜的**。 -```` - -### checklist（依 `/jsc-shared:spec-todo-list` 排序與具體化） - -- 逐項 `- [ ] **編號 短標題**：具體內容`，內容需動詞＋對象＋驗收條件齊備，能舉證對應 `path:line` 或需求彙整中的哪一句。完成後改為 `- [x] **編號 短標題**：具體內容（完成：yyyy/MM/dd HH:mm:ss）`，依上方「完成即勾選」規則逐項就地更新，不得留待多項一起補勾。 -- 依影響範圍由小到大排序（XS/S/M/L/XL，見 `spec-todo-list`），範圍相同時前置依賴排前面。 -- **編號規則**：清單有自然的分組（例如多個獨立工作方向）時，用「群組代號＋序號」（如 `A0-1`、`B1-2`，仿本檔範例）；沒有分組時用整數流水號（`1`、`2`、`3`…）。日後附加新項目時，編號延續既有規則、不得重複或跳號造成混淆。 -- 清單分成多個彼此有先後依賴的群組時，仿照本檔範例在 checklist 前加一段「### 執行順序」註明群組間的強制先後與理由；若清單本身沒有這種分階段結構，省略此小節即可，不必為了套版而硬分組。 -- 不得把任何需求彙整未提及、也無法合理推得的項目塞進清單；有疑慮的項目標「需人工確認」。 - -## 階段 5：檔案已存在的處理（需求核心，不可簡化） - -寫檔前先讀 `--file`（預設 `./todo.md`）目前是否存在、若存在再解析其 frontmatter： - -| 狀況 | 動作 | -| --- | --- | -| 檔案不存在 | 直接建立，寫入階段 4 產出的完整內容。 | -| 存在 且 frontmatter `model` **相同** | **附加到檔案最後**：加一條 `---` 分隔與 `## 追加（）` 標題，接新的 checklist 項目（依既有編號規則延續）。frontmatter 只更新 `analyzed_at`，**不動 `model`／`model_alias`／`model_reason`**。 | -| 存在 且 frontmatter `model` **不同** | **停下來用 `AskUserQuestion` 詢問使用者是否覆蓋**，見下方選項。**未得同意不得寫入任何內容。** | -| 存在 但**沒有** frontmatter | 視為「不同模型」處理，走上一列同樣的詢問流程。 | - -- **詢問選項**（依 `/jsc-shared:spec-ask-user`，4 個以內、含「其他」）：`覆蓋（改用新模型）`／`保留舊檔改用舊模型附加`／`取消`／`其他`。 - - 選「覆蓋」→ 以階段 3～4 產出的新內容整份覆寫，`model`／`model_alias`／`model_reason` 全部換新。 - - 選「保留舊檔改用舊模型附加」→ **放棄階段 3 選出的新實作模型**，改沿用舊檔 frontmatter 的 `model`；階段 4 產生的 checklist 內容改為附加在舊檔最後（同「model 相同」列的附加格式）。 - - 選「取消」→ 不寫入任何內容，回報「已取消，`` 未變更」。 - - 選「其他」→ 依使用者實際輸入處理，仍不得在未取得明確同意前寫入。 -- `--append`／`--overwrite` 已明確回答這個分支時（見〔參數〕表），依 `spec-ask-user`「已從其他管道得知答案時跳過詢問」直接照該旗標執行，不再彈出 `AskUserQuestion`；`--yes` 單獨出現**不算**已回答，仍要問。 - -## 階段 6：交付 - -輸出摘要表格： - -| 項目 | 內容 | -| --- | --- | -| 分析模型 | 階段 1 確認的模型（`analyzed_by`） | -| 實作模型 | 階段 3 選出的模型（`model` / `model_alias`），並註明是推薦還是使用者指定 | -| 項目數 | 本次新增的 checklist 項目數 | -| 檔案路徑 | 實際寫入的絕對路徑 | -| 本次動作 | 新建／附加／覆蓋 三者之一 | - -並在最後明確提醒使用者： - -> 請以 ``（找不到 alias 時用完整 id）模型開新 session 執行本清單：``。 - ---- - -## 呼叫方式 - -依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例： - -| 助理 | 呼叫 | -| --- | --- | -| Claude Code / Antigravity | `/jsc-shared:todo --source "把 X 模組改成非同步"`、`/jsc-shared:todo --source ./RFC.md --file ./plans/x.todo.md`、`/jsc-shared:todo --source 123 --impl-model sonnet`、`/jsc-shared:todo --source ./RFC.md --append` | -| Codex | `$todo --source "..."`，或用 `/skills` 選單 | -| OpenCode | 描述需求（如「幫我把這段需求分析清楚，寫成一份鎖定模型的 todo.md」）自動觸發 |