diff --git a/references/tdd.md b/references/tdd.md new file mode 100644 index 0000000..9a1acc8 --- /dev/null +++ b/references/tdd.md @@ -0,0 +1,17 @@ +# TDD 參考（拆解待辦與逐項實作時引用） + +## 接縫（Seam） + +測試只寫在**接縫**：可觀察行為的公開介面，不綁內部實作。拆解待辦前先列出受測接縫，依 `jsc-ask:ask` 與使用者確認；未確認的接縫不寫測試，測試力道集中在關鍵路徑與複雜邏輯。 + +## 循環規則 + +1. **先紅後綠**：先寫會失敗的測試，再寫剛好通過的實作；不預寫未來的測試、不加投機功能。 +2. **一次一片（vertical slice）**：一個接縫、一個測試、一個最小實作為一個循環；下一片依上一片學到的調整。 +3. **重構不在循環內**：重構屬於審查階段（`jsc-review:code-review`），不混入紅綠循環。 + +## 反模式（發現即重寫該測試） + +- **綁實作**：mock 內部協作者、測私有方法、繞過介面從旁通道驗證。徵兆：重構沒改行為，測試卻壞了。 +- **套套邏輯**：斷言用與實作相同的方式重算期望值，永遠通過。期望值必須來自獨立的真實來源（已知正確的字面值、規格、實算範例）。 +- **水平切片**：先寫完全部測試再寫全部實作。這是在測想像中的形狀；改用垂直切片逐一循環。 diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md new file mode 100644 index 0000000..be4ab9b --- /dev/null +++ b/skills/analyze/SKILL.md @@ -0,0 +1,34 @@ +--- +name: analyze +description: SDLC analysis stage. Gate on model capability tags, pick a plan from PLAN_CONTENTS, analyze user stories against the current state (working directory plus REPO_{HASH} inventory for reuse). Run WBS to produce numbered work packages, estimate them with CPM, split each into TDD todos, and write wiki page ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}. Logic only - never write code or modify files. Use after planning and before implementation. +--- + +# analyze — 分析 + +目標：產出或補充 WIKI 分析頁 `ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}`。 +本技能是**純邏輯**階段：不可以出現任何程式碼，也**禁止修改任何檔案**。 + +`{HASH}` = `{owner}/{repo}` 的 SHA-1 前 8 碼、大寫。 +所有 wiki 讀寫一律經由 `jsc-gitea:wiki`。 + +## 流程 + +1. **模型能力檢查**：依 `jsc-cli:models` 的能力標籤確認目前模型具備「分析」能力。不適合就阻擋流程，並告知使用者建議改用的模型。 +2. 經由 `jsc-gitea:wiki` 讀取 `PLAN_CONTENTS` 的**未分析**計畫（名稱 + HASH），並讀取 `ANALYZE_CONTENTS` 的既有分析。 +3. 依 `jsc-ask:ask` 規則讓使用者選擇：**補充既有分析**或**分析新計畫**。每個選項標明影響範圍。 +4. 搭配**現況**，依 `jsc-ask:ask` 決策樹逐條分析計畫頁的使用者故事，直到補全所有疑慮；只要還沒達成共識就繼續詢問。現況定義： + 1. 工作目錄的所有檔案。 + 2. **盡量複用既有方法或端點**： + - 優先查 `REPO_{HASH}` 盤點頁。若功能與端點不存在，或紀錄的 commit sha 與目前不同，就重新盤點。 + - 重新盤點**必須以 sub agent 執行**：分析該存取庫的功能與端點，加上目前 commit sha，套用 `templates/repo-page.md` 寫回 `REPO_{HASH}`，並依 `templates/repo-contents.md` 更新 `REPO_CONTENTS`。 + - 對候選的複用目標，先確認檔案路徑與方法名稱，再分析其邏輯是否符合需求。 +5. 執行**工作分解結構（WBS）**：把使用者故事拆成工作包，每個工作包給編號（`WP-01`、`WP-02`…）並標明相依關係。 +6. 以**關鍵路徑法（CPM）**估算每個工作包的工時與天數，標出關鍵路徑。 +7. 以**測試驅動開發（TDD）**把每個工作包拆解成多個待辦事項，格式 `[ ]`（未完成）/ `[x]`（完成），每項為一個垂直切片（一個接縫、一個測試、一個最小實作）；接縫與反模式見 `references/tdd.md`。 +8. 套用 `templates/analyze-page.md` 產生或更新分析頁，經由 `jsc-gitea:wiki` 寫回。 +9. 若是新的分析頁：依 `templates/analyze-contents.md` 加入 `ANALYZE_CONTENTS`，並把 `PLAN_CONTENTS` 對應計畫的狀態改為「已分析」。 + +## 禁止事項 + +- 不可輸出任何程式碼片段（檔案路徑與方法名稱可以）。 +- 不可修改工作目錄的任何檔案。 diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md new file mode 100644 index 0000000..665c313 --- /dev/null +++ b/skills/implement/SKILL.md @@ -0,0 +1,26 @@ +--- +name: implement +description: SDLC implementation stage. Gate on model capability tags, claim a ready work package from ANALYZE_CONTENTS with a work ticket, then complete its TDD todos one by one, updating the wiki after every item. Ends with jsc-review code-review and an optional MAINTAIN_CONTENTS entry. Use when analysis is done and code must be written; not for planning or analysis. +--- + +# implement — 實作 + +目標：逐項完成分析頁的待辦事項；**每完成一項就必須立即更新 WIKI 狀態**。 +所有 wiki 讀寫一律經由 `jsc-gitea:wiki`。 + +## 流程 + +1. **模型能力檢查**：依 `jsc-cli:models` 的能力標籤確認目前模型具備「實作」能力。不適合就阻擋流程，並告知使用者建議改用的模型。 +2. **產生工作證**：格式 `TICKET_{session id 前 8 碼}_{yyyyMMddHHmmss}`，並嘗試將目前 session 重新命名為工作證名稱（CLI 不支援時略過）。 +3. 經由 `jsc-gitea:wiki` 讀取 `ANALYZE_CONTENTS`，列出未完成的：計畫名稱 + HASH + 工作包編號 + 未完成項目數量。可選的工作包必須同時滿足：**未完成、無相依（或相依都已完成）、無工作證**。 +4. 依 `jsc-ask:ask` 規則讓使用者選擇要實作的工作包（選項標明未完成項目數與預估工時）。把工作證寫入分析頁該工作包的「工作證」欄位並寫回 wiki，**成功標上工作證才可以進入下一步**。 +5. 列出該工作包所有未完成項目，**逐項實作**： + - 依 TDD 循環：先紅後綠、一次一片；規則與反模式見 `references/tdd.md`（重構留給審查階段）。 + - 每完成一項，立即把分析頁該項 `[ ]` 改為 `[x]` 並寫回 wiki，才可以進行下一項。 +6. 全部完成後呼叫 `jsc-review:code-review` 等待程式碼審查；審查未過就修正並重新審查。 +7. 依 `jsc-ask:ask` 規則詢問是否將本專案加入維護：套用 `templates/maintain-contents.md` 加入 `MAINTAIN_CONTENTS`。必填：存取庫名稱 `{owner}/{repo}`、維護方式、維護起始日。選填：維護截止日（NULL = 永久維護）、前次維護時間。 + +## 規則 + +- 工作證是互斥鎖：看到已有工作證的工作包一律跳過，不可搶占。 +- 不可一次完成多項才批次更新 wiki；一項一更新。 diff --git a/skills/maintain/SKILL.md b/skills/maintain/SKILL.md new file mode 100644 index 0000000..c78b78c --- /dev/null +++ b/skills/maintain/SKILL.md @@ -0,0 +1,26 @@ +--- +name: maintain +description: SDLC maintenance stage. Gate on model capability tags, read projects still inside their maintenance window from MAINTAIN_CONTENTS, then run one sub agent per project: switch to develop or master, propose at least five maintenance actions, commit to a new branch, push, and PR. Update the last-maintained timestamp afterward. Use for periodic upkeep of delivered projects. +--- + +# maintain — 維護 + +目標：逐項完成維護目錄內專案的例行維護。 +所有 wiki 讀寫一律經由 `jsc-gitea:wiki`。 + +## 流程 + +1. **模型能力檢查**：依 `jsc-cli:models` 的「SDLC 階段需求」表確認目前模型適合維護階段（維護接受任意標籤，但模型必須列於對照表）。不適合就阻擋流程，並告知使用者建議改用的模型。 +2. 經由 `jsc-gitea:wiki` 讀取 `MAINTAIN_CONTENTS`，篩出**仍在維護期間內**的專案：維護起始日 ≤ 今天，且（維護截止日為 NULL 或 ≥ 今天）。 +3. 每一個專案**必須啟動一個 sub agent** 依以下流程執行： + 1. 將專案切換到 `develop` 分支，沒有就切 `master`，並更新到最新。 + 2. 提供**至少五種**建議的維護方法，依專案狀況取捨執行，例如： + - 相依套件更新（複用 `jsc-pkg:pkg-update`） + - 安全性弱點掃描與修補 + - 死碼與過期註解清理 + - 測試覆蓋率補強 + - 文件與 README 同步 + - 建置警告消除 + 3. 依 `jsc-git:commit` 把變更 commit 到新分支，push 後依 `jsc-git:pr` 建立 PR 回 develop 或 master。 + 4. 更新 `MAINTAIN_CONTENTS` 中該專案的「前次維護時間」為今天。 +4. 主 agent 彙整回報：每個專案執行了哪些維護方法、PR 連結、失敗原因。 diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md new file mode 100644 index 0000000..af399b8 --- /dev/null +++ b/skills/plan/SKILL.md @@ -0,0 +1,31 @@ +--- +name: plan +description: SDLC planning stage. Gate on model capability tags, pick or create a plan from PLAN_CONTENTS, then run a decision tree until goal, scope, and feasibility reach consensus. Produce user stories into wiki page PLAN_{yyyyMMdd}_{HHmmss}_{HASH}. Logic only - never write code or modify files. Use when the user wants to start or refine a plan; not for analysis or implementation. +--- + +# plan — 規劃 + +目標：產出或補充 WIKI 計畫頁 `PLAN_{yyyyMMdd}_{HHmmss}_{HASH}`。 +本技能是**純邏輯**階段：不可以出現任何程式碼，也**禁止修改任何檔案**。 + +`{HASH}` = `{owner}/{repo}` 的 SHA-1 前 8 碼、大寫。 +所有 wiki 讀寫一律經由 `jsc-gitea:wiki`。 + +## 流程 + +1. **模型能力檢查**：依 `jsc-cli:models` 的能力標籤確認目前模型具備「規劃」能力。不適合就阻擋流程，並告知使用者建議改用的模型。 +2. 經由 `jsc-gitea:wiki` 讀取 `PLAN_CONTENTS`，列出**未分析**的計畫名稱 + HASH。 +3. 依 `jsc-ask:ask` 規則讓使用者選擇：**補充既有計畫**（列出未分析計畫為選項）或**新建計畫**。每個選項標明影響範圍。 +4. 依 `jsc-ask:ask` 決策樹詢問，補全以下三項直到沒有疑慮；只要還沒達成共識就繼續詢問： + - 計畫目標：要解決什麼問題、成功的判斷標準。 + - 計畫範圍：包含什麼、排除什麼、涉及哪些存取庫。 + - 可行性：系統架構與資料來源是否支撐目標。 +5. 由共識產生**使用者故事**（身為…我想要…以便…），逐條列出。 +6. 套用 `templates/plan-page.md` 產生或更新計畫頁，經由 `jsc-gitea:wiki` 寫回。 +7. 若是新的計畫頁，套用 `templates/plan-contents.md` 的條目格式，將其加入 `PLAN_CONTENTS`（狀態=未分析）。 + +## 禁止事項 + +- 不可輸出任何程式碼片段。 +- 不可修改工作目錄的任何檔案。 +- 不可跳過決策樹直接假設需求。 diff --git a/templates/analyze-contents.md b/templates/analyze-contents.md new file mode 100644 index 0000000..4fcecb9 --- /dev/null +++ b/templates/analyze-contents.md @@ -0,0 +1,5 @@ +# 分析目錄 + +| 計畫名稱 | 分析頁 | HASH | 工作包 | 未完成項目 | 狀態 | +| --- | --- | --- | --- | --- | --- | +| {計畫名稱} | [[ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}]] | {HASH} | WP-01, WP-02 | {n} | 未完成 | diff --git a/templates/analyze-page.md b/templates/analyze-page.md new file mode 100644 index 0000000..42ca3d4 --- /dev/null +++ b/templates/analyze-page.md @@ -0,0 +1,33 @@ +# 分析：{計畫名稱} + +- 頁名：`ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}` +- 對應計畫：[[PLAN_{yyyyMMdd}_{HHmmss}_{HASH}]] +- 存取庫：`{owner}/{repo}` +- 狀態：未完成 + +## 現況摘要 + +- 工作目錄：{關鍵檔案與結構摘要} +- 複用來源：[[REPO_{HASH}]]（commit sha：`{sha}`） +- 複用決策：{複用哪些方法/端點、為什麼；不複用的原因} + +## 工作分解結構（WBS） + +| 編號 | 工作包名稱 | 相依 | 工時(h) | 天數 | 工作證 | 狀態 | +| --- | --- | --- | --- | --- | --- | --- | +| WP-01 | {名稱} | - | {h} | {d} | | 未完成 | +| WP-02 | {名稱} | WP-01 | {h} | {d} | | 未完成 | + +- 關鍵路徑：{WP-01 → WP-02 → …}，總天數 {d} + +## 待辦事項（TDD） + +### WP-01 {工作包名稱} + +- [ ] 撰寫 {對象} 的測試：{預期行為} +- [ ] 實作 {對象} 使測試通過 +- [ ] 重構 {對象} 並保持測試綠燈 + +### WP-02 {工作包名稱} + +- [ ] … diff --git a/templates/maintain-contents.md b/templates/maintain-contents.md new file mode 100644 index 0000000..57a1330 --- /dev/null +++ b/templates/maintain-contents.md @@ -0,0 +1,7 @@ +# 維護目錄 + + + +| 存取庫 | 維護方式 | 維護起始日 | 維護截止日 | 前次維護時間 | +| --- | --- | --- | --- | --- | +| {owner}/{repo} | {例：套件更新+安全掃描} | {yyyy-MM-dd} | NULL | {yyyy-MM-dd} | diff --git a/templates/plan-contents.md b/templates/plan-contents.md new file mode 100644 index 0000000..cbbcb5d --- /dev/null +++ b/templates/plan-contents.md @@ -0,0 +1,5 @@ +# 計畫目錄 + +| 計畫名稱 | 計畫頁 | 存取庫 | HASH | 狀態 | 建立時間 | +| --- | --- | --- | --- | --- | --- | +| {計畫名稱} | [[PLAN_{yyyyMMdd}_{HHmmss}_{HASH}]] | {owner}/{repo} | {HASH} | 未分析 | {yyyy-MM-dd} | diff --git a/templates/plan-page.md b/templates/plan-page.md new file mode 100644 index 0000000..3cfb0ab --- /dev/null +++ b/templates/plan-page.md @@ -0,0 +1,31 @@ +# 計畫：{計畫名稱} + +- 頁名：`PLAN_{yyyyMMdd}_{HHmmss}_{HASH}` +- 存取庫：`{owner}/{repo}` +- 狀態：未分析 +- 建立時間：{yyyy-MM-dd HH:mm:ss} + +## 目標 + +{要解決的問題與成功判斷標準} + +## 範圍 + +- 包含：{項目} +- 排除：{項目} +- 涉及存取庫：{owner}/{repo} 清單 + +## 可行性 + +- 系統架構：{現有架構如何支撐目標} +- 資料來源：{資料從哪裡來、是否可取得} +- 風險：{已知風險與對策} + +## 使用者故事 + +1. 身為 {角色}，我想要 {功能}，以便 {價值}。 +2. … + +## 問詢共識 + +{決策樹問答達成的關鍵共識摘要，逐條列出} diff --git a/templates/repo-contents.md b/templates/repo-contents.md new file mode 100644 index 0000000..711a102 --- /dev/null +++ b/templates/repo-contents.md @@ -0,0 +1,5 @@ +# 盤點目錄 + +| 存取庫 | 盤點頁 | HASH | commit sha | 盤點時間 | +| --- | --- | --- | --- | --- | +| {owner}/{repo} | [[REPO_{HASH}]] | {HASH} | `{sha}` | {yyyy-MM-dd} | diff --git a/templates/repo-page.md b/templates/repo-page.md new file mode 100644 index 0000000..57c8967 --- /dev/null +++ b/templates/repo-page.md @@ -0,0 +1,11 @@ +# 盤點：{owner}/{repo} + +- 頁名：`REPO_{HASH}` +- commit sha：`{sha}` +- 盤點時間：{yyyy-MM-dd HH:mm:ss} + +## 功能與端點 + +| 檔案路徑 | 方法/端點名稱 | 類型 | 邏輯摘要 | +| --- | --- | --- | --- | +| {path} | {method 或 HTTP 動詞 + 路由} | 方法 \| 端點 | {做什麼、輸入輸出概要} |