@loviusc/sa-spec 0.2.1 → 0.2.3

package/templates/readme.md

@@ -1,4 +1,41 @@
-# 個人系統分析 AI 工作台
+# 個人系統分析 AI 工作台 / System Analysis AI Workspace
+
+[![npm version](https://img.shields.io/npm/v/@loviusc/sa-spec.svg)](https://www.npmjs.com/package/@loviusc/sa-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> A lightweight system analysis documentation workspace CLI that turns ideas into verifiable, auditable, and conflict-checked specifications for AI-driven development.
+> 輕量級系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的規格文件。
+
+<p align="center">
+  <b>🌐 Languages:</b>
+  <a href="./README.en.md"><b>English</b></a> |
+  <a href="./README.zh-TW.md"><b>繁體中文</b></a> |
+  <a href="./README.zh-CN.md"><b>简体中文</b></a> |
+  <a href="./README.ja.md"><b>日本語</b></a> |
+  <a href="./README.ko.md"><b>한국어</b></a>
+</p>
+
+---
+
+### Quick Start (English)
+
+```bash
+# Global installation via npm
+npm install -g @loviusc/sa-spec
+
+# Initialize project with English specification rules
+sa-spec init --full --lang en
+
+# Create a feature draft branch
+sa-spec new --name cart-checkout --branch
+```
+
+**Core AI Workflow in VS Code:**
+`spec:init (sci)` $\to$ `spec:propose (scp)` $\to$ `spec:analyze (sca)` $\to$ `spec:commit (scc)`
+
+👉 **Read full English documentation: [README.en.md](./README.en.md)**
+
+---
 
 `sa-spec` 是一個輕量的系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的文件。
 
@@ -360,45 +397,51 @@ docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 
 ```mermaid
 flowchart TD
-    A[開新需求: sa-spec new --name cart --branch] --> B[建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄]
-    B --> C[AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護]
-    C --> D{使用者確認通過<br/>執行 scc 或 finalize}
-    D --> E[查詢 master 最新序號 N]
-    E --> F[重命名為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 為正式號碼]
-    F --> G[sa-spec reindex: 動態重構 index.md]
-    G --> H[合併回 master: 零衝突、序號永遠連續！]
+    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄"]
+    B --> C["AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護"]
+    C --> D{"使用者確認通過<br/>執行 scc 或 finalize"}
+    D --> E["自動查詢主分支最新序號 N"]
+    E --> F["自動定號為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 並建立 commit"]
+    F --> G["自動合併至 master 主分支<br/>動態重新生成 project/index.md"]
+    G --> H["完成閉環：零衝突、序號永遠連續！"]
 ```
 
 ### 多人協作四步流程
 
 #### 1. 提出需求（草稿與分支隔離）
-開需求時**不搶序號**，直接以語意名稱建立分支與草稿目錄：
-
-```bash
-# 自動建立並切換至 feat/cart-checkout 分支，建立 project/cart-checkout/ 草稿目錄
-sa-spec new --name cart-checkout --branch
-```
-在 VS Code 側邊欄輸入：
-```text
-scp 購物車結帳需求
-```
+開需求時**不搶序號**，直接以語意名稱建立分支與草稿目錄。支援兩種方式：
+
+* **方式 A（純 AI 自動化，最推薦）**：在 AI 側邊欄直接輸入：
+  ```text
+  scp 購物車結帳需求
+  ```
+  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，並在 `project/cart-checkout/` 建立草稿目錄！
+* **方式 B（CLI 終端指令）**：
+  ```bash
+  sa-spec new --name cart-checkout --branch
+  ```
 * **特點**：目錄名稱為 `project/cart-checkout/`，內部所有檔案皆使用 `{{REQ_ID}}` 佔位符。多人同時提出需求互不干擾、零衝突。即使需求中途放棄，直接刪除分支即可，絕不留下幽靈跳號。
 
 #### 2. 分析與衝突檢查（規格基線同步）
 在分支上執行 `spec:analyze`（或 `sca`）前，工具會確認已取得 `master`（或 `origin/master`）的最新規格，確保是以全專案最新基準進行影響評估，避免因分支落後而漏檢權限、API 或資料表衝突。
 
-#### 3. 確認歸檔與延遲定號（Late-Binding）
-當需求規格確認無誤，準備歸檔時：
-
-```bash
-# 自動向 master 查詢最新可用序號（例如 REQ-006）
-sa-spec finalize --name cart-checkout
-```
-* **自動化執行**：
-  1. 取得最新序號（例如目前最大是 `REQ-005`，自動取得 `REQ-006`）。
-  2. 使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`。
-  3. 自動掃描並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
-  4. 自動執行 `reindex` 重建需求總表。
+#### 3. 確認歸檔與延遲定號（自動領號 + 自動合併回主分支）
+當需求規格經使用者確認無誤，準備歸檔時：
+
+* **方式 A（純 AI 自動化，最推薦）**：在 AI 側邊欄直接輸入：
+  ```text
+  scc
+  ```
+  AI 收到後會自動完成全自動 Git-Flow 閉環作業：
+  1. **自動向主分支查詢並取得新號**：查詢 master/main 目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
+  2. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
+  3. **自動建立本機提交**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`。
+  4. **自動合併至主分支**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），並重新生成主分支的 `project/index.md`，保證主分支規格最新且永遠不衝突！
+* **方式 B（CLI 終端指令）**：
+  ```bash
+  sa-spec finalize --name cart-checkout
+  ```
+  CLI 同樣會自動查詢主分支最新序號定號、置換佔位符、完成提交並自動合併回 master！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
 
 #### 4. 消除索引合併衝突（`sa-spec reindex`）
 `project/index.md` 改為由目錄動態生成的「衍生清單」，不再依賴脆弱的手動 append：
@@ -681,6 +724,18 @@ git push origin master
 
 ## 更新紀錄
 
+### v0.2.3
+- **自動領號與自動合併至主分支（Git-Flow 自動化閉環）**：
+  - **自動從主分支取新號**：執行 `spec:commit`（`scc`）或 `sa-spec finalize` 時，自動向主分支（`master`/`main`）查詢最新已使用最大序號並定號（`REQ-xxx`），自動置換內部佔位符 `{{REQ_ID}}`，徹底防止多人協作時在 feature 分支發生的號碼撞車與落後問題。
+  - **自動合併回主分支**：完成 feature 分支 commit 後，自動切換至主分支（`git checkout master`）並將該 feature 分支自動合併回主分支（`git merge feat/<name>`），並在主分支自動重新整理 `project/index.md`，打造完全自動化的 Git-Flow 零衝突閉環。
+  - **CLI 自動化支援**：`sa-spec finalize --name <name>` 預設自動執行主分支序號運算、定號置換、提交與合併回主分支（支援 `--no-merge` 參數跳過自動合併）。
+
+### v0.2.2
+- **npm 首頁與專案文件全多語系化（Multi-Language Documentation on npm）**：
+  - **5 國獨立完整說明文件**：新增 `README.en.md`（英文）、`README.zh-CN.md`（簡中）、`README.ja.md`（日文）、`README.ko.md`（韓文）與 `README.zh-TW.md`（繁中）。
+  - **npm 國際化首頁最佳化**：在主 `readme.md` 頂部加入醒目的 5 語系導覽切換列與英文 Quick Start 區塊，全球開發者造訪 npm 頁面時能秒懂工具用途與使用方式。
+  - **npm 發布配置補全**：在 `package.json` 補充 `repository`、`homepage` 與 `bugs` 欄位，確保 npm 頁面上的多語系相對連結能自動正確導向 GitHub。
+
 ### v0.2.1
 - **5 國語言與國際化支援（i18n）**：
   - **支援語系**：繁體中文 (`zh-TW`，台灣常用語)、英文 (`en`)、簡體中文 (`zh-CN`)、日文 (`ja`)、韓文 (`ko`)。

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

@@ -21,9 +21,9 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 | 指令 | 簡寫 | 用途 | 執行規則 |
 |---|---|---|---|
 | `spec:init` | `sci` | 初始化 | 載入並遵守 `AGENTS.md`、本 skill 與必要規則，確認 `project/` 結構是否存在。 |
-| `spec:propose` | `scp` | 提出需求 | 整理使用者需求為摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
+| `spec:propose` | `scp` | 提出需求 | 使用者提出需求後，自動依需求名稱建立並切換至專屬 feature 分支（`feat/<name>`，若已在 feature branch 則沿用），建立草稿目錄（內部使用 `{{REQ_ID}}` 佔位），整理需求摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
 | `spec:analyze` | `sca` | 分析與起草 | 先檢查新需求是否與 `project/` 內所有既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿；有衝突則只列出衝突與待釐清問題，待使用者釐清後再次執行 `spec:analyze`（或 `sca`）。 |
-| `spec:commit` | `scc` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，並建立本機 Git commit。 |
+| `spec:commit` | `scc` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾，自動向主分支確認最新可用序號定號（`REQ-xxx`）、替換佔位符，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，建立本機 Git commit 後，自動切換回主分支並完成合併。 |
 
 ## 硬性限制
 
@@ -47,8 +47,9 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 - `handoff.md` 只能根據已確認的 SRS、UML、OpenAPI、DB Schema 與限制整理，不得新增未確認的開發假設。
 - 交給 OpenSpec 或其他 AI 開發工具時，必須指定它先閱讀 `handoff.md`，並以 `handoff.md` 作為開發入口與限制摘要；其他規格文件作為詳細來源。
 - `spec:commit` 完成文件歸檔後，必須自動建立本機 Git commit；commit message 以需求編號與需求名稱為主，並加上簡短需求說明，格式為 `docs(REQ-001): 需求名稱 - 簡短需求說明`。
+- `spec:commit` 自動合併到主分支（Git-Flow 閉環）：完成 feature 分支 commit 後，若目前處於 feature 分支（`feat/<name>`），AI 必須自動切換回主分支（優先偵測 `main` 或 `master`），拉取/檢查最新狀態並自動合併該 feature 分支 (`git checkout master && git merge feat/<name>`)，隨後在主分支重新生成 `project/index.md` 索引，確保主分支規格清單完整且無衝突。
 - `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
-- 多人協作與 Git-Flow 模式（延遲綁定序號）：支援多人平行開發。提出需求時可於 feature branch（如 `feat/<name>`）建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時向 master 確認最新可用序號並定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、重新生成 `project/index.md`，避免多人合併時的序號競爭與索引衝突。
+- 多人協作與 Git-Flow 模式（延遲綁定序號與自動合併）：支援多人平行開發。執行 `spec:propose`（或 `scp`）時，若目前處於 master/main 分支，AI 必須自動依需求名稱建立並切換至專屬 feature branch（如 `feat/<name>`），並在 `project/<name>/` 建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位，無需使用者手動敲 CLI；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時自動向 master 確認最新可用序號定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、完成提交並自動合併回 master，避免多人合併時的序號競爭與索引衝突。
 - 文件未經使用者確認，不得標示為 `已審核`。
 - `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
@@ -146,5 +147,5 @@ init (sci) -> propose (scp) -> analyze (sca)
 analyze 無衝突 -> 產出待確認版本 -> commit (scc)
 analyze 有衝突 -> 釐清問題 -> analyze (sca)
 
-commit (scc) -> 歸檔 -> 本機 Git commit
+commit (scc) -> 自動拿新號定號 -> feature commit -> 自動合併至主分支 (master/main)
 ```