@loviusc/sa-spec 0.1.0

package/templates/rules/estimation.md

@@ -0,0 +1,58 @@
+# 人日估算規則
+
+## 目的
+- 人日估算用於協助技術型系統分析師評估需求範圍、實作成本與風險緩衝。
+- 估算是分析結果的一部分，不應脫離需求內容單獨存在。
+
+## 基本原則
+- 若需求範圍、角色、流程、資料或外部介接尚未確認，不得提供過度精確的估算。
+- 估算需明確標示前提與假設。
+- 需求異動時，若影響範圍改變，必須重新估算。
+- 高風險、跨系統或資料 migration 情境需納入緩衝。
+
+## 適用範圍
+- `project/system-spec.md`：放整體系統估算總覽。
+- `project/REQ-xxx-需求短名/srs.md`：可放單一需求估算明細。
+
+## 估算欄位
+估算至少包含：
+- 估算狀態：`初估`、`待確認`、`已確認`。
+- 估算前提。
+- 分析與設計人日。
+- 開發人日。
+- 測試人日。
+- 上線或資料處理人日。
+- 風險緩衝人日。
+- 總人日。
+- 備註。
+
+## 估算輸出格式
+```md
+## 估算
+
+| 項目 | 人日 | 說明 |
+|---|---:|---|
+| 分析與設計 | 1.5 | 需求釐清、規格整理、跨系統確認 |
+| 開發 | 3 | API、畫面與資料處理 |
+| 測試 | 1 | 功能驗證與回歸測試 |
+| 上線或資料處理 | 0.5 | 參數設定或資料修正 |
+| 風險緩衝 | 1 | 外部系統依賴尚未完全確認 |
+| 總計 | 7 | 初估 |
+
+### 估算前提
+- 角色與權限規則不變。
+- 不涉及新的外部系統介接。
+
+### 估算狀態
+- 初估
+```
+
+## 估算檢查重點
+- 是否已有足夠需求資訊支援估算。
+- 是否把 API、DB、權限、報表、批次、外部系統與 migration 影響納入。
+- 是否將待確認事項與高風險反映到估算狀態或緩衝。
+- 是否在需求變更後同步更新估算。
+
+## 與審核的關係
+- `spec:review` 時需一併檢查估算前提、估算狀態與總人日是否合理。
+- 若有重大待確認事項，估算狀態應維持 `待確認`。

package/templates/rules/file-style.md

@@ -0,0 +1,49 @@
+# 檔案格式
+
+## 檔案編碼
+- 所有檔案都是以 UTF-8 編碼。
+
+## 需求文件格式
+- 所有需求文件都使用 Markdown 格式。
+- 文件內容以繁體中文為主，並採用台灣常用語。
+- 文件狀態需明確標示為：`草稿`、`待確認`、`已審核`。
+
+## 索引檔案
+- 檔名為 `project/index.md`。
+- 內容格式為：`| 編號 | 標題 | 敘述 | 狀態 | 建立時間 | 更新時間 |`。
+- 依需求編號排序，新需求加在最後一列。
+- 需求狀態或標題異動時，必須同步更新索引。
+
+## 新需求格式
+- 每個需求使用獨立資料夾，放入 `project/`。
+- 資料夾命名格式：`REQ-流水號-需求短名`，例如 `REQ-001-login`。
+- 每個需求資料夾至少包含：
+  - `srs.md`：需求規格。
+  - `history.md`：需求歷程。
+  - `uml.puml`：UML 圖。
+  - `openapi.yaml`：OpenAPI 草稿。
+  - `db-schema.md`：DB Schema 草稿。
+  - `handoff.md`：給 OpenSpec 或其他 AI 開發工具的開發交接摘要。
+- 若需求涉及畫面，使用 `wireframe.md`。
+- 若需求需要 UML，放入 `uml/` 資料夾。
+- 若需求需要 API 或資料模型，使用 `api.md` 或獨立資料模型文件。
+- 若需求需要 DB Table 設計，使用 `db-table.md`。
+
+## 建議目錄結構
+```text
+project/
+  index.md
+  REQ-001-login/
+    srs.md
+    wireframe.md
+    history.md
+    uml.puml
+    openapi.yaml
+    db-schema.md
+    handoff.md
+    uml/
+      use-case.puml
+      sequence.puml
+    api.md
+    db-table.md
+```

package/templates/rules/history.md

@@ -0,0 +1,34 @@
+# 需求歷程規則
+
+## 基本原則
+- 每個需求都必須有獨立 `history.md`。
+- 每次需求新增、修改、審核、退回或定稿，都必須新增一筆歷程。
+- 歷程不可覆蓋舊紀錄，只能追加新紀錄。
+- 歷程需記錄需求內容變更；若有高風險注意事項，也需記錄。
+- 每次產出草稿版本、使用者確認版本、或套用版本到正式文件時，都需在歷程中保留可追溯紀錄。
+
+## 歷程格式
+```md
+# 需求歷程：REQ-001
+
+| 時間 | 版本 | 異動類型 | 異動摘要 | 異動原因 | 影響範圍 | 風險等級 | 狀態 |
+|---|---|---|---|---|---|---|---|
+| 2026-04-25 21:30 | v0.1 | 新增 | 建立登入需求草稿版本 | 初始需求 | SRS、UML | 中 | 待確認 |
+```
+
+## 欄位規則
+- 時間：使用 `YYYY-MM-DD HH:mm` 格式。
+- 版本：使用 `v0.1`、`v0.2`、`v1.0` 等格式；未經人工確認前使用 `v0.x`。
+- 異動類型：`新增版本`、`修改版本`、`確認版本`、`套用版本`、`審核`、`退回`、`定稿`。
+- 異動摘要：用一句話說明本次改了什麼。
+- 異動原因：說明為什麼變更。
+- 影響範圍：列出可能受影響的文件或系統面向。
+- 風險等級：使用 `低`、`中`、`高`。
+- 狀態：使用 `草稿`、`待確認`、`已審核`。
+
+## 修改需求時
+- AI 必須先整理本次變更點。
+- AI 必須標示本次草稿版本與上一版差異。
+- 若有高風險或影響範圍不明，AI 必須記錄注意事項。
+- AI 必須在歷程中加入一筆紀錄。
+- 若資訊不足，歷程狀態應標示為 `待確認`。

package/templates/rules/review.md

@@ -0,0 +1,42 @@
+# 人工審核規則
+
+## 審核原則
+- 每份文件產出後都停留在人工審核點。
+- 未經人工確認的文件狀態不得標示為 `已審核`。
+- 審核時優先確認 AI 是否加入未經確認的假設。
+
+## 通用審核清單
+- 需求目標是否清楚。
+- 使用者與角色是否明確。
+- 主要流程是否完整。
+- 例外流程是否足夠。
+- 功能需求是否可驗收。
+- 非功能需求是否有必要且可衡量。
+- 業務規則是否有來源或待確認標示。
+- 高風險注意事項是否已記錄。
+- 歷程文件是否已更新。
+
+## UML 審核清單
+- UML 是否對應需求編號。
+- UML 是否與 `srs.md` 一致。
+- UML 是否新增了未確認角色、流程或系統行為。
+- UML 是否標示待確認內容。
+
+## Wireframe 審核清單
+- Wireframe 是否對應需求編號。
+- Wireframe 是否只根據 `srs.md` 或已標示待確認的內容產出。
+- 畫面目的、畫面元素、操作流程與錯誤狀態是否清楚。
+- 欄位、按鈕、連結、提示文字與錯誤訊息是否有用途。
+- 空狀態、載入狀態、錯誤狀態與權限不足狀態是否足夠。
+- 權限或角色差異是否明確。
+- 是否影響 API request / response、DB Table 欄位或驗收條件。
+- Wireframe 發現的 SRS 缺口是否已回寫待確認事項。
+
+## API、DB Table 與資料模型審核清單
+- API 或資料模型是否只根據已確認需求產出。
+- 權限、錯誤處理與資料欄位是否明確。
+- 是否有影響既有 API 或資料結構。
+- 是否需要更新 UML、驗收條件或注意事項。
+- DB Table、欄位、Index、Constraint 是否能追溯到需求。
+- Nullable、Unique、資料保留、刪除規則是否明確。
+- Migration、資料轉換、rollback 與效能風險是否已評估。

package/templates/rules/spec.md

@@ -0,0 +1,44 @@
+# SRS 與需求規格規則
+
+## 基本原則
+- 需求文件以單一需求為單位撰寫。
+- 不可將未確認資訊寫成事實。
+- 若資訊不足，先列出待確認問題，再產出草稿。
+- 所有需求必須可追溯、可審核、可驗收。
+
+## 文件欄位
+`srs.md` 至少包含：
+- 需求編號。
+- 需求名稱。
+- 狀態：`草稿`、`待確認`、`已審核`。
+- 需求摘要。
+- 業務目標。
+- 使用者與角色。
+- 前置條件。
+- 主要流程。
+- 例外流程。
+- 功能需求。
+- 非功能需求。
+- 業務規則。
+- 驗收條件。
+- 待確認事項。
+- 相關文件。
+
+## 功能需求格式
+功能需求使用條列式描述，並符合：
+- 每一項只描述一個可驗收行為。
+- 明確指出觸發者、系統行為與結果。
+- 若涉及權限、資料、通知或狀態變更，必須明確寫出。
+
+## 驗收條件格式
+驗收條件建議使用 Given / When / Then：
+```md
+Given 前置條件
+When 使用者執行動作
+Then 系統應產生可驗證結果
+```
+
+## 待確認事項
+- 待確認事項不可混入正式需求。
+- 每個待確認事項需說明影響範圍。
+- 待確認事項解決後，需更新 `history.md`。

package/templates/rules/system-spec.md

@@ -0,0 +1,53 @@
+# 系統規格書規則
+
+## 目的
+- 系統規格書用於快速理解整個系統是做什麼、服務誰、包含哪些主要模組與流程。
+- 系統規格書是系統層文件，不取代單一需求的 `srs.md`。
+- 單一需求文件需能追溯回系統規格書描述的範圍、模組或流程。
+
+## 基本原則
+- 文件內容以整體系統為範圍，不聚焦單一功能細節。
+- 不可將未確認資訊寫成事實。
+- 若資訊不足，先列出待確認問題，再產出草稿。
+- 系統規格書需能幫助新成員快速理解系統目的、邊界、核心流程與相關需求。
+
+## 文件位置
+- 建議檔名為 `project/system-spec.md`。
+- 若未來需要版本化，可再調整為獨立資料夾，但第一版先以單檔管理。
+
+## 文件欄位
+`system-spec.md` 至少包含：
+- 文件名稱。
+- 狀態：`草稿`、`待確認`、`已審核`。
+- 系統摘要。
+- 業務目標。
+- 範圍。
+- 不在範圍。
+- 使用者與角色。
+- 系統邊界。
+- 主要功能模組。
+- 核心流程總覽。
+- 關鍵資料主題。
+- 外部系統與介接。
+- 非功能需求總覽。
+- 已知限制與假設。
+- 相關需求清單。
+- 估算總覽。
+- 待確認事項。
+
+## 模組描述要求
+- 每個主要模組需說明其目的、主要使用者與支援的業務情境。
+- 若模組已拆成多個需求，需列出對應需求編號。
+
+## 流程描述要求
+- 核心流程以總覽層級描述，不展開到每個按鈕或欄位細節。
+- 若流程涉及跨模組、跨系統或權限切換，需特別標示。
+
+## 估算要求
+- 系統規格書需提供整體估算總覽，詳細規則遵守 `rules/estimation.md`。
+- 若估算前提未確認，估算狀態需標示為 `待確認`。
+
+## 待確認事項
+- 待確認事項不可混入正式規格內容。
+- 每個待確認事項需說明影響範圍，例如模組、流程、估算或驗收。
+- 待確認事項解決後，需同步更新相關需求文件與 `history.md`。

package/templates/rules/uml-style.md

@@ -0,0 +1,27 @@
+# UML 產出規則
+
+## 格式
+- UML 圖一律使用 PlantUML。
+- PlantUML 檔案副檔名使用 `.puml`。
+- 圖表內容以繁體中文描述，並採用台灣常用語。
+
+## 限制
+- 不可自行幻想未確認的角色、流程、資料、系統行為或例外情境。
+- 不明確的部分必須標示為「待確認」，並回到人工審核。
+- UML 必須能追溯到對應需求編號。
+- UML 內容不得超出已確認或已標示假設的需求範圍。
+
+## 圖表類型
+- Use Case Diagram：用於描述使用者、外部系統與系統功能邊界。
+- Activity Diagram：用於描述業務流程、判斷點與例外流程。
+- Sequence Diagram：用於描述角色、系統、服務或 API 之間的互動順序。
+- Class Diagram：用於描述主要資料物件、屬性與關聯。
+- State Diagram：用於描述有明確生命週期的物件狀態。
+
+## 圖表說明
+每張 UML 圖旁邊或同一文件內需補充：
+- 圖表目的。
+- 對應需求編號。
+- 涵蓋範圍。
+- 未涵蓋範圍。
+- 待確認事項。

package/templates/rules/wireframe.md

@@ -0,0 +1,81 @@
+# Wireframe 產出規則
+
+## 基本原則
+- Wireframe 是 SA 用低保真畫面行為規格，不是 UI 美術稿或前端設計稿。
+- Wireframe 以 Markdown 為主，可使用表格、ASCII 或 Mermaid 輔助說明。
+- Wireframe 必須依據 SRS 產出，並能追溯到需求編號。
+- 不可自行新增 SRS 未提到且未標示待確認的欄位、按鈕、流程或錯誤狀態。
+- 若 Wireframe 發現 SRS 缺口，必須列為待確認事項。
+
+## 輸出文件
+若需求涉及畫面，使用 `wireframe.md`，放在對應需求資料夾內。
+
+```text
+project/
+  REQ-001-login/
+    wireframe.md
+```
+
+## 文件欄位
+`wireframe.md` 至少包含：
+- 需求編號。
+- 狀態：`草稿`、`待確認`、`已審核`。
+- 畫面清單。
+- 每個畫面的畫面目的。
+- 畫面元素表：欄位、按鈕、連結、提示文字、錯誤訊息。
+- 操作流程。
+- 空狀態、錯誤狀態、載入狀態。
+- 權限或角色差異。
+- 對應需求編號。
+- 影響 API / DB Table 的欄位或操作。
+- 待確認事項。
+
+## 畫面格式
+```md
+## 畫面：登入頁
+
+### 畫面目的
+讓使用者輸入帳號密碼並登入系統。
+
+### 畫面元素
+| 元素 | 類型 | 必填 | 說明 | 對應需求 |
+|---|---|---|---|---|
+| 帳號 | Input | 是 | 使用者登入帳號 | REQ-001 |
+| 密碼 | Password Input | 是 | 使用者密碼 | REQ-001 |
+| 登入 | Button | 是 | 送出登入請求 | REQ-001 |
+
+### 操作流程
+1. 使用者輸入帳號與密碼。
+2. 使用者點擊登入。
+3. 系統驗證帳密。
+4. 成功則進入首頁。
+5. 失敗則顯示錯誤訊息。
+
+### 狀態與訊息
+| 狀態 | 情境 | 顯示內容 | 系統行為 |
+|---|---|---|---|
+| 錯誤 | 帳號或密碼錯誤 | 帳號或密碼不正確 | 停留在登入頁 |
+
+### API / DB Table 影響
+| 類型 | 項目 | 說明 | 是否待確認 |
+|---|---|---|---|
+| API | 登入請求 | 需要帳號與密碼欄位 | 否 |
+```
+
+## 權限與角色
+- 若不同角色看到的欄位、按鈕、資料或操作不同，必須明確列出。
+- 若權限差異不明確，需標示為待確認。
+
+## 狀態設計
+每個畫面需視情況描述：
+- 初始狀態。
+- 載入狀態。
+- 空狀態。
+- 成功狀態。
+- 錯誤狀態。
+- 權限不足狀態。
+
+## 審核要求
+- Wireframe 草稿完成後必須人工審核。
+- Wireframe 審核通過前，不得視為 API 或 DB Table 的正式依據。
+- 若 Wireframe 造成 SRS、API、DB Table 或驗收條件異動，必須更新 `history.md`；若產生高風險，需在需求文件的注意事項中標示。

package/templates/skills/system-analysis/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: system-analysis
+description: 用 init、propose、analyze、commit 四段流程整理需求，並產出 SRS、UML、OpenAPI、DB Schema。
+---
+
+# System Analysis Skill
+
+## 核心交付物
+
+- `srs.md`：需求規格。
+- `uml.puml`：UML 圖。
+- `openapi.yaml`：OpenAPI 草稿。
+- `db-schema.md`：DB Schema 草稿。
+- `handoff.md`：給 OpenSpec 或其他 AI 開發工具的開發交接摘要。
+- `history.md`：版本歷程。
+
+## 指令流程
+
+| 指令 | 用途 | 執行規則 |
+|---|---|---|
+| `spec:init` | 初始化 | 載入並遵守 `AGENTS.md`、本 skill 與必要規則，確認 `project/` 結構是否存在。 |
+| `spec:propose` | 提出需求 | 整理使用者需求為摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
+| `spec:analyze` | 分析與起草 | 先檢查新需求是否與 `project/` 內所有既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿；有衝突則只列出衝突與待釐清問題，待使用者釐清後再次執行 `spec:analyze`。 |
+| `spec:commit` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，並建立本機 Git commit。 |
+
+## 硬性限制
+
+- 使用繁體中文，並採用台灣常用語。
+- `spec:init` 必須檢查 Git 狀態：
+  - 若 Git 未安裝，提醒使用者後續歸檔會使用版本管理，但不可中斷初始化。
+  - 若 Git 已安裝且目前目錄尚未初始化為 Git repository，則自動執行 `git init`。
+  - 若目前目錄已是 Git repository，僅回報狀態，不重複初始化。
+- `project/system-spec.md` 由 `sa-spec init` 建立；`spec:analyze` 只能讀取它做衝突檢查，並提出待確認的系統規格更新建議，不得寫入；`spec:commit` 才能依使用者確認後的內容更新 `project/system-spec.md`。
+- 不可自行幻想未確認的業務規則、角色、流程、資料或系統行為。
+- `spec:analyze` 必須先檢查所有既有需求是否衝突。
+- 若發現衝突，不得產出最終文件，不得修改任何需求文件，只能向使用者釐清。
+- 衝突釐清後，流程回到 `spec:analyze`，重新檢查衝突並產出草稿；不可直接進入 `spec:commit`。
+- 任何流程都不得修改其他需求資料夾中的文件，除非使用者明確指定該需求也要變更。
+- `spec:commit` 只能套用已由 `spec:analyze` 產出的、且使用者已確認的無衝突版本。
+- `handoff.md` 只能根據已確認的 SRS、UML、OpenAPI、DB Schema 與限制整理，不得新增未確認的開發假設。
+- 交給 OpenSpec 或其他 AI 開發工具時，必須指定它先閱讀 `handoff.md`，並以 `handoff.md` 作為開發入口與限制摘要；其他規格文件作為詳細來源。
+- `spec:commit` 完成文件歸檔後，必須自動建立本機 Git commit；commit message 以需求編號與需求名稱為主，並加上簡短需求說明，格式為 `docs(REQ-001): 需求名稱 - 簡短需求說明`。
+- `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
+- 文件未經使用者確認，不得標示為 `已審核`。
+- `uml.puml` 不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。需求複雜時，可在同一個 `uml.puml` 內放多張 PlantUML 圖並清楚分段。
+- 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
+
+## analyze 衝突檢查
+
+執行 `spec:analyze` 時，先讀取：
+
+- `project/index.md`
+- `project/system-spec.md`
+- 所有 `project/REQ-*/srs.md`
+- 所有 `project/REQ-*/openapi.yaml`
+- 所有 `project/REQ-*/db-schema.md`
+- 所有 `project/REQ-*/handoff.md`
+- 必要時讀取 `project/REQ-*/uml.puml`
+
+至少檢查：
+
+- 是否與既有需求目標或流程重疊。
+- 是否改變既有角色、權限或資料存取規則。
+- 是否影響既有 API 路徑、request/response 或狀態碼。
+- 是否影響既有 DB Table、欄位、唯一性或關聯。
+- 是否與既有驗收條件矛盾。
+
+## analyze 發現衝突時
+
+若 `spec:analyze` 發現衝突：
+
+1. 列出衝突的既有需求編號與檔案。
+2. 說明衝突原因與影響範圍。
+3. 提出最多 3 個待釐清問題。
+4. 停止產出 SRS、UML、OpenAPI、DB Schema。
+5. 等使用者釐清後，再由使用者執行 `spec:analyze` 繼續。
+6. 不得修改任何既有需求文件。
+
+## analyze 無衝突輸出
+
+無衝突時，輸出一個待確認版本，包含：
+
+- SRS 草稿。
+- UML PlantUML 草稿。
+- OpenAPI YAML 草稿。
+- DB Schema 草稿。
+- Handoff 交接摘要草稿。
+- `project/system-spec.md` 更新建議。
+- 待確認事項。
+- 本次未修改其他需求的聲明。
+
+## commit 歸檔
+
+`spec:commit` 只能套用已由 `spec:analyze` 產出的無衝突版本。使用者明確確認後，才可歸檔：
+
+```text
+project/
+  REQ-001-name/
+    srs.md
+    uml.puml
+    openapi.yaml
+    db-schema.md
+    handoff.md
+    history.md
+```
+
+`handoff.md` 用於交接給 OpenSpec 或其他 AI 開發工具，必須包含：
+
+- 需求來源與相關文件。
+- 要開發什麼。
+- 不要開發什麼。
+- 已確認規則。
+- 狀態與流程。
+- API 契約。
+- DB 變更。
+- 驗收條件。
+- 開發限制。
+- 建議實作範圍。
+
+若需求不需要 API 或 DB，必須明確標示「無 API 需求」或「無 DB 需求」。不得在 `handoff.md` 中新增未經使用者確認的角色、權限、資料、流程、狀態、API 或 DB 欄位。
+
+交給 OpenSpec 或其他 AI 開發工具時，應要求它先閱讀 `handoff.md`，並以 `handoff.md` 作為本次開發入口與限制摘要。若需要完整細節，再查閱同需求資料夾內的 `srs.md`、`uml.puml`、`openapi.yaml`、`db-schema.md` 與 `history.md`。
+
+歸檔完成後，必須只 stage 本次歸檔相關檔案，並建立本機 Git commit。commit message 格式：
+
+```text
+docs(REQ-001): 需求名稱 - 簡短需求說明
+```
+
+只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`。若 push 失敗，只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
+
+## 狀態機
+
+```text
+init -> propose -> analyze
+
+analyze 無衝突 -> 產出待確認版本 -> commit
+analyze 有衝突 -> 釐清問題 -> analyze
+
+commit -> 歸檔 -> 本機 Git commit
+```