shared/skills/todo-wiki/SKILL.md

name, description, argument-hint

name	description	argument-hint
todo-wiki	把「需求 → 分析 → 產生鎖定模型的 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`）。	[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <英文系統名稱>_<中文系統名稱>] [--wiki-project <英文系統名稱>_<中文系統名稱>] [--wiki-page <既有頁 title|TODO_<yyyyMMdd>_<HASH>>] [--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-wiki-contents、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 只負責產生與同步清單，不執行清單內容。
• 本 skill 產生的 checklist 每項都要明寫實作方式；文件或程式修改若已有具體方向，必要時再補 建議修改內容，避免讓執行者回頭猜測。
• 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是寫進 wiki 頁給未來另一個 session 用。
• 模型鎖定要在開工前完成：在讀取任何來源、做任何分析、或接觸 wiki 前，先確認目前執行本 skill 的模型 id；無法確定時先請使用者執行 /status，不得用猜的。
• 一項一回寫、一項一確認：每完成一項 checklist，就立刻把該項 - [ ] 改成 - [x]，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。
• 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
• 目錄頁是單一共用頁面，title 預設固定為 CONTENTS，不詢問使用者；只有使用者明確提供 --wiki-index 時才覆蓋預設值。
• TODO 頁 title 預設固定為 TODO_{yyyyMMdd}_{HASH}，不詢問使用者；yyyyMMdd 使用 Asia/Taipei 當日日期，HASH 由需求彙整或系統名稱產生穩定短雜湊並轉成全大寫。
• 開工前先確定系統名稱、再挑要不要合併：依下方〔系統名稱決定〕得到系統名稱後，在階段 2-0 讀到該系統的目錄頁時，依 /jsc-shared:spec-wiki-contents〔使用者互動〕，列出所有「計畫欄有連結、代辦欄空白」的列詢問使用者是否要合併（可以不選）；細節見階段 2「選擇要不要合併進既有列」。
• 目錄頁列合併判斷（哪些列可以合併、找不到可合併列時如何新增列）一律依 /jsc-shared:spec-wiki-contents〔新增列前先找可合併的既有列〕，本 skill 不重複定義。
• 必須詢問使用者兩個獨立決策：是否合併進既有列，以及是否把新的代辦加入既有的 todo 頁內；系統名稱已由〔系統名稱決定〕流程固定，不再詢問是否關聯計畫／系統名稱。目錄頁預設一律更新，除非使用者明確說不要更新目錄頁。
• 需要加入目錄頁時，代辦欄連結到 TODO 頁；系統名稱固定為下方〔系統名稱決定〕的結果，不因是否合併既有列而改變。
• 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只 upsert 本 TODO 對應的既有列或在既有表格附加新列。

系統名稱決定

• 英文系統名稱：使用目前工作目錄的名稱（basename 當前工作目錄）。
• 中文系統名稱：從既有程式碼與文件中尋找（例如 README、package.json／pyproject.toml 的 name／description、CLAUDE.md、專案內顯著的中文專案名稱）；找到多個不一致的候選時，依 /jsc-shared:spec-ask-user 請使用者確認採用哪一個。完全找不到中文名稱時，不得自行編造，依 spec-ask-user 詢問使用者提供。
• --wiki-project 已帶時直接採用（視為使用者已指定英文＋中文系統名稱），跳過上述推論與詢問。
• 決定出的系統名稱在本次 todo-wiki 執行全程固定不變，供目錄頁對應段落標題、TODO 頁 H1 等引用系統名稱處使用；不再走「使用者從既有計畫列中選擇要關聯的系統」這條路徑。

參數

[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <英文系統名稱>_<中文系統名稱>] [--wiki-project <英文系統名稱>_<中文系統名稱>] [--wiki-page TODO_<yyyyMMdd>_<HASH>] [--append|--overwrite] [--yes]

參數	說明
--source	需求來源。未帶時視為必要決策，詢問使用者要用描述／檔案路徑／議題編號哪一種，不得臆測。
--impl-model	直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 model_reason 註明「使用者指定」。
--wiki-repo	指定要同步的 Gitea wiki repo，例如 knowledges/Plan。
--wiki-index	wiki 目錄頁 title；未帶時固定使用 CONTENTS，不詢問。
--wiki-project	系統名稱（英文＋中文）；未帶時依〔系統名稱決定〕流程從工作目錄與程式碼推論。預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。
--wiki-page	todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 TODO_{yyyyMMdd}_{HASH}。
--append / --overwrite	針對既有 wiki todo 頁 frontmatter model 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。
--yes	略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否合併進既有列、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。

階段 1：選分析模型

1. 在讀取任何來源、做任何分析、或接觸 wiki 前，先依 /jsc-shared:spec-model 第三節取得可用模型清單與標籤，並確認目前執行本 skill 的模型 id。
2. 依「需求分析／拆 TODO／架構決策」任務列比對必要標籤 #深度推理 #分析 #本機可用，選出推薦模型。
3. 若當前執行本 skill 的模型 id 無法確定，先請使用者執行 /status，不得用猜的。
4. 當前模型不符時，依 spec-model 第五節格式停止並要求使用者切換；開始任何實作前就要檢查，不得先做階段 2 分析、不得讀取來源、不得接觸 wiki。
5. 相符時記錄此模型 id 供階段 4 的 analyzed_by 使用。

階段 2：分析需求

階段 2-0：確定系統名稱、確認 wiki repo 並讀取目錄頁

1. 先確認 --wiki-repo（即 --wiki-repo 參數）；缺少時依 /jsc-shared:spec-ask-user 詢問，不臆測。
2. 依上方〔系統名稱決定〕得到英文＋中文系統名稱；--wiki-project 已帶則直接採用並跳過推論。
3. 依 /jsc-shared:spec-gitea〔Wiki 頁名轉義規則〕規則 2 分頁查表取 path，取得目錄頁（title 預設 CONTENTS，或 --wiki-index 指定值）的 path 並讀取內容，定位到本系統對應的 ## {英文系統名稱} {中文系統名稱} 段落；目錄頁不存在、或存在但沒有本系統段落，都視為該系統尚無任何計畫或代辦。
4. 本步驟讀到的目錄頁內容供階段 5 重用，不得為同一份目錄頁重複讀取。

選擇要不要合併進既有列

• 依 /jsc-shared:spec-wiki-contents〔新增列前先找可合併的既有列〕，從階段 2-0 讀到的目錄頁取出所有「計畫欄有連結、代辦欄空白」的列；無可合併列不問——一個都沒有時不詢問，直接進入「了解需求」。
• 有可合併列必問——只要存在至少一個這種列，就必須依 /jsc-shared:spec-ask-user 詢問使用者是否要合併其中一列；可不選——選項固定含「不合併，直接新增列」與「其他」，候選 ≤4 用 AskUserQuestion、>4 改文字編號列出。--yes 不得略過（即 --yes 旗標不得用來省略）本次詢問。
• 使用者選定某一列時，記下該列計畫欄連結的 path，供下一步讀取計畫頁全文；使用者選「不合併」時，維持只用 --source 分析需求。

了解需求

1. 判斷 --source 型態：
   • 對應到本機可讀取的檔案路徑 → 視為檔案，唯讀讀取全文，不寫任何衍生檔。
   • 純數字、#123、或 Gitea 議題 URL → 視為議題編號，走 /jsc-shared:spec-issue-read 讀取描述、所有留言、所有附件。
   • 都不是 → 視為需求描述本文。
2. 使用者選定要合併的計畫列時，以該列連結的 path 讀取計畫頁全文，計畫頁全文併入需求來源，並在需求彙整中標明來源（哪些需求來自計畫頁、哪些來自 --source）；讀取失敗（404 或權限不足）時讀取失敗即停——立刻停止並回報，不得改用臆測內容或略過。未選合併時維持只用 --source。
3. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 /jsc-shared:spec-ask-user 詢問使用者。
4. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 scope。
5. 若來源本身有既有 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 內容但不得寫入本機檔案。內容 H1 固定為 {英文系統名稱} {中文系統名稱} 代辦事項（使用〔系統名稱決定〕得到的系統名稱，與 wiki 頁 title TODO_{yyyyMMdd}_{HASH} 是兩件事，不得把雜湊 title 直接當 H1），frontmatter 之後、強制規則區塊之前先放這行 H1。

frontmatter

---
model: <實作模型 id>
model_alias: <實作模型 alias，若無 alias 則省略此欄>
model_reason: <階段 3 產出的理由>
analyzed_by: <階段 1 確認的分析模型 id>
analyzed_at: <yyyy/MM/dd HH:mm:ss，Asia/Taipei>
scope: <階段 2 產出的 scope>
---

強制規則區塊

固定加入：

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

| 規則 | 內容 |
| --- | --- |
| **模型鎖定** | 本頁 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 |
| **不符就停** | 當前模型 ≠ `<model>` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。開始任何實作前就要檢查，不可先讀來源或接觸 wiki。 |
| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 |
| **附加不覆蓋** | 若之後要往本頁追加新需求：`model` 相同 → 附加到頁面末尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 |
| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei）。不得留待多項一起補勾。 |
| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回解碼比對成功；若 wiki 更新失敗、讀回失敗或內容不一致，**立刻停止，不得繼續執行下一項**。 |

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

checklist

• 逐項使用 - [ ] **編號 短標題**：具體內容。
• 內容需動詞＋對象＋實作方式＋驗收條件＋來源依據齊備，並能舉證對應 path:line 或需求彙整中的哪一句；文件或程式修改時，必要時附上 建議修改內容。
• 依影響範圍由小到大排序；範圍相同時前置依賴排前面。
• 不得加入需求來源未提及、也無法合理推得的項目；有疑慮者標「需人工確認」。

階段 5：讀取既有 wiki 頁並決定寫入策略

1. 依 spec-gitea 決定 host 與 token，不輸出 token。
2. --wiki-repo、系統名稱與目錄頁內容沿用階段 2-0 的結果，不重複讀取；--wiki-index 未帶時固定使用 CONTENTS，--wiki-page 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 TODO_{yyyyMMdd}_{HASH}。
3. 詢問使用者兩個獨立決策：是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁（是否合併進既有列已於階段 2「選擇要不要合併進既有列」問過，不重問）。目錄頁預設一律更新；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。
4. 分頁讀取 GET /repos/<owner>/<repo>/wiki/pages，以 title 查表取得 todo 頁 sub_url；若使用者選擇既有 todo 頁，直接以該頁 title 對應 sub_url。目錄頁的 sub_url／內容沿用階段 2-0 已讀取的結果；目錄頁不存在時才建立；目錄頁存在時必須保留原內容，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
5. 讀取既有 todo 頁；若不存在，策略為「建立」。
6. 既有 todo 頁存在時解析 frontmatter：

狀況	動作
頁面不存在	建立新 todo 頁。
頁面存在且 frontmatter model 相同	附加到頁面最後：加 --- 分隔與 ## 追加（<yyyy/MM/dd HH:mm:ss>） 標題，接新的 checklist 項目；frontmatter 只更新 analyzed_at。
頁面存在且 frontmatter model 不同	停下來詢問使用者是否覆蓋、沿用舊模型附加、或取消；未得同意不得寫入。
頁面存在但沒有 frontmatter	視為不同模型處理。

--append／--overwrite 已明確回答不同模型分支時，依該旗標執行；--yes 不算回答。若使用者選擇既有 todo 頁，仍要沿用這個 frontmatter 模型判斷與寫回驗證流程，不得因為是既有頁就跳過。

階段 6：同步 Gitea wiki

同步順序固定：

1. 寫入 todo 頁。
2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則依 spec-wiki-contents〔新增列前先找可合併的既有列〕upsert 本系統對應段落內的表格列。目錄頁不存在才整頁新建（title CONTENTS）；目錄頁存在但沒有本系統段落時，在頁尾新增一個 ## {英文系統名稱} {中文系統名稱} 段落；兩種情況都禁止整頁覆蓋，只修改對應列的代辦／是否已完成／內容欄，或在該段落表格附加新列。
3. 若本次於階段 2「選擇要不要合併進既有列」合併到某個計畫列，回目錄頁把該列是否已產生代辦由 [ ] 改為 [x]、代辦欄填入本次 TODO 頁連結並讀回確認；找不到對應列時不得新建混用列，改以警告回報。未合併時跳過本步驟，直接以新列的代辦欄寫入、計畫欄留空。
4. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認（含步驟 2、3 的異動）。讀回時若回應含 content_base64，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
5. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。

目錄頁是單一共用頁面依系統分段、段落標題與六欄表格格式、列合併規則、以及連結來源（查表取得的 sub_url／path，不使用 percent-encode 的 title）一律依 /jsc-shared:spec-wiki-contents，本 skill 不重複定義；新增列範例（未合併既有計畫列時）：

|  |  |  | [<TODO 頁連結文字>](<查表取得的 path>) | [ ] | todo wiki：<系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |

若既有目錄頁沒有本系統的 ## 段落與六欄目錄表格，附加一段新的段落到頁面末尾，不得刪除或重排其他系統的段落與既有內容。

API 寫入方式：

• 建立新頁：POST /repos/<owner>/<repo>/wiki/new，body 帶 title、content_base64、message。
• 更新既有頁：先查表取得 sub_url，再用 PATCH /repos/<owner>/<repo>/wiki/page/<sub_url>，body 帶 title、content_base64、message。
• content_base64 的值必須是 wiki Markdown 內容以 UTF-8 編碼後再 base64 編碼的結果；title、message 與其他原有欄位行為不變。
• request body 必須由工具呼叫、stdin、shell 變數或記憶中內容直接送出，不得先寫成本機 JSON 或 Markdown 檔。

不得自行猜測 Gitea wiki title 到 sub_url 的轉義規則；找既有頁一律查表。若 REST wiki 寫入端點不可用，回報「此站台不支援不落地 wiki 寫入」並停止，不得改用 wiki git clone。

階段 7：交付

輸出摘要表格：

項目	內容
分析模型	analyzed_by
實作模型	model / model_alias，並註明推薦或使用者指定
已完成項目數	本次實際完成且已回寫確認的 checklist 項目數
Wiki repo	<owner/repo>
目錄頁	URL；若使用者明確不要更新目錄頁，填「未更新（使用者選擇不更新目錄頁）」
Todo 頁	URL
本次動作	建立／附加／覆蓋
已回寫確認	是／否，僅在所有本次 checklist 都完成且讀回比對成功時填 是

最後提醒：

請以 <alias>（找不到 alias 時用完整 id）模型開新 session 執行本 wiki 頁：<todo page URL>。

呼叫方式

依 /jsc-shared:spec-skill-invocation 的統一呼叫方式，本 skill 的實際參數格式與範例：

助理	呼叫
Claude Code / Antigravity	/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-project Kokorone_心音
Codex	$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-project Kokorone_心音
OpenCode	描述需求（如「幫我把這段需求分析清楚，直接同步成 Gitea wiki TODO，不要落地檔案」）自動觸發