shared/skills/plan-wiki/SKILL.md

name, description, argument-hint

name	description	argument-hint
plan-wiki	逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 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。	[--wiki-repo <owner/repo>] [--index <英文系統名稱>_<中文系統名稱>] [--project <英文系統名稱>_<中文系統名稱>] [--page PLAN_<yyyyMMdd>_<HASH>] [--host <gitea主機>] [--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-version-guard、spec-output、spec-execution、spec-gitea、spec-wiki-contents、spec-ask-user、spec-time-log、spec-no-scratch-files、spec-skill-invocation

本 skill 特有補充：

• 本 skill 會寫入外部 Gitea wiki；目標 wiki repo 不明時必須詢問，不得臆測。
• 目錄頁是單一共用頁面，title 預設固定為 CONTENTS，不詢問使用者；只有使用者明確提供 --index 時才覆蓋預設值。
• 計畫頁 title 預設固定為 PLAN_{yyyyMMdd}_{HASH}，不詢問使用者；yyyyMMdd 使用 Asia/Taipei 當日日期，HASH 由已確認的計畫內容、系統名稱或需求摘要產生穩定短雜湊並轉成全大寫。
• 加入目錄頁時，依下方〔系統名稱決定〕得到英文＋中文系統名稱；目錄頁裡該系統對應的 ## {英文系統名稱} {中文系統名稱} 段落使用這組名稱，計畫頁連結填進該段落表格的計畫欄（依 spec-wiki-contents〔新增列前先找可合併的既有列〕決定填入既有列、新增列，或新增整個段落）。
• 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容與其他系統的段落，只 upsert 本系統段落內對應的既有列、在該段落表格附加新列，或該系統尚無段落時新增一個段落。

系統名稱決定

• 需求中已明確指定系統名稱（使用者於對話中講出、或 --project 已帶）：直接採用；若只給了英文或只給了中文其中一種，另一種依需求內容推論後，依 /jsc-shared:spec-ask-user 請使用者確認（單選：採用推論值／自行輸入）。
• 未指定時：依已收集到的需求內容，推論 5 組候選，每組為「大駝峰英文系統名稱＋中文名稱」配對（例如 KokoroneCore 心核）；依 /jsc-shared:spec-ask-user（候選數 5 > 4，改文字編號列出）請使用者從 5 組中選一組，選項另外固定包含「重新產生 5 組」與「自行輸入」：
  • 使用者選「重新產生 5 組」：重新推論另外 5 組不同於前次的候選，再次詢問；可反覆重新產生，不設次數上限。
  • 使用者選「自行輸入」：請使用者直接提供英文＋中文系統名稱，兩者皆須提供。
  • 使用者選其中一組候選：採用該組英文＋中文名稱。
• 決定出的系統名稱在本次 plan-wiki 執行全程固定不變，供目錄頁對應段落標題、計畫頁 H1 等引用系統名稱處使用。
• 不落地絕對規則：不得建立本機 plan.md、todo.md、.md 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 curl --data @file。
• 使用者已用參數指定 --wiki-repo、--index、--project、--page 時跳過對應詢問。
• 每一輪使用者回答後都要同步 wiki；一輪一同步、一輪一確認，不可累積多輪回答後一次送出。同步失敗、讀回失敗或比對不一致時，停止下一輪詢問，先回報錯誤與待使用者處理的點。
• 只有階段 D 的 wiki 同步完成且讀回確認成功後，才能進入下一輪提問。
• 不要求使用者把 token 貼進對話；token 依 spec-gitea 從環境變數或既有設定取得。

參數

[--wiki-repo <owner/repo>] [--index <英文系統名稱>_<中文系統名稱>] [--project <英文系統名稱>_<中文系統名稱>] [--page PLAN_<yyyyMMdd>_<HASH>] [--host <gitea主機>] [--yes]

參數	說明
--wiki-repo	Gitea wiki 所屬 repo，例如 knowledges/Plan。未帶且無法從目前 repo 推得時詢問使用者。
--index	目錄頁 title；未帶時固定使用 CONTENTS，不詢問。
--project	系統名稱（英文＋中文）；未帶時依〔系統名稱決定〕流程推論候選並請使用者選定，用於目錄頁對應段落標題與摘要。
--page	計畫頁 title；未帶時固定使用 PLAN_{yyyyMMdd}_{HASH}，不詢問。
--host	Gitea 主機，依 spec-gitea host 決定順序處理。
--yes	略過一般性確認；不得略過目標 wiki 不明、系統名稱選定、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。

階段 A：前置設定

1. 依 spec-gitea 決定 host 與 token，只輸出 token「已設定／未設定」。
2. 確認 --wiki-repo 是否為 owner/repo 格式；不符合時詢問使用者修正。
3. 確認系統名稱：--project 已帶時直接採用；未帶時依〔系統名稱決定〕流程推論 5 組候選請使用者選定（或使用者要求重新產生／自行輸入）。
4. 確認目錄頁 title：未帶 --index 時固定使用 CONTENTS。
5. 確認計畫頁 title：未帶 --page 時固定使用 PLAN_{yyyyMMdd}_{HASH}。雜湊輸入優先使用已確認的計畫內容；內容不足時使用系統名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。
6. 用 GET /repos/<owner>/<repo> 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。

階段 B：讀取 wiki 現況

1. 依 spec-gitea 分頁讀取 GET /repos/<owner>/<repo>/wiki/pages。
2. 以 title 查表取得目錄頁與計畫頁的 sub_url，不得自行猜測轉義規則。
3. 讀取頁面：GET /repos/<owner>/<repo>/wiki/page/<sub_url>，將 content_base64 解成 UTF-8 Markdown。
4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的新頁內容；目錄頁存在時不得用預設格式覆蓋整頁，只能保留原內容後修改或附加本計畫對應的列。計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。

目錄頁格式

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

目錄頁不存在時，依 spec-wiki-contents〔目錄頁格式〕建立新頁（title CONTENTS），並建立本系統對應的 ## {英文系統名稱} {中文系統名稱} 段落，計畫欄填本計畫頁連結、是否已產生代辦欄填 ○、代辦與是否已完成欄留空；目錄頁已存在時禁止整頁覆蓋，只能依 spec-wiki-contents〔新增列前先找可合併的既有列〕upsert 本系統段落內對應的列、在該段落附加新列，或該系統尚無段落時新增段落，保留其他系統的段落與其餘內容。

計畫頁格式

計畫頁使用 Markdown，H1 固定為 {英文系統名稱} {中文系統名稱} 計畫（使用〔系統名稱決定〕得到的系統名稱，與 wiki 頁 title PLAN_{yyyyMMdd}_{HASH} 是兩件事，不得把雜湊 title 直接當 H1）；至少包含：

# <英文系統名稱> <中文系統名稱> 計畫

## 目標

## 背景與限制

## 範圍

## 方案

## 待確認

## TODO
- [ ] ...

已有計畫頁時保留使用者明確保留的內容；每輪只更新本 skill 管理的章節。需求不明的部分放在 ## 待確認，不得自行補完。

階段 C：逐步詢問

每輪最多問 1～3 個問題，問題必須能推進計畫內容。建議順序：

1. 計畫目標與成功標準。
2. 使用者、情境、限制條件。
3. 功能範圍與明確不做的範圍。
4. 方案拆解、資料流、外部依賴。
5. 里程碑、驗收項目、風險與待確認。

每輪回答後：

• 將回答整合進計畫頁。
• 把仍不明確的點列入 ## 待確認。
• 產出或更新 ## TODO checklist，格式依 spec-todo-list。
• 詢問使用者下一輪問題前，先完成階段 D 的 wiki 同步。
• 如果某輪資料不足，先把不確定內容放進 ## 待確認，不得自行補完再繼續問下一輪。

使用者明確表示「完成」「先到這裡」「計畫完成」時，進入階段 E；不要再追問非必要細節。

階段 D：同步 wiki

每輪同步順序固定：

1. 更新計畫頁。
2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，依 spec-wiki-contents〔新增列前先找可合併的既有列〕在本系統對應的 ## 段落修改既有列的計畫欄、附加新列，或該系統尚無段落時新增段落，確保有本計畫頁連結與摘要。
3. 再次讀回兩個頁面確認內容已更新。讀回時若回應含 content_base64，必須 base64 解碼後比對正文 Markdown 是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
4. 每輪只允許一輪同步結果對應下一輪提問；若 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 必須由工具呼叫或記憶中內容直接送出，不得先寫成本機 JSON 或 Markdown 檔。
• message 用繁體中文，例如 更新 <page title>。

若站台不支援 REST wiki 寫入端點，回報「此站台不支援不落地 wiki 寫入」並停止，不得改用 wiki git clone。

階段 E：完成收斂

輸出摘要表格：

項目	內容
Wiki repo	<owner/repo>
目錄頁	<index title>
計畫頁	<page title>
同步次數	本輪實際寫入次數
待確認	## 待確認 剩餘項目數

最後附上目錄頁與計畫頁 URL。

呼叫方式

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

助理	呼叫
Claude Code / Antigravity	/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --project Kokorone_心音
Codex	$plan-wiki --wiki-repo knowledges/Plan --project Kokorone_心音
OpenCode	描述需求（如「逐步問我計畫內容，並同步到 Gitea wiki 目錄與頁面」）自動觸發