@loviusc/sa-spec 0.1.0 → 0.1.3

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@loviusc/sa-spec",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Personal system analysis documentation workspace CLI",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "bin": {
     "sa-spec": "bin/sa-spec.js"
   },

package/readme.md

@@ -2,14 +2,14 @@
 
 `sa-spec` 是一個輕量的系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的文件。
 
-AI 工作流只使用四個指令：
+AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
 
-```text
-spec:init
-spec:propose
-spec:analyze
-spec:commit
-```
+| 標準指令 | 簡寫 | 說明 |
+|---|---|---|
+| `spec:init` | `sci` | 初始化專案與規則 |
+| `spec:propose` | `scp` | 提出需求並整理摘要 |
+| `spec:analyze` | `sca` | 衝突檢查與規格起草 |
+| `spec:commit` | `scc` | 確認歸檔並建立 Git commit |
 
 每個需求歸檔後固定包含：
 
@@ -17,7 +17,8 @@ spec:commit
 project/
   REQ-001-login/
     srs.md
-    uml.puml
+    uml/
+      main.puml
     openapi.yaml
     db-schema.md
     handoff.md
@@ -240,6 +241,7 @@ sa-spec init --full
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
 | `sa-spec doctor` | 檢查必要檔案是否存在。 |
+| `sa-spec upgrade [--dry-run]` | 將既有專案升級為最新版本：同步最新 AGENTS 與規則文件，並將既有需求中的 `uml.puml` 自動遷移為 `uml/main.puml`。 |
 
 `sa-spec new` 是快速建空白模板的輔助工具。正式需求流程仍建議使用 `spec:init`、`spec:propose`、`spec:analyze`、`spec:commit`。
 
@@ -259,7 +261,7 @@ sa-spec init --full
 | AI 對話 | Claude Code 類型的 VS Code AI 套件或 CLI 整合 | 擇一 | 用 Claude 讀取工作區規則並協作產出需求文件。 |
 | AI 對話 | Gemini 類型的 VS Code AI 套件或 CLI 整合 | 擇一 | 用 Gemini 讀取工作區規則並協作產出需求文件。 |
 | Markdown | Markdown 預覽或 Markdown All in One 類型套件 | 選用 | 預覽 `srs.md`、`history.md`、`system-spec.md`。 |
-| UML | PlantUML 類型套件 | 選用 | 預覽 `uml.puml`。 |
+| UML | PlantUML 類型套件 | 選用 | 預覽需求內的 `uml/*.puml`。 |
 | YAML | YAML 類型套件 | 選用 | 編輯與檢查 `openapi.yaml`。 |
 | Git | GitLens 類型套件 | 選用 | 查看需求文件修改歷程。 |
 
@@ -280,10 +282,10 @@ Markdown、PlantUML、YAML、GitLens 這類套件可以提升閱讀與檢查體
 | CLI | `sa-spec init --full` | 終端機或 VS Code Terminal | 建立文件骨架與規則檔。 |
 | CLI | `sa-spec check` | 終端機或 VS Code Terminal | 檢查必要文件是否存在。 |
 | CLI | `sa-spec status` | 終端機或 VS Code Terminal | 查看系統規格與需求索引狀態。 |
-| AI 工作流程 | `spec:init` | VS Code AI 對話側邊欄 | 載入規則並確認工作區狀態。 |
-| AI 工作流程 | `spec:propose` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
-| AI 工作流程 | `spec:analyze` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
-| AI 工作流程 | `spec:commit` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
+| AI 工作流程 | `spec:init` / `sci` | VS Code AI 對話側邊欄 | 載入規則並確認工作區狀態。 |
+| AI 工作流程 | `spec:propose` / `scp` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
+| AI 工作流程 | `spec:analyze` / `sca` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
+| AI 工作流程 | `spec:commit` / `scc` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
 
 建議操作順序：
 
@@ -297,32 +299,32 @@ code .
 接著在 VS Code 的 AI 對話側邊欄輸入：
 
 ```text
-spec:init
-spec:propose
-spec:analyze
-spec:commit
+spec:init    # 或簡寫 sci
+spec:propose # 或簡寫 scp
+spec:analyze # 或簡寫 sca
+spec:commit  # 或簡寫 scc
 ```
 
 如果你有安裝 prompts 或 slash commands，可以用對應的快捷指令；沒有安裝也可以直接手動輸入上面的文字指令。
 
 ## AI 工作流程
 
-| 指令 | 用途 |
-|---|---|
-| `spec:init` | 初始化並載入 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則。 |
-| `spec:propose` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
-| `spec:analyze` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
-| `spec:commit` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
+| 指令 | 簡寫 | 用途 |
+|---|---|---|
+| `spec:init` | `sci` | 初始化並載入 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則。 |
+| `spec:propose` | `scp` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
+| `spec:analyze` | `sca` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
+| `spec:commit` | `scc` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
 
 狀態機：
 
 ```text
-init -> propose -> analyze
+init (sci) -> propose (scp) -> analyze (sca)
 
-analyze 無衝突 -> 產出待確認版本 -> commit
-analyze 有衝突 -> 釐清問題 -> analyze
+analyze 無衝突 -> 產出待確認版本 -> commit (scc)
+analyze 有衝突 -> 釐清問題 -> analyze (sca)
 
-commit -> 歸檔 -> 本機 Git commit
+commit (scc) -> 歸檔 -> 本機 Git commit
 ```
 
 `spec:analyze` 若發現衝突，只會列出衝突與待釐清問題，不會修改任何需求文件，也不會產出最終文件。釐清後應再次執行 `spec:analyze`，重新檢查並產出草稿。
@@ -334,7 +336,7 @@ commit -> 歸檔 -> 本機 Git commit
 ```text
 請先閱讀 project/REQ-001-pomodoro-timer/handoff.md。
 以 handoff.md 作為本次開發入口與限制摘要。
-如需完整需求細節，再查閱同資料夾內的 srs.md、uml.puml、openapi.yaml、db-schema.md 與 history.md。
+如需完整需求細節，再查閱同資料夾內的 srs.md、uml/、openapi.yaml、db-schema.md 與 history.md。
 不得自行新增 handoff.md 未確認的角色、權限、流程、狀態、API 或 DB 欄位。
 若發現 handoff.md 與既有程式或規格衝突，請停止開發並回報。
 ```
@@ -520,7 +522,8 @@ project/
   system-spec.md
   REQ-001-pomodoro-timer/
     srs.md
-    uml.puml
+    uml/
+      state.puml
     openapi.yaml
     db-schema.md
     handoff.md
@@ -591,3 +594,28 @@ git push origin master
 - `project/system-spec.md` 只能在 `spec:commit` 依使用者確認內容更新。
 - `spec:commit` 會自動建立本機 Git commit；remote push 需使用者明確要求或啟用 auto-push。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
+
+## 更新紀錄
+
+### v0.1.3
+- **支援指令簡寫別名（同時保留完整指令）**：
+  - `sci` ＝ `spec:init`
+  - `scp` ＝ `spec:propose`
+  - `sca` ＝ `spec:analyze`
+  - `scc` ＝ `spec:commit`
+  - 兩者完全等價，使用者可依輸入習慣自由選擇長指令或 3 字母縮寫。
+
+### v0.1.2
+- **新增 `sa-spec upgrade` 版本升級指令**：
+  - **工作區規則同步**：自動檢查並更新專案中的 `AGENTS.md`、`skills/system-analysis/SKILL.md` 以及 `rules/` 目錄下的規則文件至最新版本（自動保留既有的 memory context）。
+  - **既有需求自動遷移**：掃描 `project/REQ-*` 目錄，將舊版 `uml.puml` 自動重構移動為 `uml/main.puml`，並自動修復 `handoff.md` 中的來源引用路徑。
+  - **提供 `--dry-run` 模擬模式**：可加上 `--dry-run` 參數先行預覽哪些檔案會被更新或遷移，而不實際寫入檔案。
+
+### v0.1.1
+- **PlantUML 檔案架構重構（解決多圖渲染與預覽開不起來問題）**：
+  - **目錄化結構**：每個需求目錄下由原本單一檔案 `uml.puml` 改為 `uml/` 資料夾（預設提供 `uml/main.puml` 骨架）。
+  - **單檔單圖原則**：嚴格規範每個 `.puml` 檔案僅包含單一組 `@startuml` 與 `@enduml`，禁止在單一檔案內混放多張圖。
+  - **支援多面向拆分**：需求若涉及多個面向（如業務流程、循序互動、狀態轉換），必須拆分為獨立 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），確保 PlantUML 預覽外掛能順暢開啟與渲染。
+  - **CLI 自動化**：`sa-spec new` 與 `sa-spec template req` 自動建立 `uml/` 資料夾並產出預設的 `uml/main.puml`。
+  - **全專案規範同步**：同步更新 `AGENTS.md`、`system-analysis` skill、`rules/uml-style.md`、`rules/file-style.md` 與 `handoff.md`。
+

package/src/cli.js

@@ -20,6 +20,9 @@ function main() {
     case "check":
       runCheck();
       return;
+    case "upgrade":
+      upgradeProject(args.slice(1));
+      return;
     case "doctor":
       runDoctor();
       return;
@@ -219,11 +222,13 @@ function createReqTemplate(args, label = "new") {
 
   const slug = slugify(name);
   const reqDir = path.join("project", `${id}-${slug}`);
+  const umlDir = path.join(reqDir, "uml");
   const replacements = { REQ_ID: id, REQ_NAME: name };
   const results = [
     ensureDir(reqDir),
+    ensureDir(umlDir),
     ensureFileFromTemplate(path.join("project", "req", "srs.md"), path.join(reqDir, "srs.md"), replacements),
-    ensureFileFromTemplate(path.join("project", "req", "uml.puml"), path.join(reqDir, "uml.puml"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "uml", "main.puml"), path.join(umlDir, "main.puml"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "openapi.yaml"), path.join(reqDir, "openapi.yaml"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "db-schema.md"), path.join(reqDir, "db-schema.md"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "handoff.md"), path.join(reqDir, "handoff.md"), replacements),
@@ -336,10 +341,133 @@ function slugify(value) {
     .replace(/^-+|-+$/g, "");
 }
 
+function upgradeProject(args = []) {
+  const dryRun = args.includes("--dry-run");
+  const results = [];
+
+  results.push(ensureDir("skills"));
+  results.push(ensureDir(path.join("skills", "system-analysis")));
+
+  results.push(updateFileFromTemplate("AGENTS.md", "AGENTS.md", dryRun));
+  results.push(
+    updateFileFromTemplate(
+      path.join("skills", "system-analysis", "SKILL.md"),
+      path.join("skills", "system-analysis", "SKILL.md"),
+      dryRun
+    )
+  );
+
+  const rulesTargetDir = path.join(cwd, "rules");
+  if (fs.existsSync(rulesTargetDir)) {
+    const templateRulesDir = path.join(templatesDir, "rules");
+    for (const file of listFilesRecursive(templateRulesDir)) {
+      const relativePath = path.relative(templatesDir, file);
+      results.push(updateFileFromTemplate(relativePath, relativePath, dryRun));
+    }
+  }
+
+  const projectDir = path.join(cwd, "project");
+  if (fs.existsSync(projectDir)) {
+    const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith("REQ-")) {
+        const reqRelDir = path.join("project", entry.name);
+        const oldUmlRelPath = path.join(reqRelDir, "uml.puml");
+        const oldUmlAbsPath = path.join(cwd, oldUmlRelPath);
+        const newUmlRelDir = path.join(reqRelDir, "uml");
+        const newUmlAbsDir = path.join(cwd, newUmlRelDir);
+        const newMainUmlRelPath = path.join(newUmlRelDir, "main.puml");
+        const newMainUmlAbsPath = path.join(cwd, newMainUmlRelPath);
+
+        if (fs.existsSync(oldUmlAbsPath)) {
+          if (!fs.existsSync(newMainUmlAbsPath)) {
+            if (!dryRun) {
+              if (!fs.existsSync(newUmlAbsDir)) {
+                fs.mkdirSync(newUmlAbsDir, { recursive: true });
+              }
+              fs.renameSync(oldUmlAbsPath, newMainUmlAbsPath);
+            }
+            results.push({
+              action: "migrate",
+              target: `${oldUmlRelPath} -> ${newMainUmlRelPath}`
+            });
+          } else {
+            results.push({
+              action: "warn",
+              target: oldUmlRelPath,
+              message: `目標 ${newMainUmlRelPath} 已存在，請確認是否可手動移除舊檔。`
+            });
+          }
+        }
+
+        const handoffRelPath = path.join(reqRelDir, "handoff.md");
+        const handoffAbsPath = path.join(cwd, handoffRelPath);
+        if (fs.existsSync(handoffAbsPath)) {
+          const content = fs.readFileSync(handoffAbsPath, "utf8");
+          if (content.includes("uml.puml")) {
+            if (!dryRun) {
+              fs.writeFileSync(handoffAbsPath, content.replace(/uml\.puml/g, "uml/"), "utf8");
+            }
+            results.push({
+              action: "update",
+              target: handoffRelPath,
+              message: "更新來源參照 uml.puml -> uml/"
+            });
+          }
+        }
+      }
+    }
+  }
+
+  printResultList(dryRun ? "upgrade (dry-run)" : "upgrade", results);
+}
+
+function updateFileFromTemplate(templateRelativePath, targetRelativePath, dryRun = false) {
+  const targetAbsolutePath = path.join(cwd, targetRelativePath);
+  const templateAbsolutePath = path.join(templatesDir, templateRelativePath);
+  if (!fs.existsSync(templateAbsolutePath)) {
+    return { action: "skip", target: targetRelativePath };
+  }
+
+  let templateContent = readTemplate(templateRelativePath);
+  if (!fs.existsSync(targetAbsolutePath)) {
+    if (!dryRun) {
+      writeFileIfMissing(targetAbsolutePath, templateContent);
+    }
+    return { action: "create", target: targetRelativePath };
+  }
+
+  const currentContent = fs.readFileSync(targetAbsolutePath, "utf8");
+  if (currentContent.includes("<claude-mem-context>")) {
+    const memMatch = currentContent.match(/(<claude-mem-context>[\s\S]*?<\/claude-mem-context>)/);
+    if (memMatch && !templateContent.includes("<claude-mem-context>")) {
+      templateContent = `${templateContent.trimEnd()}\n\n\n${memMatch[1]}\n`;
+    }
+  }
+
+  if (currentContent.trim() === templateContent.trim()) {
+    return { action: "skip", target: targetRelativePath };
+  }
+
+  if (!dryRun) {
+    fs.writeFileSync(targetAbsolutePath, templateContent, "utf8");
+  }
+  return { action: "update", target: targetRelativePath };
+}
+
 function printResultList(label, results) {
   console.log(`sa-spec ${label}`);
   for (const result of results) {
-    const action = result.action === "create" ? "CREATED" : result.action === "update" ? "UPDATED" : result.action === "warn" ? "WARNING" : "SKIPPED";
+    const action =
+      result.action === "create"
+        ? "CREATED"
+        : result.action === "update"
+        ? "UPDATED"
+        : result.action === "migrate"
+        ? "MIGRATED"
+        : result.action === "warn"
+        ? "WARNING"
+        : "SKIPPED";
     console.log(`${action} ${result.target}${result.message ? ` - ${result.message}` : ""}`);
   }
 }
@@ -351,6 +479,7 @@ Usage:
   sa-spec init [--full]
   sa-spec new --id REQ-001 --name login
   sa-spec check
+  sa-spec upgrade [--dry-run]
 `);
 }
 

package/templates/AGENTS.md

@@ -7,7 +7,7 @@
 每個需求歸檔時固定包含：
 
 - `srs.md`：需求規格。
-- `uml.puml`：UML 圖。
+- `uml/`：UML 圖目錄（依面向拆分為獨立 `.puml` 檔，如 `main.puml`、`sequence.puml` 等，禁止單檔混放多圖）。
 - `openapi.yaml`：OpenAPI 草稿。
 - `db-schema.md`：DB Schema 草稿。
 - `handoff.md`：給 OpenSpec 或其他 AI 開發工具的開發交接摘要。
@@ -15,14 +15,14 @@
 
 # 指令流程
 
-只使用四個指令：
+使用四個指令，並支援簡寫別名（兩者等價）：
 
-| 指令 | 用途 | 規則 |
-|---|---|---|
-| `spec:init` | 初始化 | 載入並遵守 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則，確認 `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` | `sci` | 初始化 | 載入並遵守 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則，確認 `project/` 結構是否存在。 |
+| `spec:propose` | `scp` | 提出需求 | 使用者提出需求後，先整理需求摘要、目標、初步流程與待確認事項，不歸檔、不修改既有需求。 |
+| `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。 |
 
 # 重要限制
 
@@ -40,7 +40,7 @@
 - `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 圖並清楚分段。
+- `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 # 衝突檢查重點
@@ -67,12 +67,12 @@
 # 狀態機
 
 ```text
-init -> propose -> analyze
+init (sci) -> propose (scp) -> analyze (sca)
 
-analyze 無衝突 -> 產出待確認版本 -> commit
-analyze 有衝突 -> 釐清問題 -> analyze
+analyze 無衝突 -> 產出待確認版本 -> commit (scc)
+analyze 有衝突 -> 釐清問題 -> analyze (sca)
 
-commit -> 歸檔 -> 本機 Git commit
+commit (scc) -> 歸檔 -> 本機 Git commit
 ```
 
 # 歸檔結構
@@ -82,7 +82,8 @@ project/
   index.md
   REQ-001-name/
     srs.md
-    uml.puml
+    uml/
+      main.puml
     openapi.yaml
     db-schema.md
     handoff.md

package/templates/project/req/handoff.md

@@ -1,7 +1,7 @@
 # {{REQ_ID}} {{REQ_NAME}} Handoff
 
 - 狀態：待確認
-- 來源文件：`srs.md`、`uml.puml`、`openapi.yaml`、`db-schema.md`
+- 來源文件：`srs.md`、`uml/`、`openapi.yaml`、`db-schema.md`
 - 目標讀者：OpenSpec、Codex、Claude、Gemini 或其他 AI 開發工具
 
 ## 要開發什麼

package/templates/project/req/{uml.puml → uml/main.puml}

@@ -8,7 +8,7 @@ User -> System: 發起需求
 System --> User: 回傳結果
 
 note right of System
-待於 spec:exec 後補充流程細節。
+待於 spec:analyze 後補充流程細節。
 end note
 
 @enduml

package/templates/readme.md

@@ -2,14 +2,14 @@
 
 `sa-spec` 是一個輕量的系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的文件。
 
-AI 工作流只使用四個指令：
+AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
 
-```text
-spec:init
-spec:propose
-spec:analyze
-spec:commit
-```
+| 標準指令 | 簡寫 | 說明 |
+|---|---|---|
+| `spec:init` | `sci` | 初始化專案與規則 |
+| `spec:propose` | `scp` | 提出需求並整理摘要 |
+| `spec:analyze` | `sca` | 衝突檢查與規格起草 |
+| `spec:commit` | `scc` | 確認歸檔並建立 Git commit |
 
 每個需求歸檔後固定包含：
 
@@ -17,7 +17,8 @@ spec:commit
 project/
   REQ-001-login/
     srs.md
-    uml.puml
+    uml/
+      main.puml
     openapi.yaml
     db-schema.md
     handoff.md
@@ -240,6 +241,7 @@ sa-spec init --full
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
 | `sa-spec doctor` | 檢查必要檔案是否存在。 |
+| `sa-spec upgrade [--dry-run]` | 將既有專案升級為最新版本：同步最新 AGENTS 與規則文件，並將既有需求中的 `uml.puml` 自動遷移為 `uml/main.puml`。 |
 
 `sa-spec new` 是快速建空白模板的輔助工具。正式需求流程仍建議使用 `spec:init`、`spec:propose`、`spec:analyze`、`spec:commit`。
 
@@ -259,7 +261,7 @@ sa-spec init --full
 | AI 對話 | Claude Code 類型的 VS Code AI 套件或 CLI 整合 | 擇一 | 用 Claude 讀取工作區規則並協作產出需求文件。 |
 | AI 對話 | Gemini 類型的 VS Code AI 套件或 CLI 整合 | 擇一 | 用 Gemini 讀取工作區規則並協作產出需求文件。 |
 | Markdown | Markdown 預覽或 Markdown All in One 類型套件 | 選用 | 預覽 `srs.md`、`history.md`、`system-spec.md`。 |
-| UML | PlantUML 類型套件 | 選用 | 預覽 `uml.puml`。 |
+| UML | PlantUML 類型套件 | 選用 | 預覽需求內的 `uml/*.puml`。 |
 | YAML | YAML 類型套件 | 選用 | 編輯與檢查 `openapi.yaml`。 |
 | Git | GitLens 類型套件 | 選用 | 查看需求文件修改歷程。 |
 
@@ -280,10 +282,10 @@ Markdown、PlantUML、YAML、GitLens 這類套件可以提升閱讀與檢查體
 | CLI | `sa-spec init --full` | 終端機或 VS Code Terminal | 建立文件骨架與規則檔。 |
 | CLI | `sa-spec check` | 終端機或 VS Code Terminal | 檢查必要文件是否存在。 |
 | CLI | `sa-spec status` | 終端機或 VS Code Terminal | 查看系統規格與需求索引狀態。 |
-| AI 工作流程 | `spec:init` | VS Code AI 對話側邊欄 | 載入規則並確認工作區狀態。 |
-| AI 工作流程 | `spec:propose` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
-| AI 工作流程 | `spec:analyze` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
-| AI 工作流程 | `spec:commit` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
+| AI 工作流程 | `spec:init` / `sci` | VS Code AI 對話側邊欄 | 載入規則並確認工作區狀態。 |
+| AI 工作流程 | `spec:propose` / `scp` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
+| AI 工作流程 | `spec:analyze` / `sca` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
+| AI 工作流程 | `spec:commit` / `scc` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
 
 建議操作順序：
 
@@ -297,32 +299,32 @@ code .
 接著在 VS Code 的 AI 對話側邊欄輸入：
 
 ```text
-spec:init
-spec:propose
-spec:analyze
-spec:commit
+spec:init    # 或簡寫 sci
+spec:propose # 或簡寫 scp
+spec:analyze # 或簡寫 sca
+spec:commit  # 或簡寫 scc
 ```
 
 如果你有安裝 prompts 或 slash commands，可以用對應的快捷指令；沒有安裝也可以直接手動輸入上面的文字指令。
 
 ## AI 工作流程
 
-| 指令 | 用途 |
-|---|---|
-| `spec:init` | 初始化並載入 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則。 |
-| `spec:propose` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
-| `spec:analyze` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
-| `spec:commit` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
+| 指令 | 簡寫 | 用途 |
+|---|---|---|
+| `spec:init` | `sci` | 初始化並載入 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則。 |
+| `spec:propose` | `scp` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
+| `spec:analyze` | `sca` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
+| `spec:commit` | `scc` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
 
 狀態機：
 
 ```text
-init -> propose -> analyze
+init (sci) -> propose (scp) -> analyze (sca)
 
-analyze 無衝突 -> 產出待確認版本 -> commit
-analyze 有衝突 -> 釐清問題 -> analyze
+analyze 無衝突 -> 產出待確認版本 -> commit (scc)
+analyze 有衝突 -> 釐清問題 -> analyze (sca)
 
-commit -> 歸檔 -> 本機 Git commit
+commit (scc) -> 歸檔 -> 本機 Git commit
 ```
 
 `spec:analyze` 若發現衝突，只會列出衝突與待釐清問題，不會修改任何需求文件，也不會產出最終文件。釐清後應再次執行 `spec:analyze`，重新檢查並產出草稿。
@@ -334,7 +336,7 @@ commit -> 歸檔 -> 本機 Git commit
 ```text
 請先閱讀 project/REQ-001-pomodoro-timer/handoff.md。
 以 handoff.md 作為本次開發入口與限制摘要。
-如需完整需求細節，再查閱同資料夾內的 srs.md、uml.puml、openapi.yaml、db-schema.md 與 history.md。
+如需完整需求細節，再查閱同資料夾內的 srs.md、uml/、openapi.yaml、db-schema.md 與 history.md。
 不得自行新增 handoff.md 未確認的角色、權限、流程、狀態、API 或 DB 欄位。
 若發現 handoff.md 與既有程式或規格衝突，請停止開發並回報。
 ```
@@ -520,7 +522,8 @@ project/
   system-spec.md
   REQ-001-pomodoro-timer/
     srs.md
-    uml.puml
+    uml/
+      state.puml
     openapi.yaml
     db-schema.md
     handoff.md
@@ -591,3 +594,28 @@ git push origin master
 - `project/system-spec.md` 只能在 `spec:commit` 依使用者確認內容更新。
 - `spec:commit` 會自動建立本機 Git commit；remote push 需使用者明確要求或啟用 auto-push。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
+
+## 更新紀錄
+
+### v0.1.3
+- **支援指令簡寫別名（同時保留完整指令）**：
+  - `sci` ＝ `spec:init`
+  - `scp` ＝ `spec:propose`
+  - `sca` ＝ `spec:analyze`
+  - `scc` ＝ `spec:commit`
+  - 兩者完全等價，使用者可依輸入習慣自由選擇長指令或 3 字母縮寫。
+
+### v0.1.2
+- **新增 `sa-spec upgrade` 版本升級指令**：
+  - **工作區規則同步**：自動檢查並更新專案中的 `AGENTS.md`、`skills/system-analysis/SKILL.md` 以及 `rules/` 目錄下的規則文件至最新版本（自動保留既有的 memory context）。
+  - **既有需求自動遷移**：掃描 `project/REQ-*` 目錄，將舊版 `uml.puml` 自動重構移動為 `uml/main.puml`，並自動修復 `handoff.md` 中的來源引用路徑。
+  - **提供 `--dry-run` 模擬模式**：可加上 `--dry-run` 參數先行預覽哪些檔案會被更新或遷移，而不實際寫入檔案。
+
+### v0.1.1
+- **PlantUML 檔案架構重構（解決多圖渲染與預覽開不起來問題）**：
+  - **目錄化結構**：每個需求目錄下由原本單一檔案 `uml.puml` 改為 `uml/` 資料夾（預設提供 `uml/main.puml` 骨架）。
+  - **單檔單圖原則**：嚴格規範每個 `.puml` 檔案僅包含單一組 `@startuml` 與 `@enduml`，禁止在單一檔案內混放多張圖。
+  - **支援多面向拆分**：需求若涉及多個面向（如業務流程、循序互動、狀態轉換），必須拆分為獨立 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），確保 PlantUML 預覽外掛能順暢開啟與渲染。
+  - **CLI 自動化**：`sa-spec new` 與 `sa-spec template req` 自動建立 `uml/` 資料夾並產出預設的 `uml/main.puml`。
+  - **全專案規範同步**：同步更新 `AGENTS.md`、`system-analysis` skill、`rules/uml-style.md`、`rules/file-style.md` 與 `handoff.md`。
+

package/templates/rules/file-style.md

@@ -20,12 +20,11 @@
 - 每個需求資料夾至少包含：
   - `srs.md`：需求規格。
   - `history.md`：需求歷程。
-  - `uml.puml`：UML 圖。
+  - `uml/`：UML 圖目錄，依面向拆分為獨立 `.puml` 檔（如 `main.puml`、`sequence.puml` 等，單檔單圖，禁止單檔混放多圖）。
   - `openapi.yaml`：OpenAPI 草稿。
   - `db-schema.md`：DB Schema 草稿。
   - `handoff.md`：給 OpenSpec 或其他 AI 開發工具的開發交接摘要。
 - 若需求涉及畫面，使用 `wireframe.md`。
-- 若需求需要 UML，放入 `uml/` 資料夾。
 - 若需求需要 API 或資料模型，使用 `api.md` 或獨立資料模型文件。
 - 若需求需要 DB Table 設計，使用 `db-table.md`。
 
@@ -37,13 +36,12 @@ project/
     srs.md
     wireframe.md
     history.md
-    uml.puml
+    uml/
+      main.puml
+      sequence.puml
     openapi.yaml
     db-schema.md
     handoff.md
-    uml/
-      use-case.puml
-      sequence.puml
     api.md
     db-table.md
 ```

package/templates/rules/uml-style.md

@@ -2,7 +2,9 @@
 
 ## 格式
 - UML 圖一律使用 PlantUML。
-- PlantUML 檔案副檔名使用 `.puml`。
+- PlantUML 檔案副檔名使用 `.puml`，放置於需求的 `uml/` 資料夾中（例如 `uml/main.puml`、`uml/sequence.puml`）。
+- **嚴禁將多張圖混在同一個檔案中**：每個 `.puml` 檔案僅能包含單一組 `@startuml` 與 `@enduml`，避免 PlantUML 預覽或渲染工具解析失敗或無法開啟。
+- 若需求涉及多個面向（例如業務流程、循序互動、狀態轉換），必須依圖型或面向拆分成獨立的 `.puml` 檔案。
 - 圖表內容以繁體中文描述，並採用台灣常用語。
 
 ## 限制
@@ -10,6 +12,7 @@
 - 不明確的部分必須標示為「待確認」，並回到人工審核。
 - UML 必須能追溯到對應需求編號。
 - UML 內容不得超出已確認或已標示假設的需求範圍。
+- 單張圖應保持精簡清晰，避免過度龐大或單一圖節點過多導致渲染失敗。
 
 ## 圖表類型
 - Use Case Diagram：用於描述使用者、外部系統與系統功能邊界。

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

@@ -8,7 +8,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 ## 核心交付物
 
 - `srs.md`：需求規格。
-- `uml.puml`：UML 圖。
+- `uml/`：UML 圖目錄（依面向拆分為獨立 `.puml` 檔，如 `main.puml`、`sequence.puml` 等，禁止單檔混放多圖）。
 - `openapi.yaml`：OpenAPI 草稿。
 - `db-schema.md`：DB Schema 草稿。
 - `handoff.md`：給 OpenSpec 或其他 AI 開發工具的開發交接摘要。
@@ -16,12 +16,14 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 
 ## 指令流程
 
-| 指令 | 用途 | 執行規則 |
-|---|---|---|
-| `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` | `sci` | 初始化 | 載入並遵守 `AGENTS.md`、本 skill 與必要規則，確認 `project/` 結構是否存在。 |
+| `spec:propose` | `scp` | 提出需求 | 整理使用者需求為摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
+| `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。 |
 
 ## 硬性限制
 
@@ -42,7 +44,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 - `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 圖並清楚分段。
+- `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 ## analyze 衝突檢查
@@ -55,7 +57,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 - 所有 `project/REQ-*/openapi.yaml`
 - 所有 `project/REQ-*/db-schema.md`
 - 所有 `project/REQ-*/handoff.md`
-- 必要時讀取 `project/REQ-*/uml.puml`
+- 必要時讀取 `project/REQ-*/uml/*.puml`
 
 至少檢查：
 
@@ -81,7 +83,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 無衝突時，輸出一個待確認版本，包含：
 
 - SRS 草稿。
-- UML PlantUML 草稿。
+- UML PlantUML 草稿（放置於 `uml/` 資料夾中，每張圖獨立檔案）。
 - OpenAPI YAML 草稿。
 - DB Schema 草稿。
 - Handoff 交接摘要草稿。
@@ -97,7 +99,8 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 project/
   REQ-001-name/
     srs.md
-    uml.puml
+    uml/
+      main.puml
     openapi.yaml
     db-schema.md
     handoff.md
@@ -119,7 +122,7 @@ project/
 
 若需求不需要 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`。
+交給 OpenSpec 或其他 AI 開發工具時，應要求它先閱讀 `handoff.md`，並以 `handoff.md` 作為本次開發入口與限制摘要。若需要完整細節，再查閱同需求資料夾內的 `srs.md`、`uml/`、`openapi.yaml`、`db-schema.md` 與 `history.md`。
 
 歸檔完成後，必須只 stage 本次歸檔相關檔案，並建立本機 Git commit。commit message 格式：
 
@@ -132,10 +135,10 @@ docs(REQ-001): 需求名稱 - 簡短需求說明
 ## 狀態機
 
 ```text
-init -> propose -> analyze
+init (sci) -> propose (scp) -> analyze (sca)
 
-analyze 無衝突 -> 產出待確認版本 -> commit
-analyze 有衝突 -> 釐清問題 -> analyze
+analyze 無衝突 -> 產出待確認版本 -> commit (scc)
+analyze 有衝突 -> 釐清問題 -> analyze (sca)
 
-commit -> 歸檔 -> 本機 Git commit
+commit (scc) -> 歸檔 -> 本機 Git commit
 ```