From cd95c22bd4053f1b43bbc4eccdd6b4719bd09f55 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 18:59:59 +0800 Subject: [PATCH 1/6] =?UTF-8?q?feat(implement):=20implement=20=E6=AD=A5?= =?UTF-8?q?=E9=A9=9F=E5=8A=A0=E4=B8=8A=E8=A8=BB=E8=A7=A3=E7=95=8C=E7=B7=9A?= =?UTF-8?q?=E8=A6=8F=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：步驟 9 新增 9.3「註解只寫原因」，原 9.3 順延為 9.4；步驟 10 交給 code-review 前先掃整包 diff。 Why：實作階段手上一直握著工作包編號、分析頁編號、待辦編號、分支名與 PR 編號，這些追蹤資訊很容易被寫進程式碼註解，讓註解變成文件索引。 How：規則正文放在 jsc-review 的 references/comment-scope.md，本技能只寫指引與完成條件，不重複清單；並指向 jsc-hooks 的 comment-scope.sh 當寫檔後的即時警告。 Who：jsc-sdlc 的 implement 技能。 --- skills/implement/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 790cee4..fb0aa0a 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -39,8 +39,9 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 9. **Complete the work package's open items one at a time. Every item MUST run as a sub agent**, working inside the worktree: 1. One sub agent takes one item and follows the TDD loop: red before green, one vertical slice. Rules and anti-patterns: `references/tdd.md` (refactoring belongs to the review stage). 2. The main agent keeps only the wiki bookkeeping: when the sub agent reports the item done, flip its `[ ]` to `[x]` on the analysis page and save to the wiki. - 3. Completion condition: every item of the package shows `[x]` on the saved analysis page, and each save happened before the next item's sub agent started. -10. When all items are done, call `jsc-review:code-review` and wait for the verdict. Each round of fixes **MUST run as a sub agent** inside the same worktree. Completion condition: the review passes. + 3. **A code comment states why the code is written this way; it never states where the work is documented.** The tracking numbers this stage always holds — the work package number, the analysis page number, the TDD todo number, the source branch name and the PR number — stay out of every code comment; write the reason itself into the comment instead. Full list and the allowed exceptions: `jsc-review/references/comment-scope.md`. `jsc-hooks/hooks/comment-scope.sh` compares each file after it is written and prints a warning; fix the flagged line at once, then carry on with the same item. Completion condition: the item's own diff holds no comment line carrying any of those numbers, and every warning the hook printed for this item is fixed. + 4. Completion condition: every item of the package shows `[x]` on the saved analysis page, and each save happened before the next item's sub agent started. +10. When all items are done, sweep the work package's whole diff for the comment rule of step 9.3, then call `jsc-review:code-review` and wait for the verdict. Each round of fixes **MUST run as a sub agent** inside the same worktree. Completion condition: the review passes, and the diff handed to it holds no comment line carrying the work package number, the analysis page number, a TDD todo number, the source branch name or a PR number (full list: `jsc-review/references/comment-scope.md`). 11. **One work package finished → commit, push, PR back to the source branch. Then stop and wait for that PR**: 1. Call `jsc-git:pr` from inside the worktree, **passing `{source-branch}` as the base branch**. One package, one PR; the branch rules behind that are in `references/branch.md`. 2. Write the PR URL and number into that work package's PR column on the analysis page and save it back to the wiki, so the next run of this skill can find it (step 4). -- 2.53.0 From e6e3e176ef0bdfee9ffcd59817ace58b66d4474d Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 19:00:07 +0800 Subject: [PATCH 2/6] =?UTF-8?q?feat(maintain):=20maintain=20=E6=AD=A5?= =?UTF-8?q?=E9=A9=9F=E5=8A=A0=E4=B8=8A=E8=A8=BB=E8=A7=A3=E7=95=8C=E7=B7=9A?= =?UTF-8?q?=E8=A6=8F=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：步驟 3 新增 3.3「註解只寫原因」，原 3.3、3.4 順延為 3.4、3.5。 Why：維護階段常改到既有註解，議題編號、commit hash、分支名、人名與 @ 提及很容易順手留在註解裡，讓註解變成追蹤記錄。 How：規則正文放在 jsc-review 的 references/comment-scope.md，本技能只寫指引與完成條件，不重複清單；並指向 jsc-hooks 的 comment-scope.sh 當寫檔後的即時警告。 Who：jsc-sdlc 的 maintain 技能。 --- skills/maintain/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/maintain/SKILL.md b/skills/maintain/SKILL.md index 84fc9da..1ff2bd1 100644 --- a/skills/maintain/SKILL.md +++ b/skills/maintain/SKILL.md @@ -23,7 +23,8 @@ All wiki reads and writes go through `jsc-gitea:wiki`. - build warning elimination Completion condition: the user has picked the methods to apply, and every picked method is either applied or reported with the reason it could not be. - 3. Commit the changes to a new branch per `jsc-git:commit`, push, then open a PR per `jsc-git:pr` back to the branch of step 3.1, passing it explicitly as the base. Completion condition: the PR exists, and you have reported its URL and number. - 4. Update the project's last-maintained field (the zh-TW column 「前次維護時間」) in `MAINTAIN_CONTENTS` to today. Completion condition: `MAINTAIN_CONTENTS` shows today's date in 「前次維護時間」 for that project, saved on the wiki. + 3. **A code comment states why the code is written this way; it never states where the work is tracked.** Issue numbers, commit hashes, branch names, people's names and `@` mentions stay out of every code comment this project's maintenance touches — including the comments the cleanup method rewrites. Full list and the allowed exceptions: `jsc-review/references/comment-scope.md`. `jsc-hooks/hooks/comment-scope.sh` compares each file after it is written and prints a warning; fix the flagged line at once, then carry on. Completion condition: this project's diff holds no comment line carrying an issue number, a commit hash, a branch name, a person's name or an `@` mention, and every warning the hook printed is fixed. + 4. Commit the changes to a new branch per `jsc-git:commit`, push, then open a PR per `jsc-git:pr` back to the branch of step 3.1, passing it explicitly as the base. Completion condition: the PR exists, and you have reported its URL and number. + 5. Update the project's last-maintained field (the zh-TW column 「前次維護時間」) in `MAINTAIN_CONTENTS` to today. Completion condition: `MAINTAIN_CONTENTS` shows today's date in 「前次維護時間」 for that project, saved on the wiki. 4. The main agent reports the summary: maintenance methods applied per project, PR links, and failure reasons. The report and all generated wiki content, commits, and PR descriptions stay Traditional Chinese per the STE100 rule. Completion condition: the summary names every project read in step 2, each with its applied methods and either a PR link or the reason it was skipped. 5. **Stage report — the last thing this stage does, including when no project was in window.** Run `tools/stage-report.sh maintain` with one `--page MAINTAIN:{page}` per wiki page this run wrote (`MAINTAIN_CONTENTS` counts), plus `--worklog` and `--worklog-heading` when a work log entry exists. No work log yet: write this stage's log content to a file and pass `--pending-file {file} --log-hash {HASH}` so it is held for the next `jsc-log:worklog` run. Rules and exit codes: `references/stage-report.md`. Exit 1 is a warning, never a block. Completion condition: the script's output is reported to the user verbatim, and every wiki page this run wrote appears in it. -- 2.53.0 From 31ba3f490a0714d27efb777969390693217cfecc Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 19:00:17 +0800 Subject: [PATCH 3/6] =?UTF-8?q?feat(tdd):=20TDD=20=E5=BE=AA=E7=92=B0?= =?UTF-8?q?=E8=A6=8F=E5=89=87=E6=96=B0=E5=A2=9E=E8=A8=BB=E8=A7=A3=E5=8F=AA?= =?UTF-8?q?=E5=AF=AB=E5=8E=9F=E5=9B=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：references/tdd.md 的循環規則新增第 4 項「註解只寫原因」，並寫成單一待辦的完成條件。 Why：註解界線要在紅綠循環當下就守住，不能等到審查階段才回頭清，否則追蹤編號早已散進整包 diff。 How：規則只寫一句界線加完成條件，完整清單與白名單指向 jsc-review 的 references/comment-scope.md。 Who：jsc-sdlc 的 TDD 參考文件，implement 與 maintain 兩支技能共用。 --- references/tdd.md | 1 + 1 file changed, 1 insertion(+) diff --git a/references/tdd.md b/references/tdd.md index 9a1acc8..b75b54c 100644 --- a/references/tdd.md +++ b/references/tdd.md @@ -9,6 +9,7 @@ 1. **先紅後綠**：先寫會失敗的測試，再寫剛好通過的實作；不預寫未來的測試、不加投機功能。 2. **一次一片（vertical slice）**：一個接縫、一個測試、一個最小實作為一個循環；下一片依上一片學到的調整。 3. **重構不在循環內**：重構屬於審查階段（`jsc-review:code-review`），不混入紅綠循環。 +4. **註解只寫原因**：一個待辦要算完成，該次 diff 的註解不得夾帶追蹤編號與文件位置。完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 ## 反模式（發現即重寫該測試） -- 2.53.0 From f503091655bea43b07df247cd399924c0a91305c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 19:00:26 +0800 Subject: [PATCH 4/6] =?UTF-8?q?feat(readme):=20README=20=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=20implement=20=E8=88=87=20maintain=20=E7=9A=84=E8=A8=BB?= =?UTF-8?q?=E8=A7=A3=E7=95=8C=E7=B7=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：README 的 implement 與 maintain 兩段說明各補一句註解界線，點出各自禁止寫進註解的追蹤資訊。 Why：README 是技能的對外說明，兩支技能已加規則，說明沒跟上就會讓使用者誤以為註解沒有限制。 How：兩段各補一句，內容與 SKILL.md 的指引一致，完整清單指向 jsc-review 的 references/comment-scope.md。 Who：jsc-sdlc 的 README 技能說明區塊。 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0716807..2e25454 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `implement` -實作：先確認來源分支（同時是 PR 目標）→ 領包前先跑 `tools/wp-gate.sh check` 把每個已開 PR 但沒合併的工作包留言逐筆印出並修正（以 sub agent 回原 worktree、推同一條工作分支，不開第二個 PR），**這一步只結清舊 PR 的留言，不擋別的工作包**——修不動或純討論的留言忽略但要在回報裡列出，處理過的時間戳寫回分析頁的 PR 欄位當下一輪的 `--since` → 產生工作證鎖定「未完成、無工作證」的候選工作包（交付工作包優先），**每個候選都跑 `tools/wp-gate.sh check-deps` 判斷能不能挑**：活查它在分析頁上的相依工作包是否都已合併，只有相依於它的包才會被一支未合併的 PR 擋住，跟它無關的工作包可以平行進行 → 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{wp-number}/{repo}`，一個工作包一個 worktree，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR），接著 `tools/wp-gate.sh lock` 上鎖，合併後解鎖並移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄 → 階段回報（`tools/stage-report.sh`，多報工作目錄與來源、工作、目標三條分支）。 +實作：先確認來源分支（同時是 PR 目標）→ 領包前先跑 `tools/wp-gate.sh check` 把每個已開 PR 但沒合併的工作包留言逐筆印出並修正（以 sub agent 回原 worktree、推同一條工作分支，不開第二個 PR），**這一步只結清舊 PR 的留言，不擋別的工作包**——修不動或純討論的留言忽略但要在回報裡列出，處理過的時間戳寫回分析頁的 PR 欄位當下一輪的 `--since` → 產生工作證鎖定「未完成、無工作證」的候選工作包（交付工作包優先），**每個候選都跑 `tools/wp-gate.sh check-deps` 判斷能不能挑**：活查它在分析頁上的相依工作包是否都已合併，只有相依於它的包才會被一支未合併的 PR 擋住，跟它無關的工作包可以平行進行 → 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{wp-number}/{repo}`，一個工作包一個 worktree，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR），接著 `tools/wp-gate.sh lock` 上鎖，合併後解鎖並移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄 → 階段回報（`tools/stage-report.sh`，多報工作目錄與來源、工作、目標三條分支）。寫程式碼時註解只寫「為什麼這樣寫」，工作包編號、分析頁編號、待辦編號、分支名、PR 編號一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。 ### `maintain` -維護：讀取維護期內的專案，每個專案一個 sub agent：fetch 後切 develop、master 並對齊 `origin/{branch}` → 提出至少五種維護方法，依決策樹讓使用者挑要做哪些 → commit / push / PR → 更新前次維護時間 → 階段回報（`tools/stage-report.sh`）。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。 +維護：讀取維護期內的專案，每個專案一個 sub agent：fetch 後切 develop、master 並對齊 `origin/{branch}` → 提出至少五種維護方法，依決策樹讓使用者挑要做哪些 → commit / push / PR → 更新前次維護時間 → 階段回報（`tools/stage-report.sh`）。sub agent 改程式碼時註解只寫「為什麼這樣寫」，議題編號、commit hash、分支名、人名與 `@` 提及一律不寫進註解，完整清單與白名單見 `jsc-review` 的 `references/comment-scope.md`。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。 -- 2.53.0 From 868e4345e9211caf8031a148e114ea7651c87b8d Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 19:00:36 +0800 Subject: [PATCH 5/6] =?UTF-8?q?feat(manifest):=20=E4=B8=89=E4=BB=BD=20mani?= =?UTF-8?q?fest=20=E7=89=88=E6=9C=AC=E5=8D=87=E5=88=B0=200.1.7?= 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.6 改為 0.1.7。 Why：本次為 implement、maintain 與 TDD 參考文件新增註解界線規則，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。 How：三份 manifest 只改 version 一個欄位，其餘內容不動，三份保持同一版號。 Who：jsc-sdlc 外掛的套件描述檔。 --- .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 71f759f..1c75006 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.6", + "version": "0.1.7", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 147bf53..4c2a539 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.6", + "version": "0.1.7", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 9c1eaeb..145bd1e 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.6", + "version": "0.1.7", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills/" } -- 2.53.0 From 78fb70a099fb9ac138985cf789eb4cc218c0a051 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 09:40:42 +0800 Subject: [PATCH 6/6] =?UTF-8?q?fix(references):=20=E4=BF=AE=E6=AD=A3=20cpm?= =?UTF-8?q?-chart=20=E7=9A=84=E7=B0=A1=E9=AB=94=E5=AD=97=E4=B8=A6=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=20manifest=20=E7=89=88=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What: 把 references/cpm-chart.md 第 14 行的「出现」改成正體「出現」， 並把三份 manifest 的版本由 0.1.7 bump 到 0.1.8。 Why: 存取庫文件一律用正體中文，簡體字會被 STE100 語言檢查擋下，也讓讀規則 的人分心。技能內容有異動就要 bump 版本，安裝端才拿得到新版。 How: 只換掉那一個字，句子其餘文意不動。接著跑 ste100-lint.sh 掃全庫的 .md、 .json 與程式碼檔，再用簡體字全表、U+FFFD、雙重編碼特徵與非 UTF-8 四項掃過每個 受版控的檔案，兩輪都零命中。最後用 sync-skill-manifest.sh 同步 plugin.json、 .claude-plugin/plugin.json、.codex-plugin/plugin.json。 Who: Jeffery Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- references/cpm-chart.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1c75006..b3e47b9 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.7", + "version": "0.1.8", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 4c2a539..1a84fc5 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.7", + "version": "0.1.8", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 145bd1e..0c3ad5a 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.1.7", + "version": "0.1.8", "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）", "skills": "./skills/" } diff --git a/references/cpm-chart.md b/references/cpm-chart.md index 8bf4d58..38cff48 100644 --- a/references/cpm-chart.md +++ b/references/cpm-chart.md @@ -11,7 +11,7 @@ 1. **`dateFormat` 固定用 `YYYY-MM-DD`，不用 `X`。** 第一個工作包給一個任意錨點日期（例如 `2000-01-01`），註明「錨點日期非真實排程，只用於相對呈現」。 2. **每個工作包一個 `id`**，格式 `wp01`、`wp02`……跟編號對應，全小寫、不帶連字號（mermaid id 不吃 `-`）。 3. **時長一律用整數小時 `{h}h`，直接取 WBS 表的工時(h) 欄位**，不得把工時換算成天數小數再填進圖裡。天數換算只留在標題與 WBS 表文字，圖本身不出現小數。 -4. **除了第一個工作包，其餘一律用 `after {上一個id}`** 串接，不手算累積日期。少算或算錯只會出现在這一步，串接法直接消掉這類錯誤。 +4. **除了第一個工作包，其餘一律用 `after {上一個id}`** 串接，不手算累積日期。少算或算錯只會出現在這一步，串接法直接消掉這類錯誤。 5. 關鍵路徑上的工作包標 `crit`；候補（非關鍵路徑）不進這張圖，只留在 WBS 表與候補清單文字。 ## 範本 -- 2.53.0