Merge pull request 'sync' (#3) from master into develop

Reviewed-on: plugins/generic#3

.agents/plugins/marketplace.json

@@ -5,7 +5,7 @@
       "name": "jsc",
       "source": {
         "source": "url",
-        "url": "https://gitea.jsc.idv.tw/plugins/template.git"
+        "url": "https://gitea.jsc.idv.tw/plugins/generic.git"
       }
     }
   ]

.claude-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "jsc",
-  "version": "0.1.0",
+  "version": "0.0.1",
   "description": "JSC 跨 AI 助理共用 plugin 模板（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
   "skills": "./skills",
   "author": {
     "name": "JSC"
   },
-  "homepage": "https://gitea.jsc.idv.tw/plugins/template",
+  "homepage": "https://gitea.jsc.idv.tw/plugins/generic",
-  "repository": "https://gitea.jsc.idv.tw/plugins/template.git",
+  "repository": "https://gitea.jsc.idv.tw/plugins/generic.git",
   "keywords": ["template", "skills", "cross-tool", "jsc"]
 }

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.1.0",
+  "version": "0.0.1",
   "description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準。",
   "skills": "./skills"
 }

README.md

@@ -3,7 +3,7 @@
 一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的 plugin 模板。
 核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
 搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
-在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:hello`）。
+在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:spec-output`）。
 
 ---
 
@@ -35,7 +35,7 @@ template/
 │   └── marketplace.json     # Codex marketplace（name: "jsc-plugins"，url source 指向本 repo）
 ├── plugin.json              # Antigravity 外掛定義（name: "jsc"，skills: "./skills/"）
 ├── skills/                  # ★ 唯一真實來源：所有 skills
-│   └── hello/SKILL.md
+│   └── spec-*/SKILL.md      # 共用規範 skills（一規範一目錄）
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
 ```
@@ -68,7 +68,7 @@ claude plugin marketplace remove template
 
 - 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
 - 本機開發（免 push）：`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\template`（本地路徑）後再 install。
-- **呼叫**：`/jsc:<name>`（例 `/jsc:hello`）。
+- **呼叫**：`/jsc:<name>`（例 `/jsc:spec-output`）。
 
 ### Codex
 
@@ -87,7 +87,7 @@ codex plugin marketplace remove template
 
 - 安裝 token `jsc@template` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
 - 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。
-- **呼叫**：`$<name>`（例 `$hello`），或用 `/skills` 選單。
+- **呼叫**：`$<name>`（例 `$spec-output`），或用 `/skills` 選單。
 
 ### Antigravity（`agy`）
 
@@ -109,7 +109,7 @@ agy plugin uninstall jsc
 
 - 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com/<owner>/<repo>`。
 - 其他：`agy plugin list`、`agy plugin enable jsc` / `disable jsc`、`agy plugin validate <path>`。安裝後重啟工作階段。
-- **呼叫**：`/jsc:<name>`（例 `/jsc:hello`）或依描述自動觸發。
+- **呼叫**：`/jsc:<name>`（例 `/jsc:spec-output`）或依描述自動觸發。
 
 ### OpenCode
 
@@ -127,7 +127,7 @@ git -C ~/plugins/template pull
 cp -r ~/plugins/template/skills/* ~/.config/opencode/skills/
 
 # 移除
-rm -rf ~/.config/opencode/skills/hello
+rm -rf ~/.config/opencode/skills/spec-*
 ```
 
 > **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
@@ -140,17 +140,17 @@ rm -rf ~/.config/opencode/skills/hello
 
 安裝好之後，不必進互動介面，一行指令就能叫某個 skill 跑完並印出結果：
 
-| 助理 | headless 指令 | 執行 `hello` skill |
+| 助理 | headless 指令 | 執行 `spec-output` skill |
 | --- | --- | --- |
-| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc:hello"` |
+| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc:spec-output"` |
-| Codex | `codex exec "<prompt>"` | `codex exec '$hello'` |
+| Codex | `codex exec "<prompt>"` | `codex exec '$spec-output'` |
-| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc:hello"` |
+| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc:spec-output"` |
-| OpenCode | `opencode run "<message>"` | `opencode run "用 hello skill 打個招呼"` |
+| OpenCode | `opencode run "<message>"` | `opencode run "說明 JSC 共用輸出規範的內容"` |
 
 - Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:<name>"` 即可。
-- Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$hello'`。
+- Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$spec-output'`。
 - OpenCode 沒有前綴，用自然語言描述需求，模型會自動透過 skill 工具呼叫。
-- 帶引數就接在後面，例如 `claude -p "/jsc:hello 參數"`、`codex exec '$hello 參數'`。
+- 帶引數就接在後面，例如 `claude -p "/jsc:spec-output 參數"`、`codex exec '$spec-output 參數'`。
 
 ---
 
@@ -161,13 +161,22 @@ rm -rf ~/.config/opencode/skills/hello
 
 <!-- JSC-SKILLS:START -->
 
-### `hello`
+### 共用規範（spec-*）
 
-範例 skill，用來驗證 jsc plugin 是否安裝成功，也是新增 skill 的範本。當使用者輸入 hello、想測試 plugin、或想看 skill 模板長什麼樣子時觸發；回覆一句問候並簡述此 plugin 的用途。
+以下 skills 是 **code／doc plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc:spec-<name>` 引用時載入；也可單獨呼叫查看規範內容。
 
-- **Claude Code / Antigravity**：`/jsc:hello`
+| Skill | 類型 | 內容 |
-- **Codex**：`$hello`，或用 `/skills` 選單
+| --- | --- | --- |
-- **OpenCode**：描述需求自動觸發
+| `spec-output` | 輸出規範 | 繁體中文（台灣用語）、UTF-8 無 BOM 無亂碼、表格與 Mermaid 呈現、subagent 提示需帶入本規範 |
+| `spec-execution` | 執行原則 | 自動執行原則（必要決策才中斷、已知資訊跳過詢問）、不臆測／需人工確認、不擴及無關檔案 |
+| `spec-gitea` | Gitea 工具 | tea／API 工具選擇與檢查、GITEA_TOKEN 機密保護、不依賴 jq、API 分頁與 UTF-8 JSON body、host 決定順序 |
+| `spec-git-safety` | Git 安全 | 不破壞既有工作（絕不 reset --hard／clean）、git mv 保留歷史、develop → master 後備、pull --ff-only、保守解衝突 |
+| `spec-time-log` | 時間與訊息 | Asia/Taipei `yyyy/MM/dd HH:mm:ss` 更新時間與統一同步、`[時間][階段][等級]: 訊息` log 格式、一行一則 |
+| `spec-action-params` | Action 參數 | action 參數來源優先序（context／環境變數 → inputs）、secrets／vars 一律視為不可用 |
+| `spec-dockerfile` | Dockerfile | 六步流程（參數→安裝→複製→執行→縮小→入口）、多階段建置、固定版號、對外契約不動、自我檢查 |
+| `spec-project-board` | Gitea 看板 | 進度欄位語意對應、建議欄位規則、GET 探測（404/501 不支援）、不往回移、不得新建欄位 |
+| `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc:doc-funcs 的標準流程與統一時間戳 |
+| `spec-plugin-version` | 版號規則 | 三 manifest 同步 bump、對照 master 確保單調遞增、新 plugin 首發 0.0.1、chore(plugin 版本) commit |
 
 <!-- JSC-SKILLS:END -->
 
@@ -175,13 +184,13 @@ rm -rf ~/.config/opencode/skills/hello
 
 ## 新增一個 skill
 
-1. 複製範本：`cp -r skills/hello skills/<your-skill-name>`
+1. 複製範本：`cp -r skills/spec-output skills/<your-skill-name>`（或從 template repo 的 `skills/hello` 複製）
 2. 編輯 `skills/<your-skill-name>/SKILL.md` 的 frontmatter：
    - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc:<name>`**。
    - `description`：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。
 3. 在內文寫下 skill 的具體步驟。
 4. 手動把這個 skill 補進上方「Skills 目錄」區塊。
-5. **bump 版本並 push**：四家都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump，commit 後 push 到 gitea。
+5. **bump 版本並 push**：四家都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump（規則見 `skills/spec-plugin-version/`），commit 後 push 到 gitea。
 6. 讓各助理更新：
    - Claude：`claude plugin update jsc@jsc-plugins`
    - Codex：`codex plugin marketplace upgrade jsc-plugins`

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.1.0",
+  "version": "0.0.1",
   "description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
   "skills": "./skills/"
 }

skills/hello/SKILL.md

@@ -1,37 +0,0 @@
----
-name: hello
-description: 範例 skill，用來驗證 jsc plugin 是否安裝成功，也是新增 skill 的範本。當使用者輸入 hello、想測試 plugin、或想看 skill 模板長什麼樣子時觸發；回覆一句問候並簡述此 plugin 的用途。
----
-
-# hello（範例 skill）
-
-這是 `jsc` plugin 的範例 skill。它有兩個用途：
-
-1. **驗證安裝** — 跨各家 AI 助理確認 skill 已被正確載入。
-2. **作為範本** — 複製這個資料夾即可新增一個新的 skill。
-
-## 呼叫方式
-
-| 助理 | 呼叫方式 |
-| --- | --- |
-| Claude Code | `/jsc:hello` |
-| Antigravity | `/jsc:hello`，或描述需求自動觸發 |
-| Codex | 在提示詞輸入 `$hello`，或用 `/skills` 選單 |
-| OpenCode | 直接描述需求，模型會透過 skill 工具自動呼叫 |
-
-## 行為
-
-當這個 skill 被觸發時：
-
-1. 回覆「Hello from **jsc** 👋」。
-2. 用一句話說明 `jsc` 是一個跨 AI 助理的共用 skill 集合。
-3. 提示使用者可以在 README 的「Skills 目錄」查看所有可用的 skills。
-
-## 如何以此為範本新增 skill
-
-1. 複製 `skills/hello/` 為 `skills/<your-skill-name>/`。
-2. 修改 `SKILL.md` 的 frontmatter：
-   - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這個名稱會成為 Claude Code / Antigravity 的 `/jsc:<name>` 指令**。
-   - `description`：第三人稱，寫清楚「什麼時候該用、什麼時候不該用」與觸發關鍵字 — 各家助理靠這段文字決定是否自動載入。
-3. 在內文寫下 skill 的具體步驟。
-4. 手動把新 skill 補進 README 的「Skills 目錄」區塊。

skills/spec-action-params/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: spec-action-params
+description: JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-action-params — 共用 action 參數來源優先序
+
+開發 Gitea／GitHub action（composite 或 Docker 容器 action）過程中需要新的參數值時，依下列順序處理，**前一項可取得就不往下**。
+
+## 1. 平台注入的 context／環境變數
+
+- **composite action**：`runs.steps` 內可直接使用 `${{ gitea.* }}`／`${{ github.* }}` context（Gitea 中兩者互為別名）。常用如 `github.repository`、`github.ref_name`、`github.server_url`、`github.token`、`github.event.*`。為同時相容 GitHub Actions，建議寫 `github.*`；`run` 腳本內可改讀同源的執行期環境變數（`$GITHUB_REPOSITORY` 等）。
+- **Docker 容器 action**：`action.yml` 內 expression 幾乎只有 `inputs`／`env` context 可用，但 runner 會把 `gitea.*`／`github.*` 同源資訊以**執行期環境變數注入容器** — Node 主程式讀 `process.env.GITHUB_*`（如 `GITHUB_REPOSITORY`、`GITHUB_SERVER_URL`、`GITHUB_REF_NAME`、`GITHUB_EVENT_PATH`；Gitea 亦提供 `GITEA_*` 同義變數），`entrypoint.sh` 內以 `$GITHUB_*` 讀取。為相容 GitHub，程式內建議讀 `GITHUB_*`。
+
+## 2. 取不到 → 詢問使用者新增 `inputs`
+
+- 以 `AskUserQuestion` 詢問使用者是否新增對應 `input`（名稱／description／`required`／`default`），**經同意後**才於 `inputs` 宣告。
+- 取用方式：composite 於 step 內以 `${{ inputs.<name> }}`；docker 容器內以 `INPUT_<大寫名稱>` 環境變數（Node 讀 `process.env.INPUT_<NAME>`）。
+- **未經同意不得擅自更動 `inputs`／`outputs` 契約。**
+
+## secrets／vars 一律視為不可用（不列入優先序）
+
+- `${{ secrets.* }}`／`${{ vars.* }}` context 在 composite action 的 `action.yml` 內於 GitHub 為**官方明文不可用**（`inputs` 的 `default` 也不能引用）；在 Docker 容器 action 的 `runs.args`／`runs.env` 內亦不可用（官方文件僅記載 `inputs` context 可用，runner 也不會把呼叫端 secrets 自動注入容器）。Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。
+- 為求兩邊相容，一律視為不可用 — 參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 `input`，回報時附上呼叫端 workflow 的傳入寫法：
+
+  ```yaml
+  - uses: <owner>/<action>@<ref>
+    with:
+      token: ${{ secrets.MY_TOKEN }}     # secrets 由呼叫端 workflow 傳入
+      registry: ${{ vars.MY_REGISTRY }}  # vars 亦同
+  ```

skills/spec-doc-funcs-handoff/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: spec-doc-funcs-handoff
+description: JSC plugins 共用「串接 doc-funcs 文件化流程」規範：code 類 skill（action 標準化、Dockerfile 整理）完成主要工作後，對整個目標專案完整執行 /jsc:doc-funcs（前置可用性檢查、完整流程步驟、由使用者裁示實作方式、完成後統一時間戳）。當其他 skill 內文引用 spec-doc-funcs-handoff 或 /jsc:spec-doc-funcs-handoff、或某 skill 的最後階段要完整執行 doc-funcs 補文件並重建 README 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-doc-funcs-handoff — 共用「串接 doc-funcs」流程
+
+code 類 skill 完成主要工作（action 標準化、容器化、Dockerfile 整理等）後，對**整個目標專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README。
+
+## 流程
+
+- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。
+- 以呼叫端 skill 的目標專案根目錄為目標，執行 `doc-funcs` skill 的完整流程：判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證。
+- doc-funcs 會把 `action.yml`／`Dockerfile`／`entrypoint.sh`／`docker-compose*` 等視為指令檔／CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。
+- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，呼叫端 skill **不代為決定**。
+- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
+- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步呼叫端 skill 產生的各處時間戳（橫幅 step／`entrypoint.sh`／標頭註解區塊／README），**確保各處一致**（格式見 `/jsc:spec-time-log`）。
+
+> 銜接方式：在呼叫端 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用呼叫端 skill 的目標專案根目錄。

skills/spec-dockerfile/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: spec-dockerfile
+description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-dockerfile — 共用 Dockerfile 六步流程
+
+Dockerfile 一律組織為以下**固定六步流程**，並採**多階段建置**縮小最終映像。六步是骨架，每一步的實際內容必須依專案／主程式實作決定 — 不要套用與其無關的固定樣板，也不要硬塞用不到的安裝或建置指令。
+
+## 六步流程
+
+1. **參數處理**：可調參數集中到檔案開頭以 `ARG` 注入（base image 版本、build flag、路徑等）；`# syntax` 指示與全域 `ARG` 置於最前。
+2. **安裝套件**：先 `COPY` 相依描述檔（`package*.json`／`requirements.txt`／`go.mod go.sum`／`*.csproj` 等）再安裝，以利 layer 快取；OS 套件與語言相依在此安裝，安裝後於**同一 `RUN`** 清理快取（`apt-get clean`／`rm -rf /var/lib/apt/lists/*`、`--no-cache`）。安裝指令**二擇一寫死**（如有 lockfile 用 `npm ci`、否則 `npm install`），不得以 `A || B` fallback 串接（避免靜默吞錯、破壞可重現性）。OS 套件只在真的會用到時才安裝。
+3. **複製檔案**：`COPY` 實際需要的檔案，**明列路徑、不整包 `COPY .`**（除非重整既有 Dockerfile 需保留原行為），並配合 `.dockerignore` 排除無關檔案（至少 `.git`、`.docs`、`node_modules` 等非執行必需檔）。
+4. **執行程序**：build／compile／transpile（`npm run build`／`go build`／`dotnet publish` 等）與必要的權限設定（`chmod`）於此執行；不需 build 時此步只做權限設定。
+5. **縮小映像檔**：多階段建置，runtime 階段改用較小基底（`*-slim`／`*-alpine`／`distroless`／`scratch`，依語言對應），只 `COPY --from=<build>` 帶入**執行所必需**的產物；**必須逐項明列路徑，不得整包搬**（整包搬等於沒有縮小）。不把 build 期 dev 相依與快取帶進最終映像；runtime 需要的 OS 執行檔於 runtime 階段安裝；同步搬移 runtime 需要的 `ENV`／`WORKDIR`／`EXPOSE`／`USER`。
+6. **設定入口**：`ENTRYPOINT`／`CMD` 置於最後，語意與需求（或原檔）一致。
+
+## base image 版本
+
+- **預設使用固定 major tag**（如 `node:22` 與 `node:22-slim`），不用 `latest` — 避免 base 無預警跳版導致行為漂移、跨環境不一致、無法重現除錯。
+- runtime 基底版號需與 build 基底一致，以**獨立的 runtime ARG** 帶入（如 `NODE_RUNTIME=22-slim`），不要用 `${VERSION}-slim` 組裝。tag 已是 `-alpine`／`-slim` 變體時，build 與 runtime **直接沿用同一 tag**、不再另組（沒有 `node:22-alpine-slim` 這種 tag）。使用者明確要求 `latest` 時，runtime 用 `node:slim`（**沒有 `node:latest-slim`**）。
+
+## 對外契約不動（重整既有 Dockerfile 時）
+
+- `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。
+- 凡無法可靠保證建置行為等價的重整（`ARG` 作用範圍跨 `FROM`、`COPY` 順序影響覆蓋、`RUN` 間狀態相依、單階段改多階段時 runtime 缺檔），先確認或標 `# 需人工確認` 退回最小重排。
+
+## 自我檢查
+
+1. `ARG` 在使用它的 `FROM` 之後有重新宣告（跨階段 `ARG` 規則）。
+2. runtime 階段 `COPY --from` 帶齊執行所需全部產物（執行檔、相依、靜態資源），容器能啟動。
+3. 對外契約（`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`）語意一致。
+4. 路徑一致：`WORKDIR`／`COPY` 落點與入口（`entrypoint.sh`／主程式路徑）對得上。
+5. 若環境可執行，`docker build`（或至少 `--check`／語法檢查）驗證可建置；無法執行時說明原因並標註風險。

skills/spec-execution/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: spec-execution
+description: JSC plugins 共用「執行原則」：自動執行原則（簡短計畫後直接執行到完成、只在必要決策中斷）、不臆測／需人工確認、不擴及無關檔案（排除 node_modules/.git/.docs/bin/obj/第三方依賴）。當其他 skill 內文引用 spec-execution 或 /jsc:spec-execution、或執行任何 JSC skill 需要共用執行原則時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-execution — 共用執行原則
+
+所有 JSC skills（code／doc／generic）的執行行為，一律遵守以下原則。
+
+## 自動執行原則
+
+- 除非使用者明確要求先確認，或遇到**不可忽略的必要決策**，否則各階段只需輸出簡短計畫／進度後**直接執行到完成**，不要為一般寫入、修復、留言、提交等反覆詢問。
+- **已知資訊一律跳過詢問**：使用者已透過參數（如 `--tool`、`--repo`）或對話提供的資訊，不得重複確認。
+- 帶 `--yes` 時更不應中斷；但各 skill 自行定義的「一定會中斷詢問的點」（破壞性高風險決策、對外不易復原的動作）**不得被 `--yes` 略過**。
+- 常見必要決策：目標不明（分支／專案／檔案缺失且無法推斷）、破壞性改寫需先確認、憑證皆失敗、無法安全解衝突、需求與現況衝突需人工裁示。
+
+## 不臆測／需人工確認
+
+- 任何無法可靠推論或等價推論的內容，**不編造、不硬改**：以註解或回報標註「需人工確認：...」，保留原行為，繼續處理其他項目。
+- 找不到目標（manifest、檔案、分支、專案）時**不臆測**、不逕自動工；詢問使用者或依 skill 定義的流程處理。
+- 需求彙整只做整理與歸納，不得編造來源未提及的需求。
+
+## 不擴及無關檔案
+
+- 只動 skill 明文宣告的目標檔案範圍；一律排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／generated 與第三方依賴。
+- 不要新增與任務無關的 helper、測試或重構。

skills/spec-git-safety/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: spec-git-safety
+description: JSC plugins 共用「Git 安全操作規範」：不破壞既有工作（未提交變更先提醒、絕不 reset --hard/checkout -f/clean）、git mv 保留歷史、develop → master 後備分支選擇、pull --ff-only、保守解衝突。當其他 skill 內文引用 spec-git-safety 或 /jsc:spec-git-safety、或執行任何會操作 git 工作區／分支的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-git-safety — 共用 Git 安全操作規範
+
+所有 JSC skills 操作 git 工作區、分支與遠端時，一律遵守以下規範。
+
+## 不破壞既有工作
+
+- 改寫／覆寫／搬移檔案前，若工作區有未提交變更，先提醒使用者建議先 commit／備份。
+- **絕不** `reset --hard`／`checkout -f`／`clean`，也不刪除使用者既有原始碼、不強制丟棄未提交變更。
+- 未提交變更導致切換分支／pull／建立分支失敗時，**停止並回報**，請使用者先處理；不可強制丟棄。
+- 目錄已存在且非預期內容（如非 git repo）→ 回報並略過，**不刪除、不覆蓋**。
+
+## 移動檔案優先 `git mv`
+
+- 搬移／改名檔案優先用 `git mv` 保留歷史。
+- 大小寫不敏感的檔案系統上需兩段式改名（先 `git mv A A.tmp` 再 `git mv A.tmp a`）。
+- 改名後必須同步更新專案內所有引用（設定檔、CI、文件連結），確保行為不變。
+
+## develop → master 後備分支
+
+需要基準／後備分支時（當前分支不在遠端、clone 後選工作分支、PR 目標後備），依序：
+
+1. `origin/develop` 存在 → 用 `develop`。
+2. 否則 `origin/master` 存在 → 用 `master`。
+3. 兩者皆無 → 回報「找不到 develop／master」並停止或略過該項，**不臆測其他分支**。
+
+切換寫法：
+
+```bash
+git switch develop 2>/dev/null || git switch -c develop --track origin/develop
+```
+
+- 切換後備分支屬不可忽略的狀態變更，需明確告知使用者已從原分支切換到哪個分支。
+- 批次更新既有 repo 時用 `git pull --ff-only`；無法快進（本地與遠端分歧）→ 回報需人工處理，**不**自動 merge／rebase／reset。
+
+## 保守解衝突
+
+pull／merge／cherry-pick 發生衝突時：
+
+1. 用 `git status --porcelain` 與衝突標記定位衝突檔。
+2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做**最小合理整合**。
+3. 可安全解決的衝突：編輯移除衝突標記，`git add -- <檔案...>` 標記已解決，完成 merge／rebase／cherry-pick 的必要步驟。
+4. 無法安全判斷的衝突：**停止處理**，列出檔案、原因與需要使用者決策的點；不要硬選任一邊。
+
+## 建立分支不覆蓋
+
+- 新分支名稱需可讀且避免覆蓋既有分支；本地或遠端已存在同名分支時，換一個時間戳或短 hash，不可覆蓋。
+- 建立新分支屬不可忽略的狀態變更，需明確告知使用者原因與新分支名稱。

skills/spec-gitea/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spec-gitea
+description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-gitea — 共用 Gitea 工具規範
+
+所有 JSC skills 存取 Gitea（議題、留言、PR、repo 清單）時，一律遵守以下規範。
+
+## 工具選擇（`tea` 或 `api`）
+
+使用者已明確選定工具（`--tool` 或對話中已選）時**跳過詢問**，只做該工具的可用性驗證。否則：
+
+1. 檢查 `tea` 是否存在：`command -v tea`；存在則執行 `tea login list` 記錄可用 login 與 host（失敗記錄原因，不中止）。
+2. 檢查 `GITEA_TOKEN` 是否已設定，**只輸出「已設定／未設定」**，不得輸出 token 內容：
+
+   ```bash
+   [ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"
+   ```
+
+3. 以表格呈現檢查結果後詢問使用者要用哪一種：
+
+   | 選項 | 可選條件 | 後續使用方式 |
+   | --- | --- | --- |
+   | `tea` | `tea` 可執行且目標 host 有對應 login | 命令一律帶 `--login <name> --repo <owner>/<repo>` |
+   | `api` | `GITEA_TOKEN` 已設定 | Gitea REST API + `curl`，標頭 `Authorization: token $GITEA_TOKEN` |
+
+4. 兩種方式都不可用 → 回報缺少 `tea login` 或 `GITEA_TOKEN` 並停止；**不要請使用者把 token 貼進對話**。
+5. 多筆來源分屬不同 host：選 `tea` 須確認每個 host 都有對應 login；選 `api` 須同一個 token 可存取全部，否則回報權限不足並停止。
+
+## Token 機密保護（極重要）
+
+- token 一律**從環境變數讀取**（`$GITEA_TOKEN`），**絕不**寫死在 skill、commit、PR、議題、log 或任何輸出。
+- **不可** echo 含 token 的指令或 URL；顯示給使用者的指令／錯誤訊息一律**遮蔽 token**（以 `***` 取代）；檢查時只輸出「已設定／未設定」。
+- 帶 token 的 URL（clone／push）用變數帶入、**不可印出**；token 用完即棄，不寫進 git remote 設定、不落地。clone 完成後把 origin 還原成不含 token 的乾淨 URL：
+
+  ```bash
+  git -C "${dest}" remote set-url origin "https://<host>/<owner>/<repo>.git"
+  ```
+
+- 流程若可能使對話內文殘留 token（push／API 呼叫），完成後提醒使用者清除對話（Claude Code：`/clear`），並先確認輸出與 log 無明文 token。
+
+## 不依賴 `jq`（環境未必安裝）
+
+- 解析 JSON 用 `tea` 的結構化輸出（`--output csv`／`--fields`），或把原始 JSON 直接交給助理／subagent 解析，**不要 pipe 到 `jq`**。
+
+## API 呼叫慣例
+
+- API base：`https://<host>/api/v1`（repo 層：`https://<host>/api/v1/repos/<owner>/<repo>`）。
+- 標頭：`Authorization: token $GITEA_TOKEN`。
+- **分頁必須完整讀取**：持續累加 `page` 直到回傳筆數 `< limit`（或回空陣列）為止，不可只取第一頁。
+- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc:spec-output`）。
+- API 失敗（401／403／網路錯誤）→ 回報錯誤（**遮蔽 token**）並停止；401／403 多半是 token 失效或權限不足。
+- 版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），**不得對未確認存在的端點做寫入**。
+
+## gitea 主機決定順序
+
+依序決定（取第一個成功者）：
+
+1. 參數 `--host <主機>`。
+2. 環境變數 `$GITEA_HOST`（若有）。
+3. 目前工作目錄是 git repo 且 `git remote get-url origin` 指向某 gitea 主機 → 取該 host。
+4. 以上皆無 → **詢問使用者**，不臆測。
+
+主機僅取 host 部分（如 `gitea.jsc.idv.tw`）。

skills/spec-output/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: spec-output
+description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-output — 共用輸出規範
+
+所有 JSC skills（code／doc／generic）面向使用者的輸出與寫入檔案，一律遵守以下規範。
+
+## 語言
+
+- 所有面向使用者的輸出（計畫、進度、總結、反問）與寫入外部系統的內容（議題描述／留言、commit 訊息、PR 標題與描述、README、註解）一律使用**繁體中文（台灣用語）**。
+- 僅程式碼識別字、檔名、指令（git／docker／curl 等）、API 路徑、YAML／JSON 鍵名、conventional commit 的 `type`、既有技術術語保留原文。
+- **不可**使用簡體字；敘述句不可改用英文。
+
+## 編碼無亂碼
+
+- 凡輸出或寫入含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框（）或錯碼。涵蓋：產生／覆寫的任何檔案、commit 訊息、PR 標題／描述、議題內容、終端訊息。
+- 實作要點：
+  - **寫檔**：優先用助理的檔案寫入工具（預設 UTF-8 無 BOM）。改用 shell 寫檔時，**避免 PowerShell 的 `>`／`Out-File`**（可能寫成 UTF-16 或加 BOM）；需要時用 `Set-Content -Encoding utf8NoBOM`，或在 bash 用 `printf`／heredoc。
+  - **commit 訊息**：用 `git commit -m` 直接帶字串，或寫進 UTF-8 無 BOM 的檔案再 `git commit -F <file>`；確保 `git config i18n.commitEncoding utf-8`。
+  - **API body**：以 UTF-8 JSON 檔帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓對方顯示字面 `\n`。
+  - **送出前自我檢查**：產生含繁中的檔案／訊息後，回頭確認沒有亂碼或 BOM 再提交／送出。
+- 若 skill 使用特定 emoji（如等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅），須確保正常顯示。
+
+## 表格與圖形優先
+
+- 面向使用者的輸出與寫入議題的內容（需求彙整、清單、進度回報），優先以 **Markdown 表格**與 **Mermaid 圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）呈現，讓使用者一眼看懂意圖。
+- 圖表必須忠實反映實際內容，**不得杜撰**未提及的流程或資料。
+
+## 個資保護（PII）
+
+- 寫入外部系統的內容（議題、留言、PR、文件）**不得洩漏個資（PII）**；若來源內容含個資，僅保留必要資訊或去識別化。
+
+## 派發 subagent 時
+
+- 須把本規範一併寫入每個 subagent 的提示，確保各 subagent 回傳的內容同樣是繁體中文、無亂碼。

skills/spec-plugin-version/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: spec-plugin-version
+description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、新 plugin 首發 0.0.1、一般變更 patch +1、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc:spec-plugin-version、或要調整任一 JSC plugin（code／doc／generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-plugin-version — 共用 plugin 版號規則
+
+調整任一 JSC plugin（code／doc／generic 等）的版本號時，一律遵守以下規則。
+
+## 三個 manifest 同步 bump
+
+- 版本號同時存在於三個 manifest：`plugin.json`（Antigravity）、`.claude-plugin/plugin.json`（Claude Code）、`.codex-plugin/plugin.json`（Codex）。
+- **三者必須一起 bump 且版本一致**，不得只改其中一個 —— 四家助理都以 git 內容／版本判斷是否有更新。
+- `.claude-plugin/marketplace.json`／`.agents/plugins/marketplace.json` 沒有版本欄位，不需改。
+
+## 版本單調遞增（以發佈分支為準）
+
+- bump 前**先確認發佈分支（`master`）目前的版本**，不能只看目前工作分支：
+
+  ```bash
+  git show origin/master:plugin.json | grep version
+  ```
+
+- 新版本必須**大於 master 現行版本**。工作分支（如 `develop`）可能落後或經過 revert，直接在其舊版本上 +1 會讓版本倒退（例：master 已 `0.0.4`，develop 還在 `0.0.1`，此時應 bump 至 `0.0.5` 而非 `0.0.2`）——已安裝 `0.0.4` 的助理會因版本倒退而抓不到更新。
+- 同一 PR／同一批變更只需最終一個版本；多次修改不必逐次 bump。
+
+## 版號選擇
+
+- **新 plugin 首發**：`0.0.1`（即使是從 template 複製建立，也要把 template 殘留的版本改回 `0.0.1`）。
+- **一般變更**（skill 新增／修改／移除、manifest 設定調整）：patch +1。
+- **重大改版**（skill 大規模重構、破壞相容的呼叫方式變更）：minor +1、patch 歸零。
+
+## 何時必須 bump
+
+- 任何希望四家助理拿到更新的變更都要 bump：skill 內容異動、新增／移除 skill、manifest 設定變更、README 的 Skills 目錄實質變更。
+- 純粹不影響安裝內容的變更（如 `.gitea/` CI 設定）可不 bump。
+
+## commit 與發佈
+
+- 版本 bump 的 commit 訊息：`chore(plugin 版本): 三家 manifest 升版 X.Y.Z`（僅含 3 個 manifest 的版本變更；與其他設定異動混提時說明清楚）。
+- 合併發佈後，各助理的更新方式見該 plugin README（`claude plugin update`／`codex plugin marketplace upgrade`／Antigravity 重新安裝／OpenCode 重新複製 `skills/`）。

skills/spec-project-board/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: spec-project-board
+description: JSC plugins 共用「Gitea 專案看板進度欄位規範」：欄位語意對應（分析中／待處理／進行中／待測試／已完成，以看板實際欄位名稱為準）、依需求與 TODO 勾稽結果建議欄位、先 GET 探測 project/column API（404/501 視為不支援、不對未確認端點寫入）、不往回移、不支援時改列建議清單請人工拖曳、不得新建欄位。當其他 skill 內文引用 spec-project-board 或 /jsc:spec-project-board、或需要調整 Gitea 議題所在看板欄位時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-project-board — 共用 Gitea 看板進度欄位規範
+
+JSC skills 調整議題所在的專案看板（project board）欄位時，一律遵守以下規範。
+
+## 欄位語意對應
+
+- 看板欄位名稱可對應進度語意時才操作，例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，語意相近即可對應，**不得假設看板一定有這五欄**。
+- 依議題狀態建議欄位的預設規則：
+
+  | 議題狀態 | 建議欄位 |
+  | --- | --- |
+  | 需求仍不明確、TODO 明顯不足以追蹤需求而需大量補列 | 分析中 |
+  | 需求與 TODO 齊全，但尚無任何對應實作 | 待處理 |
+  | 部分 TODO 已完成（已有部分實作） | 進行中 |
+  | 所有 TODO 已完成，但仍有「需人工確認」項目或尚待驗證 | 待測試 |
+  | 所有 TODO 已完成且無需人工確認（僅在使用者確認時） | 已完成 |
+
+- **不往回移**：議題已在建議欄位或更後面的欄位時維持原欄位，不往回移動。
+
+## 介面探測與寫入限制
+
+- `tea` 目前**沒有** project 看板指令；Gitea REST 的 project／column 端點依版本而異。
+- 移動前先以 GET 探測端點是否存在（回 404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。
+- 介面可用 → 一次一個議題移動並確認回應成功。
+- 介面不支援、看板沒有可對應語意的欄位、或欄位語意對不上 → **不移動、不視為錯誤**：改在回報（或議題留言）中列出「議題 → 建議欄位」建議清單，請使用者到看板手動拖曳。
+- **不得新建欄位**；只在建議欄位確實存在於看板且語意對應明確時移動，有疑慮就不動並回報。

skills/spec-time-log/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: spec-time-log
+description: JSC plugins 共用「時間戳與輸出訊息格式規範」：更新時間一律台灣時區（Asia/Taipei）固定 yyyy/MM/dd HH:mm:ss、寫成檔內固定字串、流程完成後統一同步各處時間戳；輸出訊息統一為 [yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息（等級 INF/WRN/ERR/TRC/DBG）、一行一則。當其他 skill 內文引用 spec-time-log 或 /jsc:spec-time-log、或需要產生更新時間／統一 log 格式時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-time-log — 共用時間戳與訊息格式規範
+
+## 更新時間
+
+- 一律使用**台灣時區（Asia/Taipei）**並固定為 `yyyy/MM/dd HH:mm:ss`，例如 `2026/06/30 18:30:05`。取得方式：
+
+  ```bash
+  TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
+  ```
+
+- 寫入檔案（橫幅、標頭註解、README）的更新時間語意為「本檔最後由 skill 產生／更新的時間」，**寫成檔內固定字串**（非執行期動態時間）。
+- 多階段流程中先寫入暫定時間戳即可；**全部完成後以完成當下的時間回頭統一同步各處時間戳**（橫幅、標頭註解區塊、README），確保各處一致。
+
+## 輸出訊息格式
+
+function 或指令檔若有輸出訊息（log、console 輸出、echo、提示訊息），格式必須統一為：
+
+```
+[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息
+```
+
+- `階段`：選填，沿用該訊息所屬區塊的原始名稱並**保留原文不翻譯**；無對應階段則移除整個 `[階段]` 區塊。
+- `等級`：限 `INF`／`WRN`／`ERR`／`TRC`／`DBG` 其中之一。
+- `時間`：Asia/Taipei，固定 `yyyy/MM/dd HH:mm:ss`。
+- 調整訊息格式僅限「訊息呈現方式」，**不得改變訊息反映的實際行為或判斷邏輯**。
+
+## 區塊階段命名與一行一則
+
+- 被格式化的 log 若包在有名稱的區塊內（原始碼的 `#region 名稱`、指令檔以「分隔線＋標題＋分隔線」宣告的橫幅段落），須將區塊名稱作為該段每則 log 的 `階段` 前綴，並**移除該包裹／橫幅本身**（僅移除標記，保留區塊內原有指令與行為）。
+- **例外**：檔案開頭「用途／更新日期」的說明標頭（含外框分隔線）屬檔案標頭、不是階段區塊，必須原樣保留。
+- **一行一則**：每則訊息必須是獨立的單行輸出指令；不得用多行字串、字串拼接或迴圈外包裹把多則訊息包成一個輸出。原本包成一坨的必須拆成逐行逐則，且每則仍套用統一格式。