diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index fdad75e..2353fbf 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.6", + "version": "0.1.7", "description": "JSC 跨 AI 助理共用規範 skills plugin(Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot CLI),`skills/` 為唯一真實來源,並提供整組 plugin 的安裝/更新/移除管理(plugins-install 一次安裝或更新 jsc-code/jsc-doc/jsc-persona/jsc-shared,plugins-uninstall 一次移除四個 JSC plugin)。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準,不依賴既有本機存取庫;所有 skills 以 SKILL.md 為共通標準;於 Claude Code 以 /jsc-shared: 前綴呼叫。", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 50d1e24..1ba7951 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.6", + "version": "0.1.7", "description": "JSC 跨 AI 助理共用規範 skills plugin,`skills/` 為唯一真實來源,並提供整組 plugin 的安裝/更新/移除管理(plugins-install 一次安裝或更新 jsc-code/jsc-doc/jsc-persona/jsc-shared,plugins-uninstall 一次移除四個 JSC plugin)。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準,不依賴既有本機存取庫;所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index a9b1066..cc0e863 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.6", + "version": "0.1.7", "description": "JSC 跨 AI 助理共用規範 skills plugin,`skills/` 為唯一真實來源,並提供整組 plugin 的安裝/更新/移除管理(plugins-install 一次安裝或更新 jsc-code/jsc-doc/jsc-persona/jsc-shared,plugins-uninstall 一次移除四個 JSC plugin)。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準,不依賴既有本機存取庫;所有 skills 以 SKILL.md 為共通標準;於 Antigravity 以 /jsc-shared: 前綴呼叫。", "skills": "./skills" } diff --git a/plugin.meta.json b/plugin.meta.json index e478071..b7d733e 100644 --- a/plugin.meta.json +++ b/plugin.meta.json @@ -1,7 +1,7 @@ { "name": "jsc-shared", "shortName": "shared", - "version": "0.1.6", + "version": "0.1.7", "descriptionCore": "JSC 跨 AI 助理共用規範 skills plugin,`skills/` 為唯一真實來源,並提供整組 plugin 的安裝/更新/移除管理(plugins-install 一次安裝或更新 jsc-code/jsc-doc/jsc-persona/jsc-shared,plugins-uninstall 一次移除四個 JSC plugin)。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準,不依賴既有本機存取庫;所有 skills 以 SKILL.md 為共通標準。", "assistants": ["Claude Code", "Codex", "Antigravity", "OpenCode", "GitHub Copilot CLI"], "cliPrefix": "/jsc-shared:", diff --git a/skills/spec-todo-list/SKILL.md b/skills/spec-todo-list/SKILL.md index c5801a7..66b28b5 100644 --- a/skills/spec-todo-list/SKILL.md +++ b/skills/spec-todo-list/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-todo-list -description: JSC plugins 共用「TODO list 規範」:一律用 Markdown checklist(`- [ ]`)格式、每項要具體到可執行可驗收、不得憑空編造需求外的項目、依影響範圍由小到大排序、每項要能舉證對應到 `path:line` 或議題描述的哪一句、完成一項就勾選並附上 Asia/Taipei 時間戳並留言回報進度。當其他 skill 內文引用 spec-todo-list 或 /jsc-shared:spec-todo-list、或需要產生/追蹤議題(或文件)TODO list 時載入此 skill。單獨被使用者呼叫時,直接說明本規範內容。 +description: JSC plugins 共用「TODO list 規範」:一律用 Markdown checklist(`- [ ]`)格式、每項要具體到可執行可驗收、必要時補上實作方式與建議修改內容、不得憑空編造需求外的項目、依影響範圍由小到大排序、每項要能舉證對應到 `path:line` 或議題描述的哪一句、完成一項就勾選並附上 Asia/Taipei 時間戳並留言回報進度。當其他 skill 內文引用 spec-todo-list 或 /jsc-shared:spec-todo-list、或需要產生/追蹤議題(或文件)TODO list 時載入此 skill。單獨被使用者呼叫時,直接說明本規範內容。 --- # spec-todo-list — 共用 TODO list 規範 @@ -19,6 +19,8 @@ description: JSC plugins 共用「TODO list 規範」:一律用 Markdown check - 每一項 TODO 都必須具體到**看到這一句就知道要做什麼、做完後能明確判斷是否達成**;不得使用「優化一下」「檢查看看」「處理相關問題」這類模糊、無驗收標準的措辭。 - 動詞+對象+(必要時)驗收條件三者盡量齊備,例如「把 `UserService.Login` 的密碼驗證改為使用雪湯 hash 比對,單元測試涵蓋密碼錯誤與帳號鎖定兩種情境」,而非「改善登入安全性」。 - 一項 TODO 只對應一件可獨立完成、可獨立驗收的工作;範圍過大時拆成多項,不得把整個議題塞成一項。 +- 若 TODO 用於實作或修正文件/程式,建議直接補上「實作方式」與「建議修改內容」,讓執行者不必回頭猜測改法。 +- 供實作型 TODO 使用時,建議格式可寫成 `- [ ] **編號 短標題**:具體內容;實作方式:...;驗收條件:...;來源依據:...;建議修改內容:...`;若確實沒有明確修改方向,`建議修改內容` 可省略,但 `實作方式` 不可省略。 ## 禁止憑空編造 diff --git a/skills/todo-wiki/SKILL.md b/skills/todo-wiki/SKILL.md index 682ac69..2a3ba98 100644 --- a/skills/todo-wiki/SKILL.md +++ b/skills/todo-wiki/SKILL.md @@ -1,7 +1,7 @@ --- 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 CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO--] [--append|--overwrite] [--yes]" +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 CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO-->] [--append|--overwrite] [--yes]" --- # todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki @@ -29,13 +29,14 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode - **不落地絕對規則**:不得建立或更新本機 `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` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。 -- 必須詢問使用者兩個獨立決策:是否關聯到計畫/系統名稱,以及是否更新 wiki 目錄頁;使用者回答不加入計畫時,仍預設更新 wiki 目錄頁,除非使用者另行明確說不要更新目錄頁。 +- 必須詢問使用者三個獨立決策:是否關聯到計畫/系統名稱、是否把新的代辦加入既有的 todo 內,以及是否更新 wiki 目錄頁;使用者回答不加入計畫時,仍預設更新 wiki 目錄頁,除非使用者另行明確說不要更新目錄頁。 - 需要加入目錄頁時,目錄標題使用 `{關聯計畫的系統名稱}-代辦`,並連結到 TODO 頁。系統名稱優先從關聯計畫取得;若沒有關聯計畫,從需求內容尋找或產生系統名稱。 - 目錄頁禁止整頁覆蓋:不存在時才新建;存在時必須保留既有內容,只修改本 TODO 既有列或在既有表格附加新列。 @@ -50,7 +51,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode | `--wiki-repo` | 指定要同步的 Gitea wiki repo,例如 `knowledges/Plan`。 | | `--wiki-index` | wiki 目錄頁 title;未帶時固定使用 `CONTENTS`,不詢問。 | | `--wiki-project` | 關聯計畫或系統名稱;預設仍會更新目錄頁,只有使用者明確表示不要更新目錄頁時才可略過。 | -| `--wiki-page` | todo 頁 title;未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`,不詢問。 | +| `--wiki-page` | todo 頁 title;可指向既有 todo 頁 title,未帶時先詢問是否加入既有 todo,只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 | | `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一,同時提供視為衝突,仍需詢問使用者。 | | `--yes` | 略過一般性確認;不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫/系統名稱、是否更新 wiki 目錄頁,或對外寫入目標不明等必要決策。 | @@ -118,16 +119,16 @@ scope: <階段 2 產出的 scope> ### checklist - 逐項使用 `- [ ] **編號 短標題**:具體內容`。 -- 內容需動詞+對象+驗收條件齊備,並能舉證對應 `path:line` 或需求彙整中的哪一句。 +- 內容需動詞+對象+實作方式+驗收條件+來源依據齊備,並能舉證對應 `path:line` 或需求彙整中的哪一句;文件或程式修改時,必要時附上 `建議修改內容`。 - 依影響範圍由小到大排序;範圍相同時前置依賴排前面。 - 不得加入需求來源未提及、也無法合理推得的項目;有疑慮者標「需人工確認」。 ## 階段 5:讀取既有 wiki 頁並決定寫入策略 1. 依 `spec-gitea` 決定 host 與 token,不輸出 token。 -2. 確認 `--wiki-repo`;缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`,`--wiki-page` 未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`。 -3. 詢問使用者兩個獨立決策:是否關聯到計畫/系統名稱,以及是否更新 wiki 目錄頁。使用者回答不加入計畫時,仍預設會更新目錄頁;只有使用者明確回答不要更新目錄頁,才可記錄為「不更新目錄頁」。 -4. 分頁讀取 `GET /repos///wiki/pages`,以 title 查表取得 todo 頁 `sub_url`;若目錄頁更新決策為開啟,也取得目錄頁 `sub_url`。目錄頁不存在時才建立;目錄頁存在時必須讀取原內容並保留,不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 +2. 確認 `--wiki-repo`;缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`,`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內;只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 +3. 詢問使用者三個獨立決策:是否關聯到計畫/系統名稱、是否把新的代辦加入既有的 todo 內,以及是否更新 wiki 目錄頁。使用者回答不加入計畫時,仍預設會更新目錄頁;只有使用者明確回答不要更新目錄頁,才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁,該頁就是本次寫入目標,不得自行改成新頁。 +4. 分頁讀取 `GET /repos///wiki/pages`,以 title 查表取得 todo 頁 `sub_url`;若使用者選擇既有 todo 頁,直接以該頁 title 對應 `sub_url`;若目錄頁更新決策為開啟,也取得目錄頁 `sub_url`。目錄頁不存在時才建立;目錄頁存在時必須讀取原內容並保留,不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 5. 讀取既有 todo 頁;若不存在,策略為「建立」。 6. 既有 todo 頁存在時解析 frontmatter: @@ -138,7 +139,7 @@ scope: <階段 2 產出的 scope> | 頁面存在且 frontmatter `model` 不同 | 停下來詢問使用者是否覆蓋、沿用舊模型附加、或取消;未得同意不得寫入。 | | 頁面存在但沒有 frontmatter | 視為不同模型處理。 | -`--append`/`--overwrite` 已明確回答不同模型分支時,依該旗標執行;`--yes` 不算回答。 +`--append`/`--overwrite` 已明確回答不同模型分支時,依該旗標執行;`--yes` 不算回答。若使用者選擇既有 todo 頁,仍要沿用這個 frontmatter 模型判斷與寫回驗證流程,不得因為是既有頁就跳過。 ## 階段 6:同步 Gitea wiki