.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準。",
   "skills": "./skills"
 }

README.md

@@ -1,7 +1,7 @@
 # jsc — 跨 AI 助理文件化 Skill 集合
 
 一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的文件化 skill 集合。
-目前內含三個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`doc-issues-analyze` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言。
+目前內含四個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`doc-issues-analyze` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言；`doc-issues-breakdown` 用於把專案／議題／文件來源拆成小功能議題並依到期日實作。
 核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
 搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
 在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:doc-docker`）。
@@ -40,7 +40,8 @@ doc/
 │   │   ├── SKILL.md
 │   │   └── scripts/
 │   ├── doc-funcs/SKILL.md   # 為 function 補齊 XML 文件
-│   └── doc-issues-analyze/SKILL.md  # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
+│   ├── doc-issues-analyze/SKILL.md  # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
+│   └── doc-issues-breakdown/SKILL.md # 讀來源 → 保存議題 → 小功能議題 → 排程實作 → PR
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
 ```
@@ -132,7 +133,7 @@ git -C ~/jsc-plugin pull
 cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/
 
 # 移除
-rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ~/.config/opencode/skills/doc-issues-analyze
+rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ~/.config/opencode/skills/doc-issues-analyze ~/.config/opencode/skills/doc-issues-breakdown
 ```
 
 > **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
@@ -190,6 +191,14 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs
 - **Codex**：`$doc-issues-analyze`，或用 `/skills` 選單
 - **OpenCode**：描述需求自動觸發
 
+### `doc-issues-breakdown`
+
+讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 `tea` 與 `GITEA_TOKEN` 並詢問使用者要用 `tea` 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都會詢問使用者描述是否有補充內容，所有議題描述最後都會依描述內容產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。所有中間成果都不落地成草稿檔，一律使用 `tea` 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-breakdown、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
+
+- **Claude Code / Antigravity**：`/jsc:doc-issues-breakdown`
+- **Codex**：`$doc-issues-breakdown`，或用 `/skills` 選單
+- **OpenCode**：描述需求自動觸發
+
 <!-- JSC-SKILLS:END -->
 
 ---

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
   "skills": "./skills/"
 }

skills/doc-issues-breakdown/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: doc-issues-breakdown
+description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-breakdown、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
+---
+
+# 分析多來源需求並保存為議題
+
+你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源並彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
+
+## 前置：輸入與工具
+
+- **輸入來源**：使用者必須選擇要讀取的來源種類，可多選且數量必須 `>= 1`：
+  - **專案編號**：Gitea project 編號或可定位 project 的 URL／識別資訊；若選取專案編號，必須只讀取該專案下開啟中的議題（含可取得的卡片／欄位／描述）；也可作為保存整理結果的目標專案。
+  - **議題編號**：Gitea issue 編號或 issue URL，可多筆。
+  - **檔案文件**：本機文件路徑，可多筆；支援 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`。
+- **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
+- **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
+
+## 第 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 貼進對話。
+
+## 第 2 步：選擇讀取來源、讀取內容並保存議題內容
+
+這是必要決策。若使用者尚未明確提供來源種類，必須先詢問要讀取哪些來源種類，並要求至少選一種：
+
+1. 專案編號。
+2. 議題編號。
+3. 檔案文件。
+
+選定後收集對應輸入：
+
+- 選「專案編號」：收集 project 編號或 project URL，並確認其 host／owner／repo／project id（若資訊不足，先詢問補齊）；後續必須只讀取該專案下開啟中的議題。
+- 選「議題編號」：收集 issue 編號或 issue URL；若只提供編號，必須確認其 host／owner／repo。
+- 選「檔案文件」：收集本機檔案路徑並確認存在；不存在的檔案先回報並請使用者修正。
+
+合併整理後一定要建立一張保存議題：
+
+- 若已提供專案編號，詢問是否使用該專案作為保存目標；使用者可改指定其他專案。
+- 若未提供專案編號，必須詢問保存用專案編號或 project URL。
+- 不得在缺少保存目標專案時繼續到對外建立議題的步驟。
+
+接著執行：
+
+1. 解析每一筆來源：
+   - 專案：解析出 `host`、`owner`、`repo`、`project id` 或可定位 project 的資訊。
+   - 議題：解析出 `host`、`owner`、`repo`、`index`（例如 `https://<host>/<owner>/<repo>/issues/<index>`）。
+   - 檔案：解析出本機絕對路徑、檔名與格式。
+2. 依第 1 步選定的工具建立每筆 Gitea 來源的存取設定：
+   - `tea`：找出對應 host 的 login，後續命令一律帶 `--login <name> --repo <owner>/<repo>`。
+   - `api`：base 為 `https://<host>/api/v1/repos/<owner>/<repo>`。
+   - 若多筆專案／議題分屬不同 host，選擇 `tea` 時必須確認每個 host 都有對應 login；選擇 `api` 時同一個 `GITEA_TOKEN` 必須可存取全部專案／議題，否則在讀取階段回報權限不足並停止。
+3. 顯示本次處理的基本資料，至少包含：
+   - 選定工具：`tea` 或 `api`。
+   - 若選 `tea`：每個 host 對應的 login 名稱；若選 `api`：顯示 `GITEA_TOKEN` 已設定，不顯示 token 內容。
+   - 讀取來源種類：專案編號／議題編號／檔案文件，至少一種。
+   - 來源專案：每筆 project 的 host、owner、repo、project id（若有）。
+   - 來源議題：每筆 issue 的 URL、host、owner、repo、index（若有）。
+   - 來源檔案：每筆檔案的路徑與格式（若有）。
+   - 保存目標專案：host、owner、repo、project id。
+   - target repositories 來源：使用者指定的 repositories 位置，或「以來源議題所在 repo／保存目標 repo 為準」。
+4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以來源議題所在 repo／保存目標 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在保存議題留言中標註需人工提供或 clone）。
+5. 依選定來源讀取內容：
+   - 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下**開啟中的議題**（若 API 有分頁必須完整分頁讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
+   - 議題：對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、以及**所有 comments**；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
+   - 檔案文件：讀取文件全文；若格式無法直接讀取，標註需人工轉換或提供純文字／Markdown。
+6. 同時盤點該 repo 既有的分類資源，供後續階段沿用：
+   - 標籤：`GET {base}/labels`（tea：`tea labels list`）
+   - 里程碑：`GET {base}/milestones`（tea：`tea milestones list`）
+   - 專案（若該 Gitea 版本有此 API）：`GET {base}/projects`；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。
+7. 把所有來源內容彙整成保存議題內容，使用 `tea` 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
+   - 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用）。
+   - 完整需求描述：整合專案、議題、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
+   - 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
+   - 保存議題分類：labels／milestone／project 掛載方式。
+   - `## TODO`：根據保存議題描述內容產生 Markdown checklist，放在描述最後。
+
+需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處保守描述並標註。
+
+## 第 3 步：拆分小功能議題
+
+將第 2 步保存到議題的內容拆分成多個小功能議題，使用 `tea` 或 Gitea API 建立／更新小功能議題或將小功能清單留言到保存議題；不得寫入本機草稿檔。每個小功能議題至少包含：
+
+- 標題：能清楚表示單一小功能交付範圍。
+- 描述：描述內容必須先詢問使用者想要包含哪些段落或資訊，至少提供可選項，例如需求背景、功能範圍、驗收條件、技術提示、測試方式、相依關係、風險與備註；依使用者選擇組成描述，不得自行固定格式。每個小功能議題建立或更新前，都必須逐一詢問使用者該議題描述是否有補充內容；使用者提供補充時，必須整合到該小功能議題描述中，若使用者明確表示沒有補充才可繼續建立或更新。描述最後必須加入 `## TODO` 區塊，根據該小功能描述內容產生 Markdown checklist。
+- 阻擋關閉：小功能議題建立後必須以可追溯方式阻擋其被直接關閉，直到驗收條件完成。可用方式包含加上既有 blocking／blocked 類標籤、在 body 中加入「關閉前檢查清單」、建立與保存議題的追溯連結，或依 Gitea 支援能力設定 issue dependency；不得使用不存在的標籤或 API，找不到支援方式時標註需人工處理。若小功能有前後相依，較先完成的前置議題必須阻擋較後完成的後置議題（前置 issue blocks 後置 issue；後置 issue is blocked by 前置 issue），不得反向設定。
+- 複雜度：依工作量、跨模組程度、風險、未知數與測試成本評估為 `S`／`M`／`L`／`XL`。
+- 到期日：根據複雜度評估 due date，預設從建立日往後推算：`S` 3 個工作天、`M` 5 個工作天、`L` 10 個工作天、`XL` 15 個工作天；若遇週末順延到下一個工作天。若小功能有相依關係，必須先排定相依順序，後置功能的到期日不得早於其前置功能的到期日，且應從最後一個前置功能的到期日之後再依自身複雜度推算。若 Gitea API 不支援 due date，寫入 issue body 並回報需人工設定。
+- 相依關係：列出與保存議題、來源議題與其他小功能議題的關聯；若有前後依賴，必須標明前置功能、後置功能、阻擋方向與到期日排程依據。
+
+決定要對照的 target repositories：使用者指定位置底下的所有專案、來源議題所在 repo，或使用者指定 repo。可研究相關專案程式碼以補充小功能議題描述，但所有分析結果必須直接保存到小功能議題描述或留言，不得建立本機草稿檔。
+
+## 第 4 步：依到期日排序並逐議題實作
+
+將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 `tea` 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。
+
+開始實作前必須逐個議題詢問使用者，至少提供該議題的標題、URL（若已建立）、到期日、相依關係、預計修改範圍與驗證方式。未取得使用者確認前，不得修改任何原始碼、不得 commit、不得 push、不得開 PR。使用者確認開始實作某一議題後，即授權在該議題範圍內自行 commit、push 工作分支並開 PR，不需要對每個 git 動作再次詢問。
+
+使用者確認某一議題後，才可對該議題執行：
+
+- 建立或切換工作分支，分支名稱應包含議題編號或小功能識別。
+- 依議題描述實作，過程中定期將進度留言到該議題；至少包含開始實作、主要變更完成、驗證結果、PR 連結。
+- 只修改該議題必要範圍；若發現需要擴大範圍或改動其他議題，先停止並詢問使用者。
+- 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
+- 完成後提交變更並推送工作分支，向 `develop` 開 PR；若遠端沒有 `develop`，改向 `master` 開 PR。不得直接 push 到 `develop` 或 `master`。
+- PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
+
+若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。