.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-meta",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "技能組自我管理：新建、更新、刪除技能與技能準則",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-meta",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "技能組自我管理：新建、更新、刪除技能與技能準則",
   "skills": "./skills",
   "jsc": {

README.md

@@ -48,6 +48,10 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 同步上游 speak-human-tw 的語言規則：比對 `references/ste100.md` 釘住的上游版本，有新版就萃取適用的變更、逐項決策樹確認、更新 lint 樣式、全庫重掃、bump manifest，最後開 PR。適合列為本 repo 的維護方式。
 
+### `tooling-guide`
+
+盤點目前支援的 plugins、skills、hooks 管理與使用路徑，產出技能組基礎指引。適合建立技能組地圖、支援清單、hook 管理總覽與新人交接資料；安裝、更新、刪除、稽核與修復改用對應技能。
+
 <!-- JSC-SKILLS:END -->
 
 ## 參考與工具
@@ -59,6 +63,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | `tools/ste100-lint.sh` | 語言規則的機檢工具：中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線；命中 exit 1 |
 | `tools/sync-domains.sh` | 依 Gitea 正本 marketplace 把所有 domain 存取庫 clone 或 pull 到本機，印出 `domain<TAB>path`；**只有 exit 0 代表全部到位且最新**，exit 3 代表有存取庫跳過或 pull 失敗（stderr 列路徑），exit 2 代表有 domain clone 失敗 |
 | `tools/list-skills.sh` | 列出正本 marketplace 上各 domain 存取庫的技能，印出 `domain<TAB>name<TAB>description`；不在正本清單上的存取庫不列 |
+| `tools/inventory-tooling.sh` | 盤點目前支援的 plugins、skills、tools、hooks，輸出技能組基礎指引 Markdown |
 | `tools/sync-marketplace.sh` | 寫入或更新兩份正本 marketplace 的 plugin 條目，再複製到每個 domain 存取庫（保證位元組一致）。**需要 python3**（json 模組改 JSON），缺 python3 不寫檔並 exit 1；存取庫不在本機 exit 3 |
 | `tools/sync-skill-manifest.sh` | 同步 domain README 的「Skills 目錄」，並 bump 三份 manifest 的 version；`minor` 與 `patch` 不得超過 `9`，`major` 可以超過 `9` |
 | `tools/find-skill-refs.sh` | 盤點一個技能在正本 marketplace 各 domain 存取庫裡的引用檔案（不掃非技能組存取庫與點開頭目錄）；技能名稱為純子字串比對，命中要逐檔確認；零命中 exit 1，掃描失敗 exit 3 |

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-meta",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "技能組自我管理：新建、更新、刪除技能與技能準則",
   "skills": "./skills/",
   "jsc": {

skills/tooling-guide/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: tooling-guide
+description: Inventory the current jsc plugins, skills, hook management, and usage paths as the baseline tooling guide. Use when the user asks for a skill-set guide, tooling map, supported plugin list, supported skill list, hook management overview, or onboarding reference. Do not use for installing, updating, deleting, auditing, or repairing the skill set; use jsc-cli:deploy, jsc-meta:skill-check, jsc-meta:skill-update, jsc-meta:skill-delete, or jsc-hooks:hooks-install instead.
+---
+
+# tooling-guide - build the baseline tooling guide
+
+Goal: produce a current guide for the jsc skill set from the local repos and the supported tooling scripts.
+
+Single source of guidelines: [`../../references/guidelines.md`](../../references/guidelines.md).
+
+## Rules
+
+- Keep the guide factual and current.
+- Prefer script output over copied lists.
+- Use `tools/inventory-tooling.sh` for the baseline inventory.
+- Keep command syntax in the guide only when it comes from README files or tool output.
+- Do not modify README files, manifests, marketplace files, hooks, tools, or other skills.
+- Put generated guide text in the response or in the user-requested target only.
+- Run detail synthesis as a sub agent when the guide needs explanations, grouping, or onboarding prose.
+
+Done when these rules are all checked before the final report.
+
+## Inputs
+
+- Optional user scope: plugin inventory, skill inventory, hook management, CLI usage, or all areas.
+- Optional output target: chat response, wiki draft text, or a named file that the user explicitly requests.
+
+Done when the scope and output target are known. If the user gives no scope, use all areas. If the user gives no target, return the guide in chat.
+
+## Flow
+
+1. Confirm the working roots. Use `/root/plugins/meta` as the meta root. Use sibling repos under `/root/plugins` for current domain checkouts. Completion condition: the meta root exists and contains `references/guidelines.md`.
+
+2. Sync the domain inventory with `tools/sync-domains.sh` from the meta root. This script owns marketplace discovery and local repo synchronization.
+   - Exit 0: continue with the printed `domain<TAB>path` rows.
+   - Exit 3: keep the printed rows, report every skipped or dirty repo from stderr as stale input, and continue only after the user accepts a guide with stale rows.
+   - Exit 2: report the clone failure and stop.
+   - Exit 1: report the unreadable canonical marketplace and stop.
+
+   Completion condition: each plugin row used by the guide has a domain and a local path, or the stale-input decision is recorded.
+
+3. Build the baseline guide with `tools/inventory-tooling.sh` from the meta root. Use its Markdown output as the base document.
+   - Exit 0: continue with the generated guide.
+   - Any other exit: report the command, exit code, and stderr, then stop.
+
+   Completion condition: the generated guide contains `Source freshness`, `Supported plugins`, `Supported skills`, `Supported CLIs`, `Hook management`, `Plugin and skill management`, `Operational checks`, and `Use this when`.
+
+4. Build the skill catalog with `tools/list-skills.sh` from the meta root. Use its TSV rows as the skill list when the baseline guide needs verification or a smaller scope.
+   - Exit 0: continue with the printed `domain<TAB>name<TAB>description` rows.
+   - Any other exit: report the command, exit code, and stderr, then stop.
+
+   Completion condition: every skill row used by the guide comes from the script output.
+
+5. Detect supported CLIs with `/root/plugins/cli/tools/detect-clis.sh`. Use its TSV rows as the installed CLI list when the baseline guide needs verification or a smaller scope.
+   - Exit 0 with rows: continue with the printed `name<TAB>path<TAB>version` rows.
+   - Exit 0 with no rows: continue and mark CLI-specific checks as not available on this machine.
+   - Any other exit: report the command, exit code, and stderr, then stop.
+
+   Completion condition: the guide states the detected CLI set, or states that no installed CLI was detected.
+
+6. Collect hook wiring facts for each detected CLI with `/root/plugins/hooks/tools/wire-cli.sh status {cli}`. Use `status` only when the baseline guide needs verification or a smaller scope.
+   - Exit 0, 1, or 5: keep the status and all `item` lines.
+   - Exit 3: mark that CLI as skipped.
+   - Exit 2: fix the CLI code from the detect output and rerun.
+   - Any other exit: report the command, exit code, and stderr, then mark the hook status as unknown.
+
+   Completion condition: every detected CLI has one hook-wiring verdict, or the guide states why the verdict is unknown.
+
+7. Collect management-flow facts from the current docs and skills. Read only README files, `SKILL.md` files, and tool help or headers from `tools/` under the synced domain repos. Do not infer support from missing or stale files. Completion condition: each management flow in the guide points to one source file or one tool output.
+
+8. Synthesize the guide. This step MUST run as a sub agent when the output needs explanations, grouping, onboarding prose, or cross-domain comparison. Give the sub agent only the collected inventories, the relevant README and SKILL paths, and this required section list:
+   - Supported plugins
+   - Supported skills
+   - Supported CLIs and usage forms
+   - Hook management
+   - Plugin and skill management
+   - Health checks and repair paths
+   - Known coverage limits
+
+   Completion condition: the sub agent returns a guide draft with every required section and with source paths for each factual claim.
+
+9. Verify the draft in the main agent.
+   - Check that each plugin comes from `sync-domains.sh`.
+   - Check that each skill comes from `list-skills.sh`.
+   - Check that each hook-wiring fact comes from `wire-cli.sh status`.
+   - Check that install, update, delete, audit, repair, and health-check actions point to the owning skill or tool.
+   - Check that the draft does not copy long implementation details from README files or scripts.
+
+   Completion condition: every factual claim has a source path or tool output, and no required section is empty.
+
+10. Deliver the guide in the requested target. If the target is chat, keep it concise and include the source paths used. If the target is a file, write only that user-requested file and do not update manifests or README files. Completion condition: the guide is delivered and the final report names the target, source freshness, stale inputs if any, and any unknown hook verdicts.
+
+## Output Contract
+
+The guide must include these fields in this order:
+
+1. `Source freshness`: synced, stale accepted, or blocked.
+2. `Supported plugins`: one row per domain.
+3. `Supported skills`: one row per skill.
+4. `Supported CLIs`: one row per detected CLI, or one sentence for none detected.
+5. `Hook management`: wiring, smoke, error scan, repair owner, and coverage limits.
+6. `Plugin and skill management`: install, update, delete, audit, and creation owners.
+7. `Operational checks`: doctor, setup, version guard, restart gate, language guard, and comment-scope guard.
+8. `Use this when`: short usage guidance for maintainers.
+
+Done when the output has all fields in order and each non-empty table has at least one source reference.

tools/inventory-tooling.sh

@@ -0,0 +1,273 @@
+#!/usr/bin/env sh
+# inventory-tooling.sh — 盤點 jsc plugins、skills、tools、hooks，輸出技能組基礎指引。
+#
+# 用法: inventory-tooling.sh [root]
+#
+# root: 預設取本腳本位置的上兩層（meta/tools -> meta -> 根）。
+#   也可用參數或 JSC_PLUGINS_ROOT 覆寫。
+#
+# 輸出: Markdown。內容包含 domain、manifest、技能、工具、hooks 與管理入口。
+# 結束碼: 0=成功 1=根目錄、marketplace 或必要工具缺失
+set -eu
+
+HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+ROOT=${1:-${JSC_PLUGINS_ROOT:-$(CDPATH= cd -- "$HERE/../.." && pwd)}}
+ROOT=${ROOT%/}
+
+[ -d "$ROOT" ] || { echo "找不到 plugins 根目錄：$ROOT" >&2; exit 1; }
+
+MARKETPLACE=""
+for cand in "$ROOT/meta/.claude-plugin/marketplace.json" "$ROOT"/*/.claude-plugin/marketplace.json; do
+  [ -f "$cand" ] && { MARKETPLACE=$cand; break; }
+done
+[ -n "$MARKETPLACE" ] || { echo "找不到 marketplace.json，無法判定 domain 清單" >&2; exit 1; }
+
+LIST_SKILLS="$ROOT/meta/tools/list-skills.sh"
+[ -x "$LIST_SKILLS" ] || { echo "找不到可執行的 list-skills.sh：$LIST_SKILLS" >&2; exit 1; }
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+domains_file="$tmp/domains.tsv"
+skills_file="$tmp/skills.tsv"
+clis_file="$tmp/clis.tsv"
+hook_status_file="$tmp/hook-status.tsv"
+
+sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"jsc-\([a-z0-9-]*\)".*/\1/p' "$MARKETPLACE" |
+  sort -u |
+  while read -r domain; do
+    [ -n "$domain" ] || continue
+    path="$ROOT/$domain"
+    [ -d "$path" ] || path="$ROOT/jsc-$domain"
+    if [ -d "$path" ]; then
+      version=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' "$path/plugin.json" 2>/dev/null | head -1)
+      [ -n "$version" ] || version="未知"
+      printf '%s\t%s\t%s\n' "$domain" "$version" "$path"
+    else
+      printf '%s\t%s\t%s\n' "$domain" "缺本機存取庫" "-"
+    fi
+  done > "$domains_file"
+
+JSC_PLUGINS_ROOT="$ROOT" "$LIST_SKILLS" > "$skills_file" 2>/dev/null || : > "$skills_file"
+
+DETECT_CLIS="$ROOT/cli/tools/detect-clis.sh"
+if [ -x "$DETECT_CLIS" ]; then
+  "$DETECT_CLIS" > "$clis_file" 2>/dev/null || : > "$clis_file"
+else
+  : > "$clis_file"
+fi
+
+WIRE_CLI="$ROOT/hooks/tools/wire-cli.sh"
+: > "$hook_status_file"
+if [ -x "$WIRE_CLI" ] && [ -s "$clis_file" ]; then
+  while IFS="$(printf '\t')" read -r cli path version; do
+    [ -n "$cli" ] || continue
+    out="$tmp/wire-$cli.out"
+    err="$tmp/wire-$cli.err"
+    if "$WIRE_CLI" status "$cli" > "$out" 2> "$err"; then
+      rc=0
+    else
+      rc=$?
+    fi
+    verdict=$(sed -n '1{s/[|]/-/g;p;}' "$out")
+    [ -n "$verdict" ] || verdict=$(sed -n '1{s/[|]/-/g;p;}' "$err")
+    [ -n "$verdict" ] || verdict="無狀態輸出"
+    case "$rc" in
+      0|1|3|5) ;;
+      2) verdict="CLI 代號不符合 wire-cli.sh 用法" ;;
+      *) verdict="未知狀態，結束碼 $rc" ;;
+    esac
+    printf '%s\t%s\t%s\n' "$cli" "$rc" "$verdict" >> "$hook_status_file"
+  done < "$clis_file"
+fi
+
+count_lines() {
+  file=$1
+  [ -s "$file" ] || { echo 0; return; }
+  wc -l < "$file" | tr -d ' '
+}
+
+domains_count=$(count_lines "$domains_file")
+skills_count=$(count_lines "$skills_file")
+clis_count=$(count_lines "$clis_file")
+
+cat <<EOF
+# jsc 技能組基礎指引
+
+產生時間：$(date '+%Y-%m-%d %H:%M:%S %z')
+
+資料來源：
+
+- plugins 根目錄：\`$ROOT\`
+- marketplace：\`$MARKETPLACE\`
+- 技能清單工具：\`$LIST_SKILLS\`
+
+## Source freshness
+
+| 項目 | 狀態 |
+| --- | --- |
+| 本機 domain 清單 | synced |
+| marketplace | \`$MARKETPLACE\` |
+
+## 現況摘要
+
+| 項目 | 數量 |
+| --- | ---: |
+| 已註冊 plugin domain | $domains_count |
+| 已掃到技能 | $skills_count |
+| 已偵測 CLI | $clis_count |
+
+## Supported plugins
+
+| domain | version | 本機路徑 |
+| --- | --- | --- |
+EOF
+
+while IFS="$(printf '\t')" read -r domain version path; do
+  [ -n "$domain" ] || continue
+  printf '| `%s` | `%s` | `%s` |\n' "$domain" "$version" "$path"
+done < "$domains_file"
+
+cat <<'EOF'
+
+## Supported skills
+
+| domain | skill | 用途 |
+| --- | --- | --- |
+EOF
+
+if [ -s "$skills_file" ]; then
+  while IFS="$(printf '\t')" read -r domain name desc; do
+    [ -n "$domain" ] || continue
+    printf '| `%s` | `%s` | %s |\n' "$domain" "$name" "$desc"
+  done < "$skills_file"
+else
+  echo '| - | - | 未掃到技能。請先執行 `meta/tools/sync-domains.sh`。 |'
+fi
+
+cat <<'EOF'
+
+Skill 使用方式：
+
+- Claude、Antigravity：使用 `/jsc-{domain}:{name}`。
+- Codex：使用技能名稱或自然語意觸發。
+- Copilot、Kiro：用需求描述觸發。
+- 每支技能只保留決策與流程。可標準輸入輸出的細節放到 `tools/`。
+- 需要強制執行的規則放到 `jsc-hooks`，不要散落在各 domain。
+
+## Supported CLIs
+
+| CLI | 執行檔 | 版本 |
+| --- | --- | --- |
+EOF
+
+if [ -s "$clis_file" ]; then
+  while IFS="$(printf '\t')" read -r cli path version; do
+    [ -n "$cli" ] || continue
+    printf '| `%s` | `%s` | `%s` |\n' "$cli" "$path" "$version"
+  done < "$clis_file"
+else
+  echo '| - | - | 這台機器未偵測到支援的 CLI，或找不到 `cli/tools/detect-clis.sh`。 |'
+fi
+
+cat <<'EOF'
+
+## Supported tools
+
+| domain | tool | 用途 |
+| --- | --- | --- |
+EOF
+
+while IFS="$(printf '\t')" read -r domain version path; do
+  [ -d "$path/tools" ] || continue
+  for tool in "$path"/tools/*; do
+    [ -f "$tool" ] || continue
+    base=$(basename "$tool")
+    first=$(sed -n '2{s/^# *//;p;}' "$tool" 2>/dev/null)
+    [ -n "$first" ] || first="工具腳本"
+    printf '| `%s` | `%s` | %s |\n' "$domain" "$base" "$first"
+  done
+done < "$domains_file"
+
+cat <<'EOF'
+
+Tool 使用方式：
+
+- 先讀工具檔頭的用法與結束碼。
+- 用真實參數驗證新增或修改的工具。
+- 結束碼沒有文件化時，先補工具說明，再讓技能呼叫它。
+
+## Hook management
+
+| hook | 用途 |
+| --- | --- |
+EOF
+
+HOOK_DIR="$ROOT/hooks/hooks"
+if [ -d "$HOOK_DIR" ]; then
+  for hook in "$HOOK_DIR"/*.sh; do
+    [ -f "$hook" ] || continue
+    base=$(basename "$hook")
+    first=$(sed -n '2{s/^# *//;p;}' "$hook" 2>/dev/null)
+    [ -n "$first" ] || first="hook 腳本"
+    printf '| `%s` | %s |\n' "$base" "$first"
+  done
+else
+  echo '| - | 找不到 `hooks/hooks`。請先執行 `meta/tools/sync-domains.sh`。 |'
+fi
+
+cat <<'EOF'
+
+Hook 使用方式：
+
+- Hook 只放在 `jsc-hooks` domain。
+- `jsc-hooks:hooks-install` 負責接線到各 CLI。
+- hook 腳本要能接受 stdin JSON 與環境變數。
+- 缺欄位時安靜降級並 `exit 0`。
+- 版本閘門與重啟閘門要保留解除自己的路徑。
+
+## Hook wiring status
+
+| CLI | 結束碼 | 狀態 |
+| --- | ---: | --- |
+EOF
+
+if [ -s "$hook_status_file" ]; then
+  while IFS="$(printf '\t')" read -r cli rc status; do
+    [ -n "$cli" ] || continue
+    printf '| `%s` | %s | %s |\n' "$cli" "$rc" "$status"
+  done < "$hook_status_file"
+else
+  echo '| - | - | 未偵測到 CLI，或找不到 `hooks/tools/wire-cli.sh`。 |'
+fi
+
+cat <<'EOF'
+
+## Plugin and skill management
+
+- 新增技能：使用 `jsc-meta:skill-new`。
+- 更新單一技能：使用 `jsc-meta:skill-update`。
+- 批次更新技能組：使用 `jsc-meta:skillset-update`。
+- 刪除技能：使用 `jsc-meta:skill-delete`。
+- 安裝、更新、移除整組 plugin：使用 `jsc-cli:deploy`。
+- 例行稽核：使用 `jsc-meta:skill-check`。
+- 重新接線 hooks：使用 `jsc-hooks:hooks-install`。
+
+## Operational checks
+
+- 體檢目前環境：使用 `jsc-cli:doctor`。
+- 修復體檢項目：使用 `jsc-cli:setup`。
+- 版本前置檢查：由 `jsc-hooks/hooks/version-guard.sh` 管理。
+- 部署後重啟閘門：由 `jsc-hooks/hooks/restart-gate.sh` 管理。
+- 語言提示與掃描：由 `jsc-hooks/hooks/ste100-guard.sh` 與 `jsc-hooks/hooks/lang-guard.sh` 管理。
+- 註解範圍檢查：由 `jsc-hooks/hooks/comment-scope.sh` 管理。
+
+## Use this when
+
+- 先執行 `meta/tools/sync-domains.sh`，同步 marketplace 上的 domain。
+- 再執行 `meta/tools/list-skills.sh`，確認技能清單。
+- 執行本工具，產出基礎指引。
+- 若新增或修改技能，執行 `meta/tools/sync-skill-manifest.sh {domain-path}`。
+- 執行 `meta/tools/ste100-lint.sh {domain-path}`。
+- 依 `jsc-git:pr` 開立 Push Request。
+EOF