From 9b48d164227c54dc4abc9db538b614bacec18cae Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 15:41:38 +0800 Subject: [PATCH 1/3] =?UTF-8?q?feat(implement):=20=E6=94=B6=E5=B0=BE?= =?UTF-8?q?=E6=94=B9=E6=88=90=E7=A8=8B=E5=BC=8F=E7=A2=BC=E5=AF=A9=E6=9F=A5?= =?UTF-8?q?=E8=88=87=20API=20=E6=96=87=E4=BB=B6=E7=A8=BD=E6=A0=B8=E5=85=A9?= =?UTF-8?q?=E9=97=9C=E4=B8=A6=E5=88=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：skills/implement/SKILL.md 第 10 步改寫。原本只呼叫 code-review，現在拆成 並列的兩關：10.1 程式碼審查維持原判準，10.2 新增 API 文件稽核——先跑 jsc-review/tools/swagger-detect.sh，退出碼 0 就呼叫 jsc-review:api-doc，1 就 明確跳過並回報，2 就修好參數或路徑重跑。技能的 description 同步改寫。 Why：支援 Swagger 的專案，控制器文件沒補全就等於工作包沒做完。兩關並列而不是 一關套一關，是因為程式碼審查過了不代表 API 文件補齊了，反過來也一樣，任何一關 沒過工作包都不算完成。跳過一定要講出來：沒回報的跳過跟忘記做分不出來。退出碼 2 是偵測不出結果，既不算通過也不算跳過，硬當跳過會讓真的支援 Swagger 的專案 漏掉稽核。 How：改寫刻意只動第 10 步內部，用 10.1、10.2 子項編號，1 到 14 的頂層編號一個 都不動——references/deliver-formats.md 指的「步驟 7」、references/branch.md 指的 「步驟 4 與步驟 11」都還指得到原來的位置。稽核項目不抄一份過來，只寫「看 jsc-review:api-doc」，判準改動時不必兩邊同步。兩關的失敗都是修，不是放行：每一 輪修正都以 sub agent 在同一個 worktree 內進行，修完再稽核一次。 Who：jsc-sdlc 的 implement 技能，工作包的收尾稽核。 --- skills/implement/SKILL.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 593d320..9854895 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding), then confirm the analysis page's source branch - it is both the worktree base and the PR target. Every already-open work package's PR comments get triaged via tools/wp-gate.sh check and fixed by sub agents only after jsc-ask consensus, never blocking an unrelated package; picking a candidate is gated per-candidate in code by tools/wp-gate.sh check-deps, and claiming it records the package number via tools/wp-gate.sh claim so tools/wp-gate.sh owns keeps every session on its own package's PR. Claim a ready work package from ANALYZE_CONTENTS with a work ticket, confirm a delivery package's content type, then complete its TDD todos one at a time inside a worktree built from origin/{source-branch}, updating the wiki after every item, closing with jsc-review code-review, one PR back to the source branch, a jsc-gitea pr-watch.sh poll that holds until that PR merges, a jsc-log:worklog entry per finished task, the chosen delivery document, an optional MAINTAIN_CONTENTS entry, and a tools/stage-report.sh report covering the model tag verdict, the worklog link, every wiki link written, the worktree and the three branches. Use when analysis is done and code must be written; not for planning or analysis. +description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding), then confirm the analysis page's source branch - it is both the worktree base and the PR target. Every already-open work package's PR comments get triaged via tools/wp-gate.sh check and fixed by sub agents only after jsc-ask consensus, never blocking an unrelated package; picking a candidate is gated per-candidate in code by tools/wp-gate.sh check-deps, and claiming it records the package number via tools/wp-gate.sh claim so tools/wp-gate.sh owns keeps every session on its own package's PR. Claim a ready work package from ANALYZE_CONTENTS with a work ticket, confirm a delivery package's content type, then complete its TDD todos one at a time inside a worktree built from origin/{source-branch}, updating the wiki after every item, closing with the two side-by-side audits jsc-review code-review and jsc-review api-doc (the latter gated by swagger-detect.sh and explicitly skipped where the project has no Swagger support), one PR back to the source branch, a jsc-gitea pr-watch.sh poll that holds until that PR merges, a jsc-log:worklog entry per finished task, the chosen delivery document, an optional MAINTAIN_CONTENTS entry, and a tools/stage-report.sh report covering the model tag verdict, the worklog link, every wiki link written, the worktree and the three branches. Use when analysis is done and code must be written; not for planning or analysis. --- # implement @@ -46,7 +46,14 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 2. The main agent keeps only the wiki bookkeeping: when the sub agent reports the item done, flip its `[ ]` to `[x]` on the analysis page and save to the wiki. 3. **A code comment states why the code is written this way; it never states where the work is documented.** The tracking numbers this stage always holds — the work package number, the analysis page number, the TDD todo number, the source branch name and the PR number — stay out of every code comment; write the reason itself into the comment instead. Full list and the allowed exceptions: `jsc-review/references/comment-scope.md`. `jsc-hooks/hooks/comment-scope.sh` compares each file after it is written and prints a warning; fix the flagged line at once, then carry on with the same item. Completion condition: the item's own diff holds no comment line carrying any of those numbers, and every warning the hook printed for this item is fixed. 4. Completion condition: every item of the package shows `[x]` on the saved analysis page, and each save happened before the next item's sub agent started. -10. When all items are done, sweep the work package's whole diff for the comment rule of step 9.3, then call `jsc-review:code-review` and wait for the verdict. Each round of fixes **MUST run as a sub agent** inside the same worktree. Completion condition: the review passes, and the diff handed to it holds no comment line carrying the work package number, the analysis page number, a TDD todo number, the source branch name or a PR number (full list: `jsc-review/references/comment-scope.md`). +10. **Two closing audits, side by side — a work package is finished only when both of them clear. Neither replaces the other**: + 1. **Code review** — when all items are done, sweep the work package's whole diff for the comment rule of step 9.3, then call `jsc-review:code-review` and wait for the verdict. Each round of fixes **MUST run as a sub agent** inside the same worktree. Completion condition: the review passes, and the diff handed to it holds no comment line carrying the work package number, the analysis page number, a TDD todo number, the source branch name or a PR number (full list: `jsc-review/references/comment-scope.md`). + 2. **API document audit — on a project that supports Swagger, the work package stays unfinished until its controller files are fully documented.** Whether the project supports Swagger is decided in code by `jsc-review/tools/swagger-detect.sh {worktree path}`; run it and branch on its exit code instead of judging the project yourself: + - `0` — the project supports Swagger. Call `jsc-review:api-doc` over the work package's changed controller files and wait for its verdict. What that audit checks belongs to `jsc-review:api-doc`; read the items there and keep no copy of them here. + - `1` — the project does not support Swagger. **Skip this audit explicitly and report the skip.** A reported skip is a pass, never a failure. + - `2` — bad arguments or a bad path. Fix them and run the script again; an undecidable detection is neither a pass nor a skip. + A failing verdict is fixed, never waived: each round of fixes **MUST run as a sub agent** inside the same worktree, and `jsc-review:api-doc` runs again over the fixed files until it passes. + Completion condition: `swagger-detect.sh` has run for this worktree and its exit code is reported, and either `jsc-review:api-doc` returned a passing verdict, or the skip is reported together with the exit code that caused it. 11. **One work package finished → commit, push, PR back to the source branch, then hold on that PR until it merges**: 1. Call `jsc-git:pr` from inside the worktree, **passing `{source-branch}` as the base branch**. One package, one PR; the branch ladder and how the base is derived are in `references/branch.md`. 2. Write the PR URL and number into that work package's PR column on the analysis page and save it back to the wiki, so the next run of this skill can find it (step 4). -- 2.53.0 From 981cda6adf9ec63b1c9af4653131cb762a1755c4 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 15:41:38 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(sdlc):=20README=20=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=E5=85=A9=E9=97=9C=E6=94=B6=E5=B0=BE=E7=A8=BD=E6=A0=B8=E8=88=87?= =?UTF-8?q?=20jsc-review=20=E7=9A=84=E5=88=86=E5=B7=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：README.md 的 implement 摘要，把原本一句「程式碼審查」換成兩關並列的收尾 稽核，寫明偵測、呼叫、跳過三條路徑與各自的退出碼；相關 domain 一節的 jsc-review 說明同步改成兩關，並註明專案支不支援 Swagger 由 swagger-detect.sh 判定、稽核 項目只寫在該技能。 Why：README 是使用者查一支技能做什麼的入口。技能正文改了流程，README 還停在 只有程式碼審查那版，讀的人會以為 API 文件稽核不存在，或以為那是另一支技能自己 的事。 How：只改 implement 摘要那一段的收尾環節，以及相關 domain 的那一行，其餘流程 敘述維持原樣。稽核項目在這裡一樣不重複列，指向 jsc-review:api-doc，避免同一份 判準散在三個檔案裡。 Who：jsc-sdlc 的存取庫說明文件。 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a23ed9..8b42c73 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `implement` -實作：先確認來源分支（同時是 PR 目標）→ 領包前先跑 `tools/wp-gate.sh check` 把每個已開 PR 但沒合併的工作包留言逐筆印出，動手前先跑 `tools/wp-gate.sh owns` 確認那支 PR 是自己這一包的，再依 `jsc-ask:ask` 決策樹與使用者對每一則留言達成共識才修（以 sub agent 回原 worktree、推同一條工作分支，不開第二個 PR），**這一步只結清舊 PR 的留言，不擋別的工作包**——修不動或純討論的留言忽略但要在回報裡列出，處理過的時間戳寫回分析頁**既有**的 PR 欄位當下一輪的 `--since` → 產生工作證鎖定「未完成、無工作證」的候選工作包（交付工作包優先），**每個候選都跑 `tools/wp-gate.sh check-deps` 判斷能不能挑**：活查它在分析頁上的相依工作包是否都已合併，只有相依於它的包才會被一支未合併的 PR 擋住，跟它無關的工作包可以平行進行 → 領到包立刻跑 `tools/wp-gate.sh claim` 記下歸屬 → 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{wp-number}/{repo}`，一個工作包一個 worktree，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR），接著 `tools/wp-gate.sh lock --wp` 上鎖並登記 PR 歸屬 → **用 `jsc-gitea/tools/pr-watch.sh` 盯到合併**（預設 60 秒輪詢、不自動退場；退出碼 `0` 已合併或關閉、`10` 有新留言就回頭跑同一套留言修正、`3` 查不到該 PR、`2` 參數或環境有問題），合併後解鎖並移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄 → 階段回報（`tools/stage-report.sh`，多報工作目錄與來源、工作、目標三條分支）。**每完成一個任務就寫一筆工作日誌**（`jsc-log:worklog`）：一個工作包、一輪 PR 留言修正、一個獨立的修正提交各算一個任務，不等到階段結束才補一次；`stage-report.sh --pending-file` 暫存的內容併進同一次寫入，寫入成功才清除。寫程式碼時註解只寫「為什麼這樣寫」，工作包編號、分析頁編號、待辦編號、分支名、PR 編號一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 +實作：先確認來源分支（同時是 PR 目標）→ 領包前先跑 `tools/wp-gate.sh check` 把每個已開 PR 但沒合併的工作包留言逐筆印出，動手前先跑 `tools/wp-gate.sh owns` 確認那支 PR 是自己這一包的，再依 `jsc-ask:ask` 決策樹與使用者對每一則留言達成共識才修（以 sub agent 回原 worktree、推同一條工作分支，不開第二個 PR），**這一步只結清舊 PR 的留言，不擋別的工作包**——修不動或純討論的留言忽略但要在回報裡列出，處理過的時間戳寫回分析頁**既有**的 PR 欄位當下一輪的 `--since` → 產生工作證鎖定「未完成、無工作證」的候選工作包（交付工作包優先），**每個候選都跑 `tools/wp-gate.sh check-deps` 判斷能不能挑**：活查它在分析頁上的相依工作包是否都已合併，只有相依於它的包才會被一支未合併的 PR 擋住，跟它無關的工作包可以平行進行 → 領到包立刻跑 `tools/wp-gate.sh claim` 記下歸屬 → 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{wp-number}/{repo}`，一個工作包一個 worktree，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → **收尾稽核兩關並列，兩關都過才算工作包完成**：一關是 `jsc-review:code-review` 程式碼審查，另一關是 API 文件稽核——先跑 `jsc-review/tools/swagger-detect.sh` 判定專案支不支援 Swagger（退出碼 `0` 支援、`1` 不支援、`2` 參數或路徑有錯），支援才呼叫 `jsc-review:api-doc` 把控制器文件補到過關（沒過就以 sub agent 修完再稽核一次），不支援就**明確跳過並回報**，跳過算通過 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR），接著 `tools/wp-gate.sh lock --wp` 上鎖並登記 PR 歸屬 → **用 `jsc-gitea/tools/pr-watch.sh` 盯到合併**（預設 60 秒輪詢、不自動退場；退出碼 `0` 已合併或關閉、`10` 有新留言就回頭跑同一套留言修正、`3` 查不到該 PR、`2` 參數或環境有問題），合併後解鎖並移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄 → 階段回報（`tools/stage-report.sh`，多報工作目錄與來源、工作、目標三條分支）。**每完成一個任務就寫一筆工作日誌**（`jsc-log:worklog`）：一個工作包、一輪 PR 留言修正、一個獨立的修正提交各算一個任務，不等到階段結束才補一次；`stage-report.sh --pending-file` 暫存的內容併進同一次寫入，寫入成功才清除。寫程式碼時註解只寫「為什麼這樣寫」，工作包編號、分析頁編號、待辦編號、分支名、PR 編號一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 ### `maintain` @@ -76,6 +76,6 @@ HASH 規則：`{owner}/{repo}` 的共用 wiki hash 一律由 `jsc-gitea/tools/ha - [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：模型能力標籤與階段閘門判定（`tools/model-tags.sh`、`references/model-tags.md`、`jsc-cli:models`）、偏好模型鏈（`tools/model-config.sh`） - [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：sdlc-gate 階段模型鎖定 - [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫、實作階段等 PR 合併的輪詢（`tools/pr-watch.sh`） -- [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review)：實作完成後的程式碼審查 +- [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review)：實作完成後並列的兩關收尾稽核——程式碼審查（`jsc-review:code-review`）、API 文件稽核（`jsc-review:api-doc`，專案支不支援 Swagger 由 `tools/swagger-detect.sh` 判定，稽核項目也只寫在該技能） - [`jsc-git`](https://gitea.jsc.idv.tw/plugins/git) / [`jsc-pkg`](https://gitea.jsc.idv.tw/plugins/pkg)：維護階段的 commit / PR 與套件更新 - [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：工作日誌，每完成一個任務就寫一筆 -- 2.53.0 From 39c087b31f33cf5187945c68670c61e1efd4e925 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 15:41:38 +0800 Subject: [PATCH 3/3] =?UTF-8?q?chore(manifest):=20=E4=B8=89=E4=BB=BD=20man?= =?UTF-8?q?ifest=20=E5=90=8C=E6=AD=A5=E5=8D=87=E7=89=88=E8=87=B3=200.2.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份 manifest 的 version 由 0.1.9 改為 0.2.0。 Why：implement 的收尾多了一關 API 文件稽核，是使用者看得到的流程異動，次版號 要跟著進。版本沒跟著升，各 CLI 端的外掛版本護欄就分不出新舊，已安裝的使用者 也收不到更新。 How：三份 manifest 只改 version 欄位，其餘欄位維持原樣，三處版本號保持一致。 Who：jsc-sdlc 外掛的安裝與更新流程。 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2dc38ff..3d4fcb8 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.9", + "version": "0.2.0", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 55cc3b5..b7a53c6 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.9", + "version": "0.2.0", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 3f881f7..3eb5f68 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.9", + "version": "0.2.0", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills/" } -- 2.53.0