From 6447416c7ba852b69d09943483386235e172207e Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:16 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs(guidelines):=20=E6=BA=96=E5=89=87?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=20SKILLSET=20=E9=A0=81=E5=9E=8B=E3=80=81?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E5=BE=8C=E9=87=8D=E5=95=9F=E9=96=98=E9=96=80?= =?UTF-8?q?=E8=88=87=E6=B5=81=E7=A8=8B=E6=AA=A2=E6=9F=A5=E5=9B=9B=E9=A0=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`references/guidelines.md` 四處增修。環境變數表新增 `JSC_WIKI_REPO_SKILLSET` 與 `JSC_RESTART_GATE` 兩列；wiki 頁命名總表新增 `SKILLSET` 一列，並補上雜湊來源為被改動的 domain 存取庫 `{owner}/{repo}`、頁內累積歷次異動兩段說明；新增「部署後重啟閘門」一節，用表寫下狀態檔、清除時機、判定位置與逃生門，另附九支豁免技能的表與「清單認的是技能名，不是呼叫鏈」一段；審核檢查清單末尾新增流程檢查四項。 Why：這批規則要落到四個 domain 的腳本與技能裡，準則是它們的唯一真實來源。規則只留在各自的實作裡，改一邊忘一邊，稽核就沒有對照標準。三件事各有各的理由：`SKILLSET` 頁型讓技能組每次異動留下查得到的驗證紀錄；重啟閘門補上「部署換掉的是磁碟上的技能檔，工作階段載入的還是舊版」這段落差；流程檢查四項把過去踩過的坑寫成逐項確認得出來的項目。 How：閘門那一節刻意把每一支的「為什麼不能擋」逐支寫出來，不只列技能名——豁免清單日後要增刪，理由沒寫下來就得重新想一次。九支的理由收斂成同一件事：部署後還要寫得完技能組異動報告與工作日誌，整批擋下去「先重啟」與「先寫完報告」會互相打死，通則另外寫進流程檢查第 4 項「閘門不自鎖」。「清單認技能名不認呼叫鏈」單獨寫一段，因為後三支（`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`）自己不是收尾規則的主體，是為了讓前六支走得完才補進來的，日後增豁免時要一併想它會呼叫誰。流程檢查其中兩項附上踩過的實例，抽象敘述判不出來的，看實例就判得出來。 Who：`jsc-meta` 的技能準則，以及依準則稽核的 `skill-check` 與四支技能組異動技能。 --- references/guidelines.md | 44 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/references/guidelines.md b/references/guidelines.md index 2b16800..571df73 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -86,9 +86,11 @@ | `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | | `JSC_WIKI_REPO_CHECK` | `CHECK_CONTENTS`、`CHECK_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | | `JSC_WIKI_REPO_REPORT` | `REPORT_CONTENTS`、`REPORT_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_CONTENTS`、`SKILLSET_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 | | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` | | `JSC_PR_WATCH_INTERVAL` | `jsc-gitea/tools/pr-watch.sh` 輪詢 PR 狀態的間隔秒數 | 預設 60 | +| `JSC_RESTART_GATE` | 部署後重啟閘門的開關，`off` 關閉整道閘門 | 閘門開啟 | 頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時，才退回 `JSC_WIKI_REPO`。不得跨類型代用。 @@ -120,6 +122,37 @@ 沒有 pre-tool hook 的 CLI 接不上這道檢查，`hooks-install` 要據實回報，不得暗示每個 CLI 都有保護。 +## 部署後重啟閘門 + +部署換掉的是磁碟上的技能檔，目前工作階段載入的還是舊版。這段落差期間跑技能，改動看起來沒生效，人會以為部署失敗又重跑一次。 + +| 項目 | 規則 | +| --- | --- | +| 狀態檔 | `$JSC_HOME/restart-required`，由 `jsc-cli:deploy` 收尾寫入 | +| 清除時機 | 重啟 CLI 之後由 `jsc-hooks` 清除，不必手動刪 | +| 狀態檔存在時 | 擋下 jsc 技能呼叫，印出「請先重啟 CLI」與狀態檔路徑 | +| 狀態檔不存在時 | 全部放行 | +| 判定位置 | 程式層，由 `jsc-hooks` 執行，不靠技能內文自我約束 | +| 逃生門 | `JSC_RESTART_GATE=off` | + +**豁免清單**（狀態檔存在也放行）： + +| 技能 | 為什麼不能擋 | +| --- | --- | +| `jsc-cli:deploy` | 部署本身的入口。擋了就沒有方法重跑部署，形成死鎖 | +| `jsc-hooks:hooks-install` | 部署後要重新接線，擋了會讓部署做一半卡住 | +| `jsc-gitea:wiki` | 寫 `SKILLSET_{HASH}` 異動報告與工作日誌的唯一路徑 | +| `jsc-log:worklog` | 部署後還要結清工作日誌 | +| `jsc-log:learn` | 部署後還要記這次的教訓 | +| `jsc-meta:*` | 開發技能組本身的工具，擋了就修不了技能組 | +| `jsc-ask:ask` | 上面幾支都要問使用者。擋了 `deploy` 連 install 或 update 都問不出來 | +| `jsc-git:pr` | 報告與異動的收尾要開 PR，擋了收尾做不完 | +| `jsc-git:commit` | 同上，`pr` 的第一步就是它 | + +豁免這幾支的理由是同一件事：`jsc-meta` 四支異動技能的收尾要求把驗證結果寫進 `SKILLSET_{HASH}`，還要結清工作日誌，而這條路徑必經 `jsc-gitea:wiki` 與 `jsc-log`。全擋的話，部署一跑完就沒有路徑寫完報告，重啟閘門與報告要求互相打死。閘門不自鎖的通則見「審核檢查清單」的流程檢查第 4 項。 + +**清單認的是技能名，不是呼叫鏈。** 豁免技能轉呼叫的下一層若不在清單上，那一層照樣會被擋。後三支（`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`）自己不是收尾規則的主體，是為了讓前六支走得完才補進來的。`version-guard.sh` 的豁免清單當年也是為同一個原因收進 `jsc-ask:ask`。新增豁免技能時要一併想它會呼叫誰。 + ## Wiki 頁命名總表 所有 wiki 頁面一律採雙層命名： @@ -137,6 +170,7 @@ | `ERROR` | `ERROR_CONTENTS` | `ERROR_{HASH}` | 異常目錄、異常頁 | jsc-hooks | | `CHECK` | `CHECK_CONTENTS` | `CHECK_{HASH}` | 體檢目錄、執行環境體檢頁 | jsc-cli | | `REPORT` | `REPORT_CONTENTS` | `REPORT_{HASH}` | 報表目錄、工作報表頁（年、月、週、日各一頁） | jsc-log | +| `SKILLSET` | `SKILLSET_CONTENTS` | `SKILLSET_{HASH}` | 技能組異動目錄、技能組異動報告頁（新增、更新、刪除、批次更新之後的驗證結果與改動清單） | jsc-meta | `{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的 SHA-1 前 8 碼，大寫。 若第一碼是 `0-9`、`A`、`B`、`C`，就改成 `H` 加上原 SHA-1 前 7 碼，總長仍維持 8 碼。 @@ -145,6 +179,9 @@ `REPORT` 用得到那個主題字串：雜湊來源為 `{owner}/{repo}/{期間}`，期間是 `daily`、`weekly`、`monthly`、`yearly` 其中之一。 年、月、週、日各自一頁，每頁內依期間累積分節。 +`SKILLSET` 的雜湊來源就是被改動的 domain 存取庫 `{owner}/{repo}`，算法同上，由同一支 `jsc-gitea/tools/hash-id` 產生。 +頁內**累積**歷次異動：每次異動附加一節，不覆蓋舊紀錄。要看一支技能改過幾次，就在同一頁上翻。 + `CHECK` 是唯一例外：它記的是一台執行環境，不是一個存取庫，所以雜湊來源為 `{主機名}/{登入帳號}`。 8 碼與 `H` 前綴的算法完全相同，由同一支 `jsc-gitea/tools/hash-id` 產生。 在沒有存取庫的目錄也跑得出體檢，是這個例外存在的原因。 @@ -164,3 +201,10 @@ - [ ] 所有非程式碼輸出（程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件）為繁體中文、UTF-8、無亂碼、無簡體字，且 `tools/ste100-lint.sh` 對該 domain 全綠 - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version - [ ] PR 的 base 符合「PR 分支階梯」，沒有越級 + +流程檢查四項，對照技能自己的流程逐項確認： + +- [ ] 技能內外引用的步驟編號、檔案路徑、節標題都真的存在，指標指得到。踩過的實例：規則搬到 `references/` 後指標指向空處，照著指過去只看到空白 +- [ ] 每個步驟以可檢核的完成條件結尾，沒有「理解後」「適當地」這類模糊語 +- [ ] 每個外部呼叫（腳本、API、其他技能）的失敗情況都有明寫怎麼辦，退出碼都有分流 +- [ ] 技能自己裝的閘門不會擋掉解除那道閘門的唯一路徑（閘門不自鎖）。踩過的實例：工作包閘門若擋掉 `implement`，結清 PR 就沒有路徑 From 9a0ea8e248eaa4bb6da0c44777d0aa0ba11acbf7 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:16 +0800 Subject: [PATCH 2/4] =?UTF-8?q?feat(skill-check):=20=E7=A8=BD=E6=A0=B8?= =?UTF-8?q?=E5=8A=A0=E5=85=A5=20marketplace=20=E5=90=8C=E6=AD=A5=E5=BF=85?= =?UTF-8?q?=E7=B6=93=E6=AD=A5=E9=A9=9F=E8=88=87=E6=B5=81=E7=A8=8B=E6=AA=A2?= =?UTF-8?q?=E6=9F=A5=E5=9B=9B=E9=A0=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`skills/skill-check/SKILL.md` 兩處增修。第 2 步的稽核範圍明寫要逐項涵蓋準則的流程檢查四項，四項各列一條，完成條件改成「每個 domain 的稽核結果對所有清單項目都有結論，含這四項」；新增第 5 步「同步 marketplace 正本」，四個結束碼各自寫明怎麼處理，原本的複查與開 PR 順延為第 6、7 步。 Why：`sync-marketplace.sh` 原本沒有出現在任何技能流程裡，跑不跑全憑人記得。正本在 `plugins/meta`，每個 domain 存取庫各留一份位元組完全相同的副本，稽核改完不同步，就會有存取庫註冊到過期的 plugin 清單。流程檢查四項同理：準則加了項目，稽核不點名就沒有人會查，四項等於沒加。 How：同步列為必經步驟，不是選項。呼叫時拿既有項目自己現在的值重寫一次，重寫同一筆是冪等的，所以不必先判斷哪一筆該改。四個結束碼逐一分流：3 是寫好了但有 domain 沒 clone 到本機，先跑 `sync-domains.sh` 再重跑；2 是參數個數不對；1 是缺 python3、正本讀不到或副本位元組不一致；0 才代表每份副本完全相同，而且是腳本自己驗過的。 Who：`jsc-meta:skill-check` 的例行合規稽核流程。 --- skills/skill-check/SKILL.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/skills/skill-check/SKILL.md b/skills/skill-check/SKILL.md index 086ab8a..1c1cce9 100644 --- a/skills/skill-check/SKILL.md +++ b/skills/skill-check/SKILL.md @@ -10,8 +10,21 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references ## Flow 1. Run `tools/sync-domains.sh` to sync every domain repo of the Gitea canonical marketplace. Completion condition: the script exits 0 and prints one `domainpath` line per marketplace domain — exit 0 is the only code that means every repo is present and current. Exit 3 means some repos were not updated: reconcile every path named on stderr (commit or stash the dirty tree, or fix the failing pull) and rerun; when the user confirms a dirty tree is intentional local work, record that decision and continue on the local version — never read exit 3 as current. Exit 2 means a domain could not be cloned and exit 1 means the canonical marketplace was unreadable — resolve either before continuing. -2. Audit every skill of every domain against the guidelines.md audit checklist — this step MUST run as a sub agent, one sub agent per domain repo. Each sub agent reports its findings: skill, failed checklist item, evidence (file:line), proposed fix. Completion condition: every domain has an audit result. +2. Audit every skill of every domain against the guidelines.md audit checklist — this step MUST run as a sub agent, one sub agent per domain repo. Each sub agent reports its findings: skill, failed checklist item, evidence (file:line), proposed fix. Cover the checklist's four flow checks by name, not only the naming and language items: + 1. Every step number, file path and section title the skill references — inside itself and in other files — really exists (the pointer points at something). + 2. Every step ends in a checkable completion condition, with no vague wording. + 3. Every external call (script, API, other skill) states what to do on failure and routes every exit code. + 4. No gate the skill installs blocks the only path that lifts that gate. + + Completion condition: every domain has an audit result that names a verdict for all checklist items, the four flow checks included. 3. Present each failed item via the `jsc-ask:ask` decision tree (apply the proposed fix / skip / custom fix). Every option states its impact scope (example: skipping leaves the skill non-compliant until the next audit). Completion condition: every finding has a recorded decision. 4. Apply the confirmed fixes — the fix-application part MUST run as a sub agent, one sub agent per affected domain repo: modify the files per the confirmed fix. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) for each affected domain repo to refresh that domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: every affected repo carries the fixes and the manifest bump. -5. Re-check the guidelines.md audit checklist for every touched skill. On any failure, **return to step 3**: confirm and fix again, until all items pass. Completion condition: all checklist items pass. -6. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL. +5. Sync the canonical marketplace — a **required** step, never optional. The canonical pair lives in `plugins/meta` and every domain repo carries a byte-identical copy, so a fix that leaves the copies apart makes some repos register a stale plugin set. Run `tools/sync-marketplace.sh {domain} {repo-url} {description}` once with an existing entry's own current values (rewriting the same entry is idempotent); the script rewrites both canonical files and copies them into every domain repo. Route each exit code: + - Exit 3 — written, but some domain repo is not present locally. Run `tools/sync-domains.sh`, then rerun this step. + - Exit 2 — usage error: the script takes exactly three arguments. Fix them and rerun. + - Exit 1 — missing python3, an unreadable canonical file, or a byte mismatch between copies. Read stderr, fix the named cause (install python3 for the first), then rerun. + - Exit 0 — every copy holds identical bytes; the script verifies that itself. + + Completion condition: the script exits 0 and prints the touched paths. +6. Re-check the guidelines.md audit checklist for every touched skill. On any failure, **return to step 3**: confirm and fix again, until all items pass. Completion condition: all checklist items pass. +7. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL. From 478f670d53486dced619e712f7d51091bd6095a1 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:16 +0800 Subject: [PATCH 3/4] =?UTF-8?q?feat(skillset-report):=20=E5=9B=9B=E6=94=AF?= =?UTF-8?q?=E7=95=B0=E5=8B=95=E6=8A=80=E8=83=BD=E6=94=B6=E5=B0=BE=E5=A5=97?= =?UTF-8?q?=E7=94=A8=E5=88=B0=E5=B7=A5=E4=BD=9C=E9=9A=8E=E6=AE=B5=E3=80=81?= =?UTF-8?q?=E9=A9=97=E8=AD=89=E4=B8=A6=E5=AF=AB=E7=95=B0=E5=8B=95=E5=A0=B1?= =?UTF-8?q?=E5=91=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`skill-new`、`skill-update`、`skill-delete`、`skillset-update` 四支各新增一個收尾步驟，內含三個子步驟：把改動套用到目前工作階段、逐項驗證功能真的動得起來、把驗證結果附加到 wiki 的 `SKILLSET_{HASH}`。四支的 `description` 同步補上這段收尾。 Why：原本四支都以「開了 PR」作為收尾。PR 開完技能還沒進到任何 CLI，改動到底動不動得起來沒人驗過，壞了要等下一次有人踩到才知道。技能組的異動紀錄也一樣沒有落腳處：同一支技能改過幾次、每次改了什麼，只能翻 git 紀錄。 How：套用那一步分兩條路徑，依改動走到哪裡決定。PR 已經合併到 `master` 才走 `jsc-cli:deploy` 更新模式，並依提示重新啟動；PR 還停在 `develop` 或還在等審核，就改用工作樹驗證，報告標成「工作樹驗證、尚未部署」，並點名還沒合併的發佈 PR。分兩條路徑的理由是完成條件達不到：marketplace 與 `version-guard.sh` 都讀存取庫的預設分支，停在 `develop` 的改動 `deploy` 一定看不到，硬跑就卡在永遠達不到的完成條件上。驗證那一步要求逐項比對結束碼與實際輸出，不接受「跑完沒報錯」；對不上就回到套用那一步重跑，不往下走。報告一律附加一節、不覆蓋舊節，要看一支技能改過幾次就在同一頁上翻；寫不進去就把頁名與未寫入的內容交回使用者，這一步留著不結案。 Who：`jsc-meta` 的四支技能組異動技能，以及日後查技能組異動紀錄的人。 --- skills/skill-delete/SKILL.md | 8 +++++++- skills/skill-new/SKILL.md | 8 +++++++- skills/skill-update/SKILL.md | 8 +++++++- skills/skillset-update/SKILL.md | 8 +++++++- 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/skills/skill-delete/SKILL.md b/skills/skill-delete/SKILL.md index 1b8ece7..47ec08d 100644 --- a/skills/skill-delete/SKILL.md +++ b/skills/skill-delete/SKILL.md @@ -1,6 +1,6 @@ --- name: skill-delete -description: Remove a skill from the jsc skill set safely. Pick the skill from the Gitea canonical marketplace skill list, inventory every file referencing it, fix each affected file through decision-tree questions until guideline checks pass, delete the skill and verify no on-disk leftover in any CLI, then open a PR via jsc-git pr. Use only for removal; not for renaming (use skill-update). +description: Remove a skill from the jsc skill set safely. Pick the skill from the Gitea canonical marketplace skill list, inventory every file referencing it, fix each affected file through decision-tree questions until guideline checks pass, delete the skill and verify no on-disk leftover in any CLI, open a PR via jsc-git pr, then deploy the deletion into the current session and append the change report to wiki SKILLSET_{HASH}. Use only for removal; not for renaming (use skill-update). --- # skill-delete — delete a skill @@ -28,3 +28,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references Completion condition: the script exits 0, or exit 3 is reported to the user and recorded in the PR. 8. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back. +9. Apply the deletion to the current working session, verify it took, then report: + 1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read the repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`: + - The PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the version without the skill, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the deletion as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints `jsc-{domain}` at the version the three manifests now carry. + - The PR is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run the next sub-step against `/root/plugins/{domain}` rather than the installed copy, mark the report as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the deletion reaches any CLI. Until it merges the skill is still installed and still callable, so say that too. Completion condition: the verification sub-step passed against the worktree and the outstanding release PR is named in the report. + 2. Verify the function concretely: run `tools/list-skills.sh` and confirm no row carries the deleted `{domain}/{name}`, rerun `tools/verify-skill-removed.sh {domain} {name}` for exit 0, then run every tool and skill that step 5 fixed and confirm each still finishes with its documented exit code — a fix that broke a caller shows up here, not earlier. On any mismatch — the deleted skill still listed, a leftover from exit 1, a fixed caller that now fails — fix the cause and rerun this step from 9.1. Completion condition: the skill is absent from the list, the verification script exits 0 (or its exit 3 stays reported as「無處可查」), and every fixed caller ran. + 3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent. Call `jsc-gitea:wiki`; `{HASH}` comes from the `{owner}/{repo}` of the domain repo that lost the skill, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「刪除」, skill name, changed files (the step 5 inventory verdicts included), PR URL, the step 9.2 verification result per item — and keep every earlier section. Add the page to `SKILLSET_CONTENTS` when it is new. When the write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links it. diff --git a/skills/skill-new/SKILL.md b/skills/skill-new/SKILL.md index d52f7d4..de370af 100644 --- a/skills/skill-new/SKILL.md +++ b/skills/skill-new/SKILL.md @@ -1,6 +1,6 @@ --- name: skill-new -description: Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), then open a PR via jsc-git pr. Use when the user wants to add a skill; not for editing an existing one (use skill-update). +description: Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), open a PR via jsc-git pr, then deploy the skill into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use when the user wants to add a skill; not for editing an existing one (use skill-update). --- # skill-new — create a skill @@ -34,3 +34,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) to sync the domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: `skills/{name}/SKILL.md` exists, the README lists the skill, and all three manifests show the same new version. 4. Self-check every item of the guidelines.md audit checklist; fix anything that fails. Completion condition: every checklist item passes. 5. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back. +6. Apply the new skill to the current working session, verify it works, then report: + 1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read the repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`: + - The PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the new version, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints `jsc-{domain}` at the version the three manifests now carry. + - The PR is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run step 6.2 against `/root/plugins/{domain}` rather than the installed copy, mark the report in 6.3 as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: step 6.2 passed against the worktree and the outstanding release PR is named in the report. + 2. Verify the function concretely: run `tools/list-skills.sh` and see the `{domain}{name}` row for the new skill, then run every tool the skill added with real arguments and compare each exit code against its documented meaning. Invoke `/jsc-{domain}:{name}` once and confirm the CLI loads the SKILL.md body instead of reporting an unknown command. On any mismatch — a missing row, an exit code the tool's own documentation does not describe, an unknown command — fix the cause and rerun this step from 6.1. Completion condition: the row is printed, every added tool ran with an expected exit code, and the command loaded. + 3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent. Call `jsc-gitea:wiki`; `{HASH}` comes from the `{owner}/{repo}` of the domain repo that gained the skill, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「新增」, skill name, changed files, PR URL, the step 6.2 verification result per item — and keep every earlier section. Add the page to `SKILLSET_CONTENTS` when it is new. When the write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links it. diff --git a/skills/skill-update/SKILL.md b/skills/skill-update/SKILL.md index dcd453b..990cb66 100644 --- a/skills/skill-update/SKILL.md +++ b/skills/skill-update/SKILL.md @@ -1,6 +1,6 @@ --- name: skill-update -description: Update one existing skill in the jsc skill set. List all skills from the Gitea canonical marketplace (cloning any missing domain repo) and let the user pick one, ask update details via decision tree, apply the change, then re-check against the guidelines checklist until it passes and open a PR via jsc-git pr. Use for modifying a single skill; not for creating (skill-new), not for removing (skill-delete), and not for a change spanning several skills or domains (skillset-update). +description: Update one existing skill in the jsc skill set. List all skills from the Gitea canonical marketplace (cloning any missing domain repo) and let the user pick one, ask update details via decision tree, apply the change, re-check against the guidelines checklist until it passes, open a PR via jsc-git pr, then deploy the change into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use for modifying a single skill; not for creating (skill-new), not for removing (skill-delete), and not for a change spanning several skills or domains (skillset-update). --- # skill-update — update a skill @@ -16,3 +16,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references 5. Update the skill — the modification part MUST run as a sub agent: modify SKILL.md and related files. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) to sync the domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: the skill files carry the change and all three manifests show the same new version. 6. Check every item of the guidelines.md audit checklist. On any failure, **return to step 4**: ask again and fix, until all items pass. Completion condition: every checklist item passes. 7. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back. +8. Apply the update to the current working session, verify it works, then report: + 1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read the repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`: + - The PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the new version, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints `jsc-{domain}` at the version the three manifests now carry. + - The PR is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run the next sub-step against `/root/plugins/{domain}` rather than the installed copy, mark the report as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: the verification sub-step passed against the worktree and the outstanding release PR is named in the report. + 2. Verify the function concretely: run `tools/list-skills.sh` and see the updated `description` in the skill's row, then run every tool this change touched with real arguments and compare each exit code against its documented meaning. Invoke `/jsc-{domain}:{name}` once and confirm the CLI loads the changed SKILL.md body. On any mismatch — a stale row, an exit code the tool's own documentation does not describe, an unchanged body — fix the cause and rerun this step from 8.1. Completion condition: the row shows the new description, every touched tool ran with an expected exit code, and the command loaded. + 3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent. Call `jsc-gitea:wiki`; `{HASH}` comes from the `{owner}/{repo}` of the changed domain repo, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「更新」, skill name, changed files, PR URL, the step 8.2 verification result per item — and keep every earlier section. Add the page to `SKILLSET_CONTENTS` when it is new. When the write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links it. diff --git a/skills/skillset-update/SKILL.md b/skills/skillset-update/SKILL.md index c077fca..cc7f7e4 100644 --- a/skills/skillset-update/SKILL.md +++ b/skills/skillset-update/SKILL.md @@ -1,6 +1,6 @@ --- name: skillset-update -description: Apply one change request across the whole jsc skill set — multiple skills in multiple domains in one pass. Ask the change details via decision tree, sync every domain repo from the Gitea canonical marketplace, apply the change per affected domain via sub agents, re-check against the guidelines checklist until it passes, then open a PR per affected repo via jsc-git pr. Use when a change spans multiple skills or domains; not for a single skill (use skill-update). +description: Apply one change request across the whole jsc skill set — multiple skills in multiple domains in one pass. Ask the change details via decision tree, sync every domain repo from the Gitea canonical marketplace, apply the change per affected domain via sub agents, re-check against the guidelines checklist until it passes, open a PR per affected repo via jsc-git pr, then deploy the change into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use when a change spans multiple skills or domains; not for a single skill (use skill-update). --- # skillset-update — apply one change across the skill set @@ -14,3 +14,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references 3. Apply the change to every affected skill — the modification part MUST run as a sub agent, one sub agent per affected domain repo: modify SKILL.md and related files and tools. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) for each affected domain repo to sync that domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: every affected domain repo carries the change, the README sync, and the manifest bump. 4. Check every item of the guidelines.md audit checklist for each touched skill. On any failure, **return to step 1**: ask again and fix, until all items pass. Completion condition: every checklist item passes for every touched skill. 5. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL. +6. Apply the batch change to the current working session, verify it works, then report: + 1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read each repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`: + - Every affected repo's PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the new version of **every** affected plugin, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new versions and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints every affected `jsc-{domain}` at the version its three manifests now carry. + - Any affected repo is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run the next sub-step against each `/root/plugins/{domain}` rather than the installed copies, mark the report as 「工作樹驗證、尚未部署」, and list every release PR that still has to merge before the change reaches any CLI. A change spanning several repos reaches the CLIs only when the last of them merges, so name them all. Completion condition: the verification sub-step passed against every affected worktree and every outstanding release PR is named in the report. + 2. Verify the function concretely: run `tools/list-skills.sh` and check the row of every touched skill against the change, then run every tool this change touched with real arguments and compare each exit code against its documented meaning. Invoke one touched skill per affected domain as `/jsc-{domain}:{name}` and confirm the CLI loads the changed SKILL.md body. On any mismatch — a stale row, an exit code the tool's own documentation does not describe, an unchanged body — fix the cause and rerun this step from 6.1. Completion condition: every touched skill's row matches the change, every touched tool ran with an expected exit code, and one command per affected domain loaded. + 3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent, one sub agent per affected domain repo. Call `jsc-gitea:wiki`; `{HASH}` comes from that repo's `{owner}/{repo}`, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「批次更新」, the change request in one line, touched skills, changed files, PR URL, the step 6.2 verification result per item — and keep every earlier section. Add each page to `SKILLSET_CONTENTS` when it is new. When a write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: every affected repo's page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links them all. From 816fe07fbd54fc3b5aa31defeec38ef4d486e56c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:16 +0800 Subject: [PATCH 4/4] =?UTF-8?q?chore(manifest):=20=E4=B8=89=E4=BB=BD=20man?= =?UTF-8?q?ifest=20=E7=89=88=E6=9C=AC=E5=8D=87=E5=88=B0=200.1.4?= 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` 的 `version` 由 0.1.3 改為 0.1.4。 Why：本次準則新增 `SKILLSET` 頁型、部署後重啟閘門與流程檢查四項，`skill-check` 多了 marketplace 同步必經步驟，四支異動技能也多了收尾步驟，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。 How：三份只改 `version` 一個欄位，其餘內容不動，三份保持同一版號。 Who：`jsc-meta` 外掛的套件描述檔。 --- .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 45e72bb..7f196f5 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.1.3", + "version": "0.1.4", "description": "技能組自我管理：新建、更新、刪除技能與技能準則", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 9a376d2..01fe5c9 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.1.3", + "version": "0.1.4", "description": "技能組自我管理：新建、更新、刪除技能與技能準則", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 4a9af5b..a116ffb 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.1.3", + "version": "0.1.4", "description": "技能組自我管理：新建、更新、刪除技能與技能準則", "skills": "./skills/" }