diff --git a/README.md b/README.md index c108cd7..bc5845e 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,11 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安 ### `skill-new` -新建技能:決策樹問細節(目標、觸發、輸入輸出、domain)→ 缺 domain 時依 template 結構建立新存取庫 → sub agent 依準則產生技能 → 審核清單自檢 → PR。 +新建技能:決策樹問細節(目標、觸發、輸入輸出、domain)→ 缺 domain 時依 template 結構建立新存取庫 → sub agent 依準則產生技能 → 審核清單自檢 → PR,並依 `references/pr-report.md` 回報。 ### `skill-update` -更新技能:先查 Gitea 正本 marketplace 取得 domain 清單並補 clone 缺少的存取庫,列出全部技能 → 使用者選擇 → 決策樹問更新細節 → 更新後依審核檢查清單逐項檢查,不符就回到詢問 → PR。 +更新技能:先查 Gitea 正本 marketplace 取得 domain 清單並補 clone 缺少的存取庫,列出全部技能 → 使用者選擇 → 決策樹問更新細節 → 更新後依審核檢查清單逐項檢查,不符就回到詢問 → PR,並依 `references/pr-report.md` 回報。 ### `skill-delete` @@ -38,11 +38,11 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安 ### `skillset-update` -批次更新——把一份變更需求套用到整個技能組的多個技能/domain,先檢查工具化、sub agent 與環境變數優先規則,再逐 repo 開 PR;單一技能改用 skill-update。 +批次更新——把一份變更需求套用到整個技能組的多個技能/domain,先檢查工具化、sub agent 與環境變數優先規則,再逐 repo 開 PR;PR 回報格式見 `references/pr-report.md`;單一技能改用 skill-update。 ### `skill-check` -例行稽核——沒有變更需求時,把整個技能組逐一對照準則的審核檢查清單:sub agent 逐 domain 稽核 → 不符項目逐項決策樹確認 → sub agent 套用修正並複檢 → 逐 repo 開 PR。有變更需求改用 skillset-update。 +例行稽核——沒有變更需求時,把整個技能組逐一對照準則的審核檢查清單,再分開跑流程優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門;不符項目與優化建議分開回報,逐項決策樹確認後才套用,最後逐 repo 開 PR。有變更需求改用 skillset-update。 ### `ste100-sync` diff --git a/references/guidelines.md b/references/guidelines.md index 6553f0d..2bab5c0 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -27,6 +27,8 @@ 5. 功能主幹 `{類型}/{功能}/main` 不在 origin 上時,自動從 `develop` 建立並推上去,收尾要回報建立了哪一條分支。 6. 階梯最後一級不能省:`develop` 併進 `master` 才會生效,marketplace 與 `version-guard.sh` 都讀存取庫的**預設分支**。 +PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-report.md`](pr-report.md)。所有會產生 PR 的技能都引用那份文件,不在技能內各自抄欄位。 + ## Description 規則 1. frontmatter 的 `description` 為一行英文,不超過 5 句或 5 個步驟——**兩個上限滿足任一個就算通過**,句數與步驟數都超過才要精簡。 diff --git a/references/pr-report.md b/references/pr-report.md new file mode 100644 index 0000000..3e0b263 --- /dev/null +++ b/references/pr-report.md @@ -0,0 +1,36 @@ +# PR 收尾回報 + +所有會建立或更新 PR 的技能都用本頁格式回報。不要在各技能複製欄位定義。 + +## PR 資訊表格 + +只要本輪建立 PR、找到既有 PR,或更新既有 PR,就在回報中列出同一張表。 + +| {owner}/{repo} | PR 編號 | PR 連結 | PR 簡述 | +| --- | --- | --- | --- | +| `{owner}/{repo}` | `{number}` | `{url}` | `{title or one-line summary}` | + +同一輪有多支 PR 時,全部放在同一張表。沒有 PR 時不要印空表,改用一句話說明沒有建立或更新 PR。 + +## 留言回覆 + +依 PR 留言完成修正、判定不需修正,或判定無法修正後,必須回覆原留言。 + +回覆一律走 `jsc-gitea/tools/gitea.sh comment-reply`。不要自行拼 API。 + +`pr-comments` 第三欄會標出留言類型與 id。呼叫 `comment-reply` 時使用下列對應。 + +| `pr-comments` 第三欄 | `comment-reply` 類型 | +| --- | --- | +| `留言#{id}` | `issue` | +| `審查#{id}` | `review` | +| `行內#{id}(...)` | `inline` | + +回覆內容固定包含兩項: + +| 項目 | 內容 | +| --- | --- | +| 處理結果 | 已修、不需修,或無法修 | +| 依據 | commit、檔案,或不修理由 | + +完成條件:本輪處理過的每一則留言,都有對應的回覆連結或明確的回覆失敗原因。 diff --git a/skills/skill-delete/SKILL.md b/skills/skill-delete/SKILL.md index 47ec08d..8a30677 100644 --- a/skills/skill-delete/SKILL.md +++ b/skills/skill-delete/SKILL.md @@ -27,7 +27,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references - Exit 0 — no leftover in the locations listed on stderr. 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. +8. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back and is reported with the table format in `references/pr-report.md`. 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. diff --git a/skills/skill-new/SKILL.md b/skills/skill-new/SKILL.md index de370af..f45e7d6 100644 --- a/skills/skill-new/SKILL.md +++ b/skills/skill-new/SKILL.md @@ -33,7 +33,7 @@ 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. +5. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back and is reported with the table format in `references/pr-report.md`. 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. diff --git a/skills/skill-update/SKILL.md b/skills/skill-update/SKILL.md index 990cb66..f21ad9f 100644 --- a/skills/skill-update/SKILL.md +++ b/skills/skill-update/SKILL.md @@ -15,7 +15,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references 4. Ask for update details via the `jsc-ask:ask` decision tree (change the goal? the trigger? the flow? move rules down to a hook or a tool?). Every option states its impact scope (example: renaming breaks the existing invocation command). Completion condition: every question has a recorded answer. 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. +7. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back and is reported with the table format in `references/pr-report.md`. 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. diff --git a/skills/skillset-update/SKILL.md b/skills/skillset-update/SKILL.md index cc7f7e4..06f6fc4 100644 --- a/skills/skillset-update/SKILL.md +++ b/skills/skillset-update/SKILL.md @@ -13,7 +13,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references 2. 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. 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. +5. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL, and all URLs are reported in one table with the format in `references/pr-report.md`. 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. diff --git a/skills/ste100-sync/SKILL.md b/skills/ste100-sync/SKILL.md index 1ff836e..fc52c40 100644 --- a/skills/ste100-sync/SKILL.md +++ b/skills/ste100-sync/SKILL.md @@ -24,7 +24,7 @@ Keep `references/ste100.md` in sync with its upstream source, [speak-human-tw](h 7. If the replacement table or the cliché list changed, update the `TERMS`, `CLICHES` and `SIMPLIFIED` patterns in `tools/ste100-lint.sh`. Completion condition: `sh -n tools/ste100-lint.sh` passes and each newly adopted term hits on a test string. 8. Run `tools/ste100-lint.sh` over every jsc repo (`tools/sync-domains.sh` prints the repo paths). Fix hits in files this repo owns. Completion condition: the lint exits 0 for this repo, and hits in other repos are reported with `file:line` for their owners. 9. Run `tools/sync-skill-manifest.sh .` to sync the README's 「Skills 目錄」 section and bump the manifests. Completion condition: all three manifests show the same new version. -10. Open a PR via `jsc-git:pr`. Completion condition: a PR URL comes back. +10. Open a PR via `jsc-git:pr`. Completion condition: a PR URL comes back and is reported with the table format in `references/pr-report.md`. ## Notes