From 1153f7f064ff0479561a902af6b36b0ab002d6e5 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 16:53:17 +0000 Subject: [PATCH] =?UTF-8?q?fix(wiki):=20=E7=B5=B1=E4=B8=80=20SDLC=20wiki?= =?UTF-8?q?=20=E9=A0=81=E5=91=BD=E5=90=8D=E8=88=87=20ERROR=20=E7=AF=84?= =?UTF-8?q?=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- README.md | 11 +++++++---- plugin.json | 2 +- skills/analyze/SKILL.md | 6 +++--- skills/implement/SKILL.md | 13 +++++++------ skills/maintain/SKILL.md | 4 ++-- skills/plan/SKILL.md | 6 +++--- templates/analyze-contents.md | 2 +- templates/analyze-page.md | 6 ++++-- templates/error-contents.md | 9 +++++++++ templates/error-page.md | 33 +++++++++++++++++++++++++++++++++ templates/plan-contents.md | 2 +- templates/plan-page.md | 3 ++- templates/repo-contents.md | 2 +- templates/repo-page.md | 1 + 16 files changed, 77 insertions(+), 27 deletions(-) create mode 100644 templates/error-contents.md create mode 100644 templates/error-page.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9d70ac0..d087e35 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.0.1", + "version": "0.0.2", "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 02b5875..7be74c9 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.0.1", + "version": "0.0.2", "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）", "skills": "./skills" } diff --git a/README.md b/README.md index 9e13126..fce5bf4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # jsc-sdlc — 開發生命週期 -jsc 技能組的 sdlc domain：規劃 → 分析 → 實作 → 維護四個階段，全程以 wiki 頁追蹤（`PLAN_*`、`ANALYZE_*`、`REPO_*`、`MAINTAIN_CONTENTS`）。每階段先做模型能力檢查，不適合就阻擋流程。 +jsc 技能組的 sdlc domain：規劃 → 分析 → 實作 → 維護四個階段，全程以 wiki 頁追蹤（`PLAN_CONTENTS`、`PLAN_{HASH}`、`ANALYZE_CONTENTS`、`ANALYZE_{HASH}`、`REPO_CONTENTS`、`REPO_{HASH}`、`MAINTAIN_CONTENTS`）。另有異常頁（`ERROR_CONTENTS`、`ERROR_{HASH}`）記錄 hook 或流程失敗。每次切換階段才重新檢查該階段需要的模型能力標籤；同一階段內不重複變更。 ## 安裝、更新、移除 @@ -24,11 +24,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 ### `plan` -規劃：讀計畫目錄 → 補充或新建計畫 → 決策樹補全目標、範圍、可行性至共識 → 產生使用者故事 → 寫回 `PLAN_{yyyyMMdd}_{HHmmss}_{HASH}`。純邏輯，禁止程式碼與修改檔案。 +規劃：讀計畫目錄 → 補充或新建計畫 → 決策樹補全目標、範圍、可行性至共識 → 產生使用者故事 → 寫回 `PLAN_{HASH}`。純邏輯，禁止程式碼與修改檔案。 ### `analyze` -分析：搭配現況（工作目錄與 `REPO_{HASH}` 盤點複用）分析使用者故事 → WBS 產生編號工作包 → CPM 估工時與天數 → TDD 拆待辦 → 寫回 `ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}`。純邏輯，禁止程式碼與修改檔案。 +分析：搭配現況（工作目錄與 `REPO_{HASH}` 盤點複用）分析使用者故事 → WBS 產生編號工作包 → CPM 估工時與天數 → TDD 拆待辦 → 寫回 `ANALYZE_{HASH}`。純邏輯，禁止程式碼與修改檔案。 ### `implement` @@ -47,12 +47,15 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 | `templates/plan-page.md`、`templates/plan-contents.md` | 計畫頁與計畫目錄 | | `templates/analyze-page.md`、`templates/analyze-contents.md` | 分析頁（WBS、CPM、TDD 待辦）與分析目錄 | | `templates/repo-page.md`、`templates/repo-contents.md` | 存取庫盤點頁（功能與端點，附 commit sha）與盤點目錄 | +| `templates/error-page.md`、`templates/error-contents.md` | 異常頁與異常目錄 | | `templates/maintain-contents.md` | 維護目錄（截止日 NULL = 永久維護） | | `references/tdd.md` | 接縫、紅綠循環規則、反模式 | ## 環境變數 -Wiki 位置：`JSC_WIKI_REPO_PLAN` / `JSC_WIKI_REPO_ANALYZE` / `JSC_WIKI_REPO_REPO` / `JSC_WIKI_REPO_MAINTAIN`，未設定退回 `JSC_WIKI_REPO`，再未設定就詢問（見 `jsc-gitea`）。 +Wiki 位置：`PLAN_{HASH}` / `PLAN_CONTENTS` 只讀 `JSC_WIKI_REPO_PLAN`，再退回 `JSC_WIKI_REPO`；`ANALYZE_{HASH}` / `ANALYZE_CONTENTS` 只讀 `JSC_WIKI_REPO_ANALYZE`，再退回 `JSC_WIKI_REPO`；`REPO_{HASH}` / `REPO_CONTENTS` 只讀 `JSC_WIKI_REPO_REPO`，再退回 `JSC_WIKI_REPO`；`MAINTAIN_CONTENTS` 只讀 `JSC_WIKI_REPO_MAINTAIN`，再退回 `JSC_WIKI_REPO`。不同類型不可互相代用；兩者都未設定才詢問（見 `jsc-gitea`）。 + +HASH 規則：一律先算 `{owner}/{repo}` 的 SHA-1 前 8 碼並轉大寫；若第一碼是數字，或 `A`、`B`、`C`，就改成 `H` 加上原 SHA-1 前 7 碼，總長維持 8 碼。 ## 相關 domain diff --git a/plugin.json b/plugin.json index a285c44..4ce9145 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.0.1", + "version": "0.0.2", "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）", "skills": "./skills/" } diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index e823e13..7000f34 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -1,14 +1,14 @@ --- 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. +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_{HASH}. Logic only - never write code or modify files. Use after planning and before implementation. --- # analyze -Goal: create or extend the wiki analysis page `ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}`. +Goal: create or extend the wiki analysis page `ANALYZE_{HASH}`. This skill is a **logic-only** stage: never output code, and **never modify any file**. -`{HASH}` = first 8 chars of the SHA-1 of `{owner}/{repo}`, uppercase. +`{HASH}` = the shared wiki hash for `{owner}/{repo}`: take the first 8 uppercase hex chars of its SHA-1. If the first char is a digit, or `A`/`B`/`C`, replace it with `H` and keep the next 7 chars. All wiki reads and writes go through `jsc-gitea:wiki`. ## Steps diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index e02dc95..a7b20db 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -11,14 +11,15 @@ All wiki reads and writes go through `jsc-gitea:wiki`. ## Steps 1. **Model capability gate**: check the capability tags from `jsc-cli:models` and confirm the current model qualifies for implementation. If not, block the flow and tell the user which model to switch to. -2. **Generate a work ticket**: format `TICKET_{first 8 chars of session id}_{yyyyMMddHHmmss}`. Try to rename the current session to the ticket name (skip when the CLI does not support it). -3. Read `ANALYZE_CONTENTS` via `jsc-gitea:wiki` and list what is unfinished: plan name, HASH, work package number, count of open items. A selectable work package must satisfy all three: **unfinished, dependency-free (or all dependencies done), and not holding a work ticket**. -4. Let the user pick a work package per `jsc-ask:ask` rules (options state open-item count and estimated effort). Write the ticket into that work package's ticket column (the zh-TW field 「工作證」) on the analysis page and save it back to the wiki. **Only after the ticket is saved successfully may you proceed.** -5. List every open item of the work package and implement them **one at a time**: +2. **Resolve environment first**: inspect `JSC_WIKI_REPO_ANALYZE`, `JSC_WIKI_REPO`, `JSC_WIKI_REPO_QUESTION`, `GITEA_HOST`, and `GITEA_TOKEN` before asking the user anything. Use inherited shell values first. If the env vars are present but the tool cannot read them, check the current shell environment before asking. +3. **Generate a work ticket**: format `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`. Use the shared wiki hash for `{owner}/{repo}` for `{HASH}`: take the first 8 uppercase hex chars of its SHA-1, then replace a leading digit or `A`/`B`/`C` with `H` plus the next 7 chars. Try to rename the current session to the ticket name (skip when the CLI does not support it). +4. Read `ANALYZE_CONTENTS` via `jsc-gitea:wiki` and list what is unfinished: plan name, HASH, work package number, count of open items. A selectable work package must satisfy all three: **unfinished, dependency-free (or all dependencies done), and not holding a work ticket**. +5. Let the user pick a work package per `jsc-ask:ask` rules (options state open-item count and estimated effort). Write the ticket into that work package's ticket column (the zh-TW field 「工作證」) on the analysis page and save it back to the wiki. **Only after the ticket is saved successfully may you proceed.** +6. List every open item of the work package and implement them **one at a time**: - Follow the TDD loop: red before green, one slice at a time; rules and anti-patterns in `references/tdd.md` (refactoring belongs to the review stage). - After each item, flip its `[ ]` to `[x]` on the analysis page and save to the wiki before starting the next item. -6. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes. -7. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time. +7. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes. +8. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time. ## Rules diff --git a/skills/maintain/SKILL.md b/skills/maintain/SKILL.md index bde4bbd..4243fb8 100644 --- a/skills/maintain/SKILL.md +++ b/skills/maintain/SKILL.md @@ -1,6 +1,6 @@ --- 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. +description: SDLC maintenance stage. Gate on model capability tags for the maintenance stage, 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 @@ -10,7 +10,7 @@ All wiki reads and writes go through `jsc-gitea:wiki`. ## Steps -1. **Model capability gate**: check the 「SDLC 階段需求」 table from `jsc-cli:models` and confirm the current model qualifies for maintenance (any tag qualifies, but the model must be listed in the mapping table). If not, block the flow and tell the user which model to switch to. +1. **Model capability gate**: check the 「SDLC 階段需求」 table from `jsc-cli:models` and confirm the current model qualifies for maintenance (any tag qualifies, but the model must be listed in the mapping table). If not, block the flow and tell the user which model to switch to. Re-check only when the stage changes. 2. Read `MAINTAIN_CONTENTS` via `jsc-gitea:wiki` and filter projects **still inside their maintenance window**: start date ≤ today, and (end date is NULL or ≥ today). 3. Every project **MUST run as a sub agent** with this flow: 1. Switch the project to the `develop` branch, falling back to `master`, and pull to latest. diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index b972f56..cc9180a 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -1,14 +1,14 @@ --- 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. +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_{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 -Goal: create or extend the wiki plan page `PLAN_{yyyyMMdd}_{HHmmss}_{HASH}`. +Goal: create or extend the wiki plan page `PLAN_{HASH}`. This skill is a **logic-only** stage: never output code, and **never modify any file**. -`{HASH}` = first 8 chars of the SHA-1 of `{owner}/{repo}`, uppercase. +`{HASH}` = the shared wiki hash for `{owner}/{repo}`: take the first 8 uppercase hex chars of its SHA-1. If the first char is a digit, or `A`/`B`/`C`, replace it with `H` and keep the next 7 chars. All wiki reads and writes go through `jsc-gitea:wiki`. ## Steps diff --git a/templates/analyze-contents.md b/templates/analyze-contents.md index e6fbf01..9f11a3e 100644 --- a/templates/analyze-contents.md +++ b/templates/analyze-contents.md @@ -2,4 +2,4 @@ | 計畫名稱 | 分析頁 | HASH | 工作包 | 未完成項目 | 狀態 | | --- | --- | --- | --- | --- | --- | -| {計畫名稱} | [[ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}]] | {HASH} | WP-01、WP-02 | {n} | 未完成 | +| {計畫名稱} | [[ANALYZE_{HASH}|{計畫名稱}]] | {HASH} | WP-01、WP-02 | {n} | 未完成 | diff --git a/templates/analyze-page.md b/templates/analyze-page.md index 531bcd7..a0639e8 100644 --- a/templates/analyze-page.md +++ b/templates/analyze-page.md @@ -1,9 +1,11 @@ # 分析：{計畫名稱} -- 頁名：`ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}` -- 對應計畫：[[PLAN_{yyyyMMdd}_{HHmmss}_{HASH}]] +- 頁名：`ANALYZE_{HASH}` +- HASH：`{HASH}` +- 對應計畫：[[PLAN_{HASH}]] - 存取庫：`{owner}/{repo}` - 狀態：未完成 +- 建立時間：{yyyy-MM-dd HH:mm:ss} ## 現況摘要 diff --git a/templates/error-contents.md b/templates/error-contents.md new file mode 100644 index 0000000..8a6b674 --- /dev/null +++ b/templates/error-contents.md @@ -0,0 +1,9 @@ +# 異常目錄 + +> 由失敗回報流程維護。新異常附加在文末，查問題時先看最新一筆。 + +## 異常清單 + +| 時間 | 頁名 | 存取庫名稱 | 觸發流程 | 退出碼 | 摘要 | +| --- | --- | --- | --- | --- | --- | +| {yyyy-MM-dd HH:mm:ss} | [[ERROR_{HASH}|{error title}]] | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} | diff --git a/templates/error-page.md b/templates/error-page.md new file mode 100644 index 0000000..3de248b --- /dev/null +++ b/templates/error-page.md @@ -0,0 +1,33 @@ +# 異常紀錄：{error title} + +> 由失敗回報流程建立。這是一筆單次異常紀錄，不覆寫舊內容；同類失敗再發生時，請另開新頁。 + +- 頁名：`ERROR_{HASH}` +- HASH：`{HASH}` +- 發生時間：{yyyy-MM-dd HH:mm:ss} +- 存取庫名稱：{owner}/{repo} +- CLI：{cli} +- Session：{session_id} +- 觸發流程：{hook_name} +- 退出碼：{exit_code} +- 錯誤摘要：{error_summary} + +## 現象 + +- {現象描述} + +## 可能原因 + +- {可能原因} + +## 處理結果 + +- {處理方式} + +## 相關資訊 + +| 欄位 | 內容 | +| --- | --- | +| 訊息來源 | {stdin / env / command} | +| 相關輸出 | {stdout / stderr 摘要} | +| 關聯 ticket | [[TICKET_{yyyyMMdd}_{HHmmss}_{HASH}|{ticket 標題}]] | diff --git a/templates/plan-contents.md b/templates/plan-contents.md index cbbcb5d..e40094d 100644 --- a/templates/plan-contents.md +++ b/templates/plan-contents.md @@ -2,4 +2,4 @@ | 計畫名稱 | 計畫頁 | 存取庫 | HASH | 狀態 | 建立時間 | | --- | --- | --- | --- | --- | --- | -| {計畫名稱} | [[PLAN_{yyyyMMdd}_{HHmmss}_{HASH}]] | {owner}/{repo} | {HASH} | 未分析 | {yyyy-MM-dd} | +| {計畫名稱} | [[PLAN_{HASH}|{計畫名稱}]] | {owner}/{repo} | {HASH} | 未分析 | {yyyy-MM-dd} | diff --git a/templates/plan-page.md b/templates/plan-page.md index d8e67f5..c820133 100644 --- a/templates/plan-page.md +++ b/templates/plan-page.md @@ -1,6 +1,7 @@ # 計畫：{計畫名稱} -- 頁名：`PLAN_{yyyyMMdd}_{HHmmss}_{HASH}` +- 頁名：`PLAN_{HASH}` +- HASH：`{HASH}` - 存取庫：`{owner}/{repo}` - 狀態：未分析 - 建立時間：{yyyy-MM-dd HH:mm:ss} diff --git a/templates/repo-contents.md b/templates/repo-contents.md index 711a102..3386f11 100644 --- a/templates/repo-contents.md +++ b/templates/repo-contents.md @@ -2,4 +2,4 @@ | 存取庫 | 盤點頁 | HASH | commit sha | 盤點時間 | | --- | --- | --- | --- | --- | -| {owner}/{repo} | [[REPO_{HASH}]] | {HASH} | `{sha}` | {yyyy-MM-dd} | +| {owner}/{repo} | [[REPO_{HASH}|{owner}/{repo}]] | {HASH} | `{sha}` | {yyyy-MM-dd} | diff --git a/templates/repo-page.md b/templates/repo-page.md index fa49503..6f828d0 100644 --- a/templates/repo-page.md +++ b/templates/repo-page.md @@ -1,6 +1,7 @@ # 盤點：{owner}/{repo} - 頁名：`REPO_{HASH}` +- HASH：`{HASH}` - commit sha：`{sha}` - 盤點時間：{yyyy-MM-dd HH:mm:ss} -- 2.53.0