diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 63a70bd..5051549 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.0.2", + "version": "0.0.3", "description": "技能組自我管理：新建/更新/刪除技能與技能準則", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index f047617..acb9818 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.0.2", + "version": "0.0.3", "description": "技能組自我管理：新建/更新/刪除技能與技能準則", "skills": "./skills" } diff --git a/README.md b/README.md index 8fa49ad..182f2da 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 ### `skillset-update` -批次更新——把一份變更需求套用到整個技能組的多個技能／domain，逐 repo 開 PR；單一技能改用 skill-update。 +批次更新——把一份變更需求套用到整個技能組的多個技能／domain，先檢查工具化、sub agent 與環境變數優先規則，再逐 repo 開 PR；單一技能改用 skill-update。 + +### `skill-check` + +例行稽核——沒有變更需求時，把整個技能組逐一對照準則的審核檢查清單：sub agent 逐 domain 稽核 → 不符項目逐項決策樹確認 → sub agent 套用修正並複檢 → 逐 repo 開 PR。有變更需求改用 skillset-update。 ### `ste100-sync` diff --git a/plugin.json b/plugin.json index dd61698..9eb42fa 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.0.2", + "version": "0.0.3", "description": "技能組自我管理：新建/更新/刪除技能與技能準則", "skills": "./skills/" } diff --git a/references/guidelines.md b/references/guidelines.md index 9b9b8ae..0bff4f5 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -59,27 +59,35 @@ | --- | --- | --- | | `GITEA_HOST` | Gitea 站台（例：`https://gitea.jsc.idv.tw`） | 詢問使用者 | | `GITEA_TOKEN` | Gitea API token | 改用 tea 登入金鑰（`tea login list`）；tea 也沒有才詢問使用者 | -| `JSC_WIKI_REPO_{TYPE}` | 各類型 wiki 頁所在的 `{owner}/{repo}`；TYPE = `QUESTION` / `PLAN` / `ANALYZE` / `MAINTAIN` / `REPO` / `LOG` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_QUESTION` | `QUESTION_CONTENTS`、`QUESTION_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_PLAN` | `PLAN_CONTENTS`、`PLAN_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_ANALYZE` | `ANALYZE_CONTENTS`、`ANALYZE_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_MAINTAIN` | `MAINTAIN_CONTENTS`、`MAINTAIN_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_REPO` | `REPO_CONTENTS`、`REPO_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_LOG` | `LOG_CONTENTS`、`LOG_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 | | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` | +頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時，才退回 `JSC_WIKI_REPO`。不得跨類型代用。 + ## Wiki 頁命名總表 -| 頁面 | 用途 | 擁有者 | -| --- | --- | --- | -| `QUESTION_CONTENTS` | 問詢目錄（存取庫名稱 → 問詢紀錄） | jsc-ask | -| `QUESTION_{HASH}` | 單一存取庫的問詢紀錄 | jsc-ask | -| `PLAN_CONTENTS` | 計畫目錄 | jsc-sdlc | -| `PLAN_{yyyyMMdd}_{HHmmss}_{HASH}` | 計畫頁 | jsc-sdlc | -| `ANALYZE_CONTENTS` | 分析目錄 | jsc-sdlc | -| `ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}` | 分析頁 | jsc-sdlc | -| `MAINTAIN_CONTENTS` | 維護目錄 | jsc-sdlc | -| `REPO_CONTENTS` | 盤點目錄 | jsc-sdlc | -| `REPO_{HASH}` | 存取庫盤點頁（功能與端點 + commit sha） | jsc-sdlc | -| `LOG_CONTENTS` | 日誌目錄 | jsc-log | -| `LOG_{yyyyMM}_W{週數}` | 工作日誌（週數基於週五日期計算） | jsc-log | +所有 wiki 頁面一律採雙層命名： -`{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的 SHA-1 前 8 碼、大寫。 +| 類型 | 目錄頁 | 內容頁 | 用途 | 擁有者 | +| --- | --- | --- | --- | --- | +| `QUESTION` | `QUESTION_CONTENTS` | `QUESTION_{HASH}` | 問詢目錄、單一存取庫的問詢紀錄 | jsc-ask | +| `PLAN` | `PLAN_CONTENTS` | `PLAN_{HASH}` | 計畫目錄、計畫頁 | jsc-sdlc | +| `ANALYZE` | `ANALYZE_CONTENTS` | `ANALYZE_{HASH}` | 分析目錄、分析頁 | jsc-sdlc | +| `MAINTAIN` | `MAINTAIN_CONTENTS` | `MAINTAIN_{HASH}` | 維護目錄、維護頁 | jsc-sdlc | +| `REPO` | `REPO_CONTENTS` | `REPO_{HASH}` | 盤點目錄、存取庫盤點頁 | jsc-sdlc | +| `LOG` | `LOG_CONTENTS` | `LOG_{HASH}` | 日誌目錄、工作日誌頁 | jsc-log | +| `ERROR` | `ERROR_CONTENTS` | `ERROR_{HASH}` | 異常目錄、異常頁 | jsc-hooks | + +`{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的 SHA-1 前 8 碼，大寫。 +若第一碼是 `0-9`、`A`、`B`、`C`，就改成 `H` 加上原 SHA-1 前 7 碼，總長仍維持 8 碼。 +同一規則套用到所有目錄頁與內容頁。 ## 審核檢查清單 @@ -87,9 +95,10 @@ - [ ] 名稱符合命名規則，且與既有技能目標不重複 - [ ] description 為英文、≤ 5 句或 5 步驟、含觸發時機 -- [ ] 可 hook 的規則已下放 jsc-hooks；可工具化的流程已下放 tools/ +- [ ] 可 hook 的規則已下放 jsc-hooks；可工具化的流程已下放 tools/；SKILL.md 沒有保留可由標準輸入輸出執行的細節流程 - [ ] 細節流程已標示 MUST run as a sub agent - [ ] gitea 操作透過 gitea.sh 或 tea +- [ ] wiki repo 與 Gitea 認證先讀目前 shell 繼承的環境變數；只有缺值或無法解析時才詢問；頁面類型不得跨用其他 `JSC_WIKI_REPO_{TYPE}` - [ ] 問詢透過 jsc-ask 決策樹規則 - [ ] SKILL.md 整份為英文（要原樣輸出的繁中字面除外）；README、AGENTS、templates、references 為 STE100 繁中；UTF-8 無亂碼 - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version diff --git a/skills/skill-check/SKILL.md b/skills/skill-check/SKILL.md new file mode 100644 index 0000000..1d2a50f --- /dev/null +++ b/skills/skill-check/SKILL.md @@ -0,0 +1,17 @@ +--- +name: skill-check +description: Routine compliance audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, audit every skill against the guidelines.md audit checklist via sub agents, confirm each failed item with the user via decision tree, apply the confirmed fixes and re-check until all items pass, then open a PR per affected repo via jsc-git pr. Use for periodic or on-demand compliance checks of the skill set; not for applying a change request (use skillset-update) or editing one skill (use skill-update). +--- + +# skill-check — audit the skill set against the guidelines + +Single source of guidelines: [`../../references/guidelines.md`](../../references/guidelines.md). + +## Flow + +1. Query the Gitea canonical marketplace for the authoritative domain list: run `jsc-gitea/tools/gitea.sh api GET /repos/plugins/jsc/raw/.claude-plugin/marketplace.json`. Clone any domain repo missing from the working directory (`gitea.sh clone-url plugins/{domain}`) and pull the rest. Completion condition: every domain repo exists locally and is current. +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. +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 — this step MUST run as a sub agent, one sub agent per affected domain repo: modify the files, sync 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. diff --git a/skills/skill-delete/SKILL.md b/skills/skill-delete/SKILL.md index bdd9b09..ab6a344 100644 --- a/skills/skill-delete/SKILL.md +++ b/skills/skill-delete/SKILL.md @@ -17,7 +17,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references - References in other SKILL.md files, the domain README's 「Skills 目錄」 section, the two marketplace.json files in `plugins/jsc` plus their synced copies in every domain repo, `tools/`, and the `jsc-hooks` wiring 5. For each affected file: 1. Decide whether the file needs a fix to keep its current behavior after the deletion. If no fix is needed, **skip the rest of this loop**. - 2. Ask for fix details via the `jsc-ask:ask` decision tree (call a replacement skill? inline the flow? drop the feature too?). Every option states its impact scope. + 2. Ask for fix details via the `jsc-ask:ask` decision tree (call a replacement skill? move a deterministic input/output flow to `tools/`? run the detailed flow as a sub agent? drop the feature too?). If the fix touches wiki or Gitea access, confirm it reads inherited environment variables before asking the user. Every option states its impact scope. 3. After fixing, check the guidelines.md audit checklist. On failure, return to step 5.2. 6. Delete the skill directory `skills/{name}/`, then sync the domain README and bump the version in all three manifests. 7. Deep-delete verification — this step MUST run as a sub agent: after deleting via each CLI's native plugin commands, physically inspect every installed CLI's on-disk skill and hook storage. Detect CLIs via `jsc-cli/tools/detect-clis.sh`; check Claude's `~/.claude/plugins/cache/` and hook entries in settings, plus the equivalent locations for codex / copilot / antigravity / kiro. Confirm no file or hook wiring for the deleted skill remains. Completion condition: every location checked and clean; remove any leftover by hand and recheck. diff --git a/skills/skillset-update/SKILL.md b/skills/skillset-update/SKILL.md index d29999c..8113a9f 100644 --- a/skills/skillset-update/SKILL.md +++ b/skills/skillset-update/SKILL.md @@ -9,7 +9,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references ## Flow -1. Ask for the change details via the `jsc-ask:ask` decision tree: what rule or behavior changes, which skills and which domains are affected. Every option states its impact scope (example: changing a shared flow step touches every skill that calls it). Completion condition: the affected-skill list is agreed with the user. +1. Ask for the change details via the `jsc-ask:ask` decision tree: what rule or behavior changes, which skills and which domains are affected. Include three required checks before the affected-skill list is final: whether any deterministic input/output flow must move to `tools/`, whether any detailed flow must run as a sub agent, and whether any wiki or Gitea flow must read inherited environment variables before asking the user. Every option states its impact scope (example: changing a shared flow step touches every skill that calls it). Completion condition: the affected-skill list and the three checks are agreed with the user. 2. Query the Gitea canonical marketplace for the authoritative domain list: run `jsc-gitea/tools/gitea.sh api GET /repos/plugins/jsc/raw/.claude-plugin/marketplace.json`. Clone any domain repo missing from the working directory (`gitea.sh clone-url plugins/{domain}`) and pull the rest. Completion condition: every domain repo exists locally and is current. 3. Apply the change to every affected skill — this step MUST run as a sub agent, one sub agent per affected domain repo: modify SKILL.md and related files and tools, 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.