diff --git a/skills/doc-funcs/SKILL.md b/skills/doc-funcs/SKILL.md index d42a2db..1e9b7ca 100644 --- a/skills/doc-funcs/SKILL.md +++ b/skills/doc-funcs/SKILL.md @@ -7,6 +7,14 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ 你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README。請依下列階段依序完成。 +## 共用規範（generic plugin，必要前置） + +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： + +- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、subagent 提示需帶入本規範。 +- `/jsc:spec-execution`：不臆測／需人工確認、不擴及無關檔案（generated/bin/obj/.git/.docs 與第三方依賴）。 +- `/jsc:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、輸出訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 + ## 第 0 步：先判斷語言與生態 在產生任何草稿之前，必須先判斷目標 repo 的主要程式語言與生態，後續所有草稿的註解格式都以此為準： @@ -101,12 +109,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ - workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md`**，保留 workflow 實際設定不變，僅整理成說明文件。 - 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。 - 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。 -- 輸出訊息格式：若該 function 或指令檔有輸出訊息（例如 log、console 輸出、echo、回傳給使用者的提示訊息），訊息格式必須統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`。其中 `階段` 為選填，沿用該訊息所屬區塊的原始名稱並保留原文不翻譯；若無對應階段則移除整個 `[階段]` 區塊。`等級` 必須是 `INF`/`WRN`/`ERR`/`TRC`/`DBG` 其中之一；`時間` 使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`。調整輸出訊息格式僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。 -- 區塊內 log 的階段命名：若被調整格式的 log 被包在某個有名稱的區塊內，必須將該區塊名稱作為該 log 的 `階段` 名稱（沿用原始名稱、保留原文不翻譯），套用完成後移除標示該區塊的包裹／標題本身（僅移除標記與包裹，保留區塊內原有的指令與行為）。有名稱的區塊包含但不限於： - - 原始碼：`#region 名稱`/`#endregion`、或其他帶名稱的包裹結構。 - - 指令檔：以「印出分隔線＋區塊標題＋分隔線」這種橫幅（banner）方式宣告的段落（例如先 echo `====`、再 echo 區塊名稱、再 echo `----`）。此時橫幅顯示的標題即為該段所有 log 的 `階段` 名稱，且必須移除這幾行印出橫幅的輸出指令，改成把 `階段` 名稱併進該段每一行訊息的前綴。 -- 例外：指令檔開頭「用途／更新日期」的檔案說明標頭（含其外框分隔線）屬於檔案標頭、不是階段區塊，必須原樣保留，不可被移除或轉成 `階段` 前綴。 -- 一行一則訊息：每一則輸出訊息（原始碼或指令檔皆適用）都必須是獨立的單行輸出指令，一則訊息對應一行；不得用任何區塊（例如多行字串、字串拼接累積成一坨、迴圈外層包住整段訊息的結構）把多則訊息包成一個輸出。原本被包成一坨輸出的多則訊息，必須拆成逐行、逐則的輸出，且每則仍套用上述統一訊息格式。 +- 輸出訊息格式：依 `/jsc:spec-time-log` — 若該 function 或指令檔有輸出訊息，統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱不翻譯；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；時間 Asia/Taipei）；區塊階段命名（`#region`／橫幅段落名稱作為 `階段` 前綴並移除包裹／橫幅本身、僅移除標記保留指令與行為）、檔案標頭保留例外、一行一則規則皆依該 spec。調整僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。 ## 第 7 步：實作註解後，保守優化效能並僅修正有誤的排版 @@ -169,6 +172,6 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。 - 排版一律依照檔案原本的排版方式；只有排版確實有誤（縮排錯亂、tab／空白混用致錯、對齊錯誤造成誤讀、編碼／行尾異常）才修正該處，不得全檔重排、不得套用 formatter 改變原有風格。 - 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。 -- function 或指令檔若有輸出訊息，訊息格式必須統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱並保留原文不翻譯；無對應階段時移除該區塊；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。若該 log 被包在有名稱的區塊內（含指令檔以分隔線＋標題＋分隔線宣告的橫幅段落），須將區塊名稱當作 `階段` 名稱後移除該包裹／橫幅，且僅移除包裹、保留區塊內原有指令與行為；但開頭用途/更新日期標頭不算階段區塊，必須保留。每則訊息必須一行一則、各自為獨立的單行輸出指令，不得用區塊或字串拼接把多則訊息包成一坨輸出。 +- function 或指令檔若有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留與一行一則規則一律依 `/jsc:spec-time-log`，且不得藉此改變訊息反映的實際行為。 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。 -- 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。 +- 原始碼註解與 README 的語言依 `/jsc:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。 diff --git a/skills/doc-issues-analyze-to-file/SKILL.md b/skills/doc-issues-analyze-to-file/SKILL.md index 79f7c08..7712b69 100644 --- a/skills/doc-issues-analyze-to-file/SKILL.md +++ b/skills/doc-issues-analyze-to-file/SKILL.md @@ -7,15 +7,23 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite 你要讀取使用者提供的一或多筆 Gitea issue，彙整成完整需求文件，依功能拆成多個實作階段（每階段建立一個 issue），配合指定的 repositories 產生實作草稿，最後產出交付文件並依 issues 分組留言。**建立 issue 與留言屬於對外且不易復原的動作，必須先讓使用者確認過草稿再執行**。所有需求彙整、階段拆分與實作草稿一律先產生草稿檔，再詢問使用者是否實際建立 issue / 留言。請依下列階段依序完成。 +## 共用規範（generic plugin，必要前置） + +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： + +- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 +- `/jsc:spec-execution`：不臆測／需人工確認、不擴及無關檔案。 +- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（`Authorization: token`、分頁完整讀取）。 + ## 前置：輸入與工具 - **輸入**：至少一筆 issue URL（可多筆）。可另外指定「repositories 位置」（本機含多個專案的資料夾）；若未指定，實作草稿以各 issue 所在的 repository 為準。 - **工具優先序**： 1. 若該 issue host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment` 等），並以 `--login --repo /` 指定目標。 2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定）。 -- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。 +- **不要依賴 `jq`**：依 `/jsc:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 - **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze-to-file/`。 -- **議題描述流程圖**：產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，若有助於理解，盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把該階段的處理流程、狀態轉移或與其他階段的相依關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。 +- **議題描述流程圖**：依 `/jsc:spec-output` — 產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，有助理解就加入 Mermaid 流程圖（處理流程、狀態轉移、階段相依關係），忠實反映需求與拆分結果、不得杜撰。 ## 第 0 步：解析 issue URL 與準備工具 @@ -122,7 +130,5 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite - 建立 issue 與留言是對外且不易復原的動作，**必須先經第 6 步使用者確認**；未確認前只產生本機草稿。 - 新 issue 一律沿用來源 issue 的里程碑與專案；標籤只從既有標籤中依需求性質挑選，不自行新建（除非使用者要求）。 - subagent 與各步驟只讀程式碼與 issue、只寫 `.docs/` 草稿，**不得修改任何原始碼**；本 skill 的產出是需求文件、階段 issue、實作草稿與交付留言，不含改動程式邏輯。 -- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。 +- JSON 解析（不依賴 `jq`）依 `/jsc:spec-gitea`；個資保護（PII）與語言規範依 `/jsc:spec-output`。 - 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。 -- 留言與交付文件不得洩漏個資（PII）；若 issue 內容含個資，於文件與留言中僅保留必要資訊或去識別化。 -- 文件、留言與草稿以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。 diff --git a/skills/doc-issues-analyze/SKILL.md b/skills/doc-issues-analyze/SKILL.md index 868684b..00a0a68 100644 --- a/skills/doc-issues-analyze/SKILL.md +++ b/skills/doc-issues-analyze/SKILL.md @@ -7,6 +7,15 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。 +## 共用規範（generic plugin，必要前置） + +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： + +- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、表格／Mermaid 呈現、個資（PII）去識別化。 +- `/jsc:spec-execution`：不臆測／需人工確認、已知資訊跳過詢問。 +- `/jsc:spec-gitea`：tea／API 工具選擇與檢查、`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 分頁完整讀取。 +- `/jsc:spec-project-board`：看板欄位語意對應、GET 探測（404／501 不支援）、不往回移、不得新建欄位。 + ## 絕對準則（不可違反） - **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、實作進度、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有兩個：（1）使用者確認實作某議題後、在該議題範圍內對**目標 repository 原始碼**進行的正常程式修改與 git commit；（2）為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。 @@ -19,8 +28,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 - **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。 - **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。 - **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。 -- **工具選擇**：在解析與讀取 Gitea 來源前，先檢查本機是否可用 `tea`、`tea login list` 是否有對應 login、以及環境變數 `GITEA_TOKEN` 是否已設定；接著詢問使用者要使用 `tea` 或 Gitea REST API + `curl` + token。使用者已明確指定工具時才可跳過詢問。 -- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。 +- **工具選擇**：依 `/jsc:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。 - **議題必須連同留言與附件一起讀取**：處理任何議題（含專案底下展開的議題）時，除了 `title`／`body` 等欄位，必須一併讀取**所有留言（comments）**與**所有附件（attachments/assets，含議題本身與各留言的附件）**，其內容都是需求分析的依據： - 附件清單：`tea` 目前沒有附件指令，一律走 API — 議題附件 `GET {base}/repos/{owner}/{repo}/issues/{index}/assets`、留言附件 `GET {base}/repos/{owner}/{repo}/issues/comments/{id}/assets`，取得每個附件的檔名、類型與下載 URL。 - 文字類附件（Markdown、純文字、CSV、JSON 等）：以 `curl` 直接取得內容到對話中分析，不落地。 @@ -28,19 +36,11 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 - 無法讀取的格式（或僅有 `tea` 而無 token 可下載附件）：在保存議題內容中列出附件檔名與 URL 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容。 - **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。 - **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。 -- **議題描述流程圖**：產生保存議題或小功能議題的描述時，若有助於理解，盡量在描述中加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把需求流程、狀態轉移或議題間的相依／阻擋關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。 +- **議題描述流程圖**：依 `/jsc:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。 ## 第 1 步：工具可用性檢查與使用方式選擇 -先檢查可用工具並選擇後續使用方式。除非使用者已明確指定 `tea` 或 `api`，否則不得自行決定。 - -1. 檢查 `tea` 是否存在：`command -v tea`。 -2. 若 `tea` 存在，執行 `tea login list`，記錄可用 login 與其 host；若失敗，記錄失敗原因但不要中止。 -3. 檢查 `GITEA_TOKEN` 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容。 -4. 依檢查結果詢問使用者要使用哪一種方式： - - `tea`：只有在 `tea` 可執行時才可選；後續解析來源後仍需確認來源 host 有對應 login。 - - `api`：只有在 `GITEA_TOKEN` 已設定時才可選；後續使用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`。 -5. 若兩種方式都不可用，停止並回報缺少 `tea login` 或 `GITEA_TOKEN`；不要要求使用者把 token 貼進對話。 +依 `/jsc:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`，失敗記錄原因不中止）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 詢問使用者要用 `tea` 或 `api`（除非使用者已明確指定，不得自行決定；選 `tea` 後續仍需確認來源 host 有對應 login）→ 兩種方式都不可用則停止並回報缺少 `tea login` 或 `GITEA_TOKEN`（不要要求使用者把 token 貼進對話）。 ## 第 2 步：選擇讀取來源、讀取內容並保存議題內容 @@ -125,10 +125,8 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 **分析完成後：把議題移到看板「待處理」欄位**。保存議題與所有小功能議題都建立／更新完成後（即分析階段結束），對其中**確實屬於某個專案看板（project board）**的議題調整進度欄位： -- 若看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，語意相近即可對應，不得假設看板一定有這五欄），把議題移動到「待處理」欄位，代表需求分析已完成、等待實作。 -- **不往回移**：議題已在「待處理」或更後面的欄位（進行中／待測試／已完成）時維持原欄位，只有在「分析中」或未指定欄位時才移動。 -- 移動前先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測端點是否存在（404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。 -- 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳；不得新建欄位。 +- 依 `/jsc:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。 +- 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳。 ## 第 4 步：依到期日排序並逐議題實作 diff --git a/skills/doc-issues-sync/SKILL.md b/skills/doc-issues-sync/SKILL.md index ddecee3..6c3daf2 100644 --- a/skills/doc-issues-sync/SKILL.md +++ b/skills/doc-issues-sync/SKILL.md @@ -7,6 +7,15 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t 你要讀取使用者提供的一個 Gitea **專案（project）**或**單一議題**，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。例外：輸入為專案且使用者指定「關閉專案／專案完成」時，進入**專案完成模式**（見第 1 步之後的專節），跳過標籤分組與逐議題勾稽，改為批次搬移至「已完成」並關閉議題。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只回傳同步計畫（不落地任何檔案），實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。 +## 共用規範（generic plugin，必要前置） + +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： + +- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 +- `/jsc:spec-execution`：不臆測／需人工確認。 +- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。 +- `/jsc:spec-project-board`：看板欄位語意對應與建議欄位規則、404／501 視為不支援、不得新建欄位。 + ## 絕對準則（不可違反） - **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（議題清單、需求分析、追加後的正文、標籤異動、勾稽結果、留言內容）一律留在**對話內容**與 **subagent 的回傳值**裡。最終產物只透過 `tea` 或 Gitea API **寫回議題正文／標籤／留言**，除此之外不產生任何本機檔案。 @@ -18,10 +27,10 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t - **工具優先序**： 1. 若該 host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment`、`tea labels` 等），並以 `--login --repo /` 指定目標。 2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。 -- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。 +- **不要依賴 `jq`**：依 `/jsc:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。 -- **專案進度欄位（project column）**：若議題屬於某個專案看板（project board），且看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，不得假設看板一定有這五欄），本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整；對應規則見第 3.5 步。欄位語意對不上或介面不支援時不移動，只回報建議。 -- **議題描述流程圖**：若要補進議題正文或進度留言的內容有助於理解（例如需求流程、TODO 之間的先後／相依），盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）以視覺化呈現；流程圖必須忠實反映議題需求與 TODO 現況，不得杜撰未提及的流程。 +- **專案進度欄位（project column）**：依 `/jsc:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。 +- **議題描述流程圖**：依 `/jsc:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。 ## 第 0 步：解析輸入、判斷專案或議題、準備工具 @@ -81,12 +90,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t 3. **3.2 依需求更新可用標籤**：依議題需求性質，從該 repo **既有標籤**中挑選應掛上（或應移除）的標籤，回傳內容中列出「建議的標籤異動」（新增哪些、移除哪些、維持哪些）。**不自行新建標籤**，除非使用者要求；找不到合適標籤就維持原樣並標註。 4. **3.3 逐條勾稽未完成 TODO 是否已完成**：對所有**未完成**的 TODO（含 3.1 新增的），逐條依工作目錄下的檔案內容判斷是否已完成。已完成者標記為 `- [x]` 並在回傳內容記下判斷依據（以 `path:line` 指出對應實作位置）；無法從檔案可靠判斷者維持未完成並標註「需人工確認」。 5. **3.4 整理 TODO 異動留言**：若本議題有任何 TODO 異動（**新增**的 TODO，或**狀態變更**——由未完成改為完成），整理成一則留言內容，包含：本次新增了哪些 TODO、哪些 TODO 判定為完成（附對應實作位置）、哪些仍未完成（含原因／需人工確認）。若沒有任何 TODO 異動，回傳標明「無異動、不需留言」。 -6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則（欄位名稱以看板實際名稱為準，語意相近即可對應）： - - 需求仍不明確、TODO 明顯不足以追蹤需求而需大量補列 → 「分析中」。 - - 需求與 TODO 齊全，但工作目錄中尚無任何對應實作 → 「待處理」。 - - 部分 TODO 已勾稽為完成（已有部分實作）→ 「進行中」。 - - 所有 TODO 勾稽為已完成，但仍有「需人工確認」項目或尚待驗證 → 「待測試」。 - - 所有 TODO 已完成且無需人工確認 → 「已完成」。 +6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。 回傳內容需含：目前欄位、建議欄位、判斷依據。建議欄位與目前欄位相同時標明「欄位無異動」；看板欄位語意對不上（或取不到欄位資訊）時標明「無法對應、維持原欄位」並列出實際欄位名稱，不得硬套。議題不屬於任何專案看板時跳過本項。 每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、專案進度欄位建議（目前欄位／建議欄位／判斷依據，或「不屬於專案看板」「無法對應」）、以及所有「需人工確認」項目。 @@ -123,11 +127,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t - 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。 - **標籤異動**：套用建議的新增／移除。 - tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。 -- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，把議題移到建議欄位。 - - 先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測對應端點是否存在（回 404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。 - - 介面可用 → 呼叫對應端點把議題移至建議欄位，一次一個議題並確認回應成功。 - - 介面不可用 → 不視為錯誤：跳過移動，改在第 7 步回報中列出「議題 → 建議欄位」清單，請使用者到看板手動拖曳。 - - 只在建議欄位確實存在於看板且語意對應明確時移動；有疑慮就不動並回報。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。 +- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。 - **留言**：對有 TODO 異動的議題張貼留言。 - tea：`tea comment --repo / --login "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。 - 無異動的議題不留言。 @@ -146,8 +146,6 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t - 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。 - subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、不得修改任何工作目錄原始碼**。 - 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。 -- 進度欄位調整只在議題確實屬於專案看板、建議欄位存在於看板且語意對應明確、並經第 5 步使用者確認後執行；不得新建欄位、不得對未確認存在的 API 端點做寫入。介面不支援時只回報建議清單，不視為錯誤。 +- 進度欄位調整依 `/jsc:spec-project-board`，且必須經第 5 步使用者確認後執行。 - 專案完成模式只在輸入為專案且使用者**明確**指定關閉／完成時進入；語意不明就用 AskUserQuestion 確認，不得自行認定。批次關閉議題前必須經使用者確認；含未完成 TODO 的議題要在確認時明確標出。不得透過此模式關閉不屬於該專案的議題。 -- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。 -- 留言與回傳內容不得洩漏個資（PII）；若議題內容含個資，於回傳內容與留言中僅保留必要資訊或去識別化。 -- 回傳內容與留言以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。 +- JSON 解析（不依賴 `jq`）依 `/jsc:spec-gitea`；個資保護（PII）與語言規範依 `/jsc:spec-output`。