jiantw83
d472f81cd2
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
jsc-review — 程式碼審查
jsc 技能組的 review domain：基於《Refactoring》壞味道目錄的六組審查（結構與體積、可讀性與命名、耦合與設計、邏輯與壞習慣、註解規範、淺模組），套用在檔案變更完成與實作完成兩個時機。
安裝、更新、移除
Marketplace 統一為 jsc（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 jsc-review@jsc。每個指令一行：
| CLI | 安裝 | 更新 | 移除 |
|---|---|---|---|
| claude | claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-review@jsc |
claude plugin marketplace update jsc && claude plugin update jsc-review@jsc |
claude plugin uninstall jsc-review@jsc |
| codex | codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-review@jsc |
codex plugin marketplace upgrade jsc |
codex plugin remove jsc-review@jsc |
| copilot | copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-review@jsc |
copilot plugin marketplace update jsc && copilot plugin update jsc-review@jsc |
copilot plugin uninstall jsc-review@jsc |
| antigravity | git clone https://gitea.jsc.idv.tw/plugins/review.git ~/plugins/review && agy plugin install ~/plugins/review |
git -C ~/plugins/review pull && agy plugin uninstall jsc-review && agy plugin install ~/plugins/review |
agy plugin uninstall jsc-review |
| kiro | kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-review@jsc |
kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-review@jsc |
kiro-cli plugin uninstall jsc-review@jsc |
antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用
/jsc-cli:deploy。
舊入口
plugins/jsc已移除，marketplace 正本移到plugins/meta。marketplace 名稱仍是jsc（取自 marketplace.json 的name欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行claude plugin marketplace remove jsc，再依上表重新 add。
Skills 目錄
呼叫方式：Claude / Antigravity /jsc-review:{name}；Codex ${name}；Copilot / Kiro 描述需求自動觸發。
code-review
對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 檔案:行號、嚴重度、建議重構手法，修正與否由呼叫端決定。步驟 1 先把 diff 落成一份快照檔，六組讀同一份，git 只算一次，六組的結論也一致。第 2 組的註解範圍只管樣式判不出來的部分：專案代號、客戶名稱與情境相關的審查痕跡；禁止清單與允許清單的唯一來源是 references/comment-scope.md，這裡不再抄一份。樣式判得出來的項目由 jsc-hooks/hooks/comment-scope.sh 擋。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才交給 tools/merge-findings.sh 彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。
刻意移除的保護：第 2 組本來連樣式判得出來的項目也重掃一遍，所以
JSC_COMMENT_SCOPE=off或該 CLI 沒接上comment-scope.sh時，第 2 組是最後一道網。現在那道網沒有了。hook 關掉或沒接線時，議題編號、wiki 頁編號、工作包編號、commit hash 留在註解裡不會有人擋，commit 前請改跑/jsc-review:comment-cleanup。
api-doc
稽核 API 專案的 Swagger 文件：每個可能回傳的 HTTP 狀態碼都要宣告回覆類型，每個輸入與輸出都要有說明；範例只掛在純量成員上，類別型成員只留說明，範例責任往下推給它的屬性，一路遞迴到最內層的純量。集合看元素型別判斷：元素是純量就比照純量，附一份列出幾個元素的範例；元素是類別就比照類別，只留說明，遞迴改走進元素型別。控制器改完或實作完成時執行，例如由 jsc-sdlc:implement 呼叫，與 jsc-review:code-review 並列為兩關收尾稽核。先跑 tools/swagger-detect.sh 偵測，套件與掛接設定要雙重命中才算支援；只裝套件沒掛接就回報未啟用並停手，不開任何 sub agent。稽核分兩個面向，各一個 sub agent 平行執行：狀態碼一個，說明與範例連同巢狀資料模型的遞迴合成一個，同一批資料模型檔只讀一次，兩份檢核表分段列出。兩個面向都回覆才交給 tools/merge-findings.sh 彙整。原始碼的註解契約歸 jsc-review:code-review 第 5 組，這支只管 Swagger 文件屬性與範例，兩支不重複回報。回報 檔案:行號、嚴重度與建議修法，本技能不改程式碼。
comment-cleanup
清理本次變更新增或修改的註解，把文件追蹤資訊與審查流程痕跡移除，只留下程式邏輯的實質理由。使用者要求「清一下註解」、「不要留 review 痕跡」，或 commit 前發現註解夾帶流程資訊時執行。判斷準則只看 references/comment-scope.md，本技能負責清理，comment-scope.sh 負責擋，code-review 第 2 組負責指出人工判讀案例。改寫每個檔案一個 sub agent 平行跑，建置與測試留到最後統一跑一次。未明確要求時不動未變更的舊註解。
參考
| 檔案 | 用途 |
|---|---|
references/smells.md |
六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 |
references/comment-scope.md |
程式碼註解內容界線：禁止寫進註解的文件編號、審查流程痕跡、允許項目與白名單、命中時的改法 |
工具
| 檔案 | 用途 |
|---|---|
tools/swagger-detect.sh |
判斷專案有沒有真的啟用 Swagger。套件與設定雙重確認，缺一不算支援。輸出 support=、stack=、package=、config=；結束碼 0 支援、1 不支援、2 參數個數不對、路徑不存在或環境缺 grep |
tools/merge-findings.sh |
合併 code-review 六組與 api-doc 兩個面向的發現。輸入是六欄 TSV（檔案、行號、嚴重度、組別、發現名稱、說明），同一個檔案與行號的發現併成一列，再依 高 → 中 → 低 排序。結束碼 0 有發現、1 無發現、2 參數或環境錯誤、3 輸入格式錯誤 |
tools/changed-comments.sh |
列出本次變更新增或修改的註解行，供 comment-cleanup 決定清理範圍。不給參數比對工作區與 HEAD，給基準版本則比對 {base}...HEAD。輸出三欄 TSV（檔案、行號、內容）；註解樣式與非程式碼副檔名清單沿用 jsc-hooks/hooks/comment-scope.sh 的同一份。結束碼 0 有結果、1 無結果、2 參數或環境錯誤 |
相關 domain
jsc-sdlc：實作階段完成後呼叫本審查