shared/skills/todo/SKILL.md

name, description, argument-hint

name	description	argument-hint
todo	把「需求 → 分析 → 產生 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`）。	[--source <需求描述|檔案路徑|議題編號>] [--file <path>] [--impl-model <id|alias>] [--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 <path>] [--impl-model <id|alias>] [--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>（<alias>），當前模型為 <current-model-id>。
   請執行 /model <alias> 切換後重新呼叫本 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

---
model: <實作模型 id>
model_alias: <實作模型 alias，若無 alias 則省略此欄>
model_reason: <階段 3 產出的理由，含「使用者指定」註記時比照>
analyzed_by: <階段 1 確認的分析模型 id，原樣含變體標記>
analyzed_at: <yyyy/MM/dd HH:mm:ss，依 spec-time-log，Asia/Taipei>
scope: <階段 2 產出的 scope>
---

「給執行本清單 Agent 的強制規則」區塊

固定內容，只代換 <model>／<alias> 與時間戳，四條規則與錯誤訊息格式逐字比照、不可簡化或改寫措辭：

## 0. 給執行本清單 Agent 的強制規則（先讀完再動手）

| 規則 | 內容 |
| --- | --- |
| **模型鎖定** | 本檔 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 |
| **不符就停** | 當前模型 ≠ `<model>` 時，**立刻停止、不做任何檔案修改**，輸出下方錯誤訊息並要求使用者切換。 |
| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 |
| **附加不覆蓋** | 若之後要往本檔追加新需求：`model` 相同 → 附加到檔尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 |

```
[<yyyy/MM/dd HH:mm:ss>][模型檢查][ERR]: 本清單指定 <model>（<alias>），當前模型為 <current-model-id>。
請執行 /model <alias> 切換後重新載入本清單，本次不進行任何修改。
```

> 當前模型 id 的取得方式：Claude Code 沒有提供模型 id 的環境變數，agent 依自身系統提示所述的 exact model ID 自我回報即可；無法確定時請使用者以 `/status` 確認，**不要用猜的**。

checklist（依 /jsc-shared:spec-todo-list 排序與具體化）

• 逐項 - [ ] **編號 短標題**：具體內容，內容需動詞＋對象＋驗收條件齊備，能舉證對應 path:line 或需求彙整中的哪一句。
• 依影響範圍由小到大排序（XS/S/M/L/XL，見 spec-todo-list），範圍相同時前置依賴排前面。
• 編號規則：清單有自然的分組（例如多個獨立工作方向）時，用「群組代號＋序號」（如 A0-1、B1-2，仿本檔範例）；沒有分組時用整數流水號（1、2、3…）。日後附加新項目時，編號延續既有規則、不得重複或跳號造成混淆。
• 清單分成多個彼此有先後依賴的群組時，仿照本檔範例在 checklist 前加一段「### 執行順序」註明群組間的強制先後與理由；若清單本身沒有這種分階段結構，省略此小節即可，不必為了套版而硬分組。
• 不得把任何需求彙整未提及、也無法合理推得的項目塞進清單；有疑慮的項目標「需人工確認」。

階段 5：檔案已存在的處理（需求核心，不可簡化）

寫檔前先讀 --file（預設 ./todo.md）目前是否存在、若存在再解析其 frontmatter：

狀況	動作
檔案不存在	直接建立，寫入階段 4 產出的完整內容。
存在 且 frontmatter model 相同	附加到檔案最後：加一條 --- 分隔與 ## 追加（<yyyy/MM/dd HH:mm:ss>） 標題，接新的 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 相同」列的附加格式）。
  • 選「取消」→ 不寫入任何內容，回報「已取消，<path> 未變更」。
  • 選「其他」→ 依使用者實際輸入處理，仍不得在未取得明確同意前寫入。
• --append／--overwrite 已明確回答這個分支時（見〔參數〕表），依 spec-ask-user「已從其他管道得知答案時跳過詢問」直接照該旗標執行，不再彈出 AskUserQuestion；--yes 單獨出現不算已回答，仍要問。

階段 6：交付

輸出摘要表格：

項目	內容
分析模型	階段 1 確認的模型（analyzed_by）
實作模型	階段 3 選出的模型（model / model_alias），並註明是推薦還是使用者指定
項目數	本次新增的 checklist 項目數
檔案路徑	實際寫入的絕對路徑
本次動作	新建／附加／覆蓋 三者之一

並在最後明確提醒使用者：

請以 <alias>（找不到 alias 時用完整 id）模型開新 session 執行本清單：<path>。

---

呼叫方式

依 /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」）自動觸發