universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bundled/skills/commands/migrate.md

@@ -0,0 +1,84 @@
+---
+description: "[UDS] Guide code migration, framework upgrades and technology modernization"
+allowed-tools: Read, Grep, Glob, Bash(npm:*, git:*)
+argument-hint: "[migration target or framework | 遷移目標或框架]"
+---
+
+# Migration Assistant | 遷移助手
+
+Guide code migration, framework upgrades and technology modernization.
+
+引導程式碼遷移、框架升級與技術現代化。
+
+## Workflow | 工作流程
+
+```
+ASSESS ──► PLAN ──► PREPARE ──► MIGRATE ──► VERIFY ──► CLEANUP
+```
+
+## Usage | 使用方式
+
+- `/migrate` - Start interactive migration guide
+- `/migrate --assess` - Assess migration scope and risk
+- `/migrate "Vue 2 to 3"` - Migrate specific framework
+- `/migrate --deps` - Dependency upgrade analysis
+- `/migrate --rollback` - Rollback strategy planning
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/migrate` | 詢問遷移目標，進入 ASSESS |
+| `/migrate --assess` | 直接執行範圍和風險評估 |
+| `/migrate "target"` | 以指定目標進入 ASSESS |
+| `/migrate --deps` | 僅分析相依套件升級 |
+| `/migrate --rollback` | 規劃回滾策略 |
+
+### Interaction Script | 互動腳本
+
+#### ASSESS Phase
+1. 分析現有程式碼和相依性
+2. 評估風險矩陣（breaking changes、資料遷移、API 變更）
+3. 展示評估報告
+
+🛑 **STOP**: 評估報告後等待使用者決定是否繼續
+
+#### PLAN Phase
+1. 制定遷移計畫（分階段步驟）
+2. 定義回滾策略
+
+🛑 **STOP**: 計畫確認後等待使用者確認
+
+#### MIGRATE Phase
+1. 逐步執行遷移
+2. 每個步驟後驗證
+
+🛑 **STOP**: 每個主要步驟完成後等待確認
+
+#### VERIFY Phase
+1. 執行測試確認遷移成功
+2. 生成驗證報告
+
+### Stop Points | 停止點
+
+| Phase | Stop Point | 等待內容 |
+|-------|-----------|---------|
+| ASSESS | 評估報告後 | 決定是否繼續 |
+| PLAN | 計畫制定後 | 確認計畫 |
+| MIGRATE | 每個主要步驟後 | 確認繼續 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 遷移步驟失敗 | 建議回滾到上一個檢查點 |
+| 相依性衝突 | 列出衝突，建議解決方案 |
+| 測試失敗 | 報告失敗，建議修復後重試 |
+
+## Reference | 參考
+
+- Full standard: [migration-assistant](../migration-assistant/SKILL.md)

package/bundled/skills/commands/pr.md

@@ -0,0 +1,72 @@
+---
+description: "[UDS] Guide Pull Request creation, review automation and merge strategies"
+allowed-tools: Read, Grep, Glob, Bash(git:*, gh:*)
+argument-hint: "[branch name or PR number | 分支名稱或 PR 編號]"
+---
+
+# PR Automation Assistant | PR 自動化助手
+
+Guide Pull Request creation, review automation and merge strategies.
+
+引導 Pull Request 建立、審查自動化和合併策略。
+
+## Workflow | 工作流程
+
+```
+CREATE ──► REVIEW ──► APPROVE ──► MERGE ──► CLEANUP
+```
+
+## Usage | 使用方式
+
+- `/pr` - Start interactive PR creation
+- `/pr create` - Create PR from current branch
+- `/pr --template` - Use PR template
+- `/pr review 123` - Review specific PR
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/pr` | 檢查當前分支狀態，詢問建立或審查 PR |
+| `/pr create` | 分析當前分支差異，建立 PR |
+| `/pr --template` | 使用 PR 模板建立 |
+| `/pr review <number>` | 審查指定 PR |
+
+### Interaction Script | 互動腳本
+
+#### CREATE
+1. 確認當前分支和目標分支
+2. 分析 commits，生成 PR title 和 description
+3. 展示 PR 內容預覽
+
+🛑 **STOP**: PR 內容確認後等待使用者確認建立
+
+#### REVIEW
+1. 取得 PR 差異
+2. 執行程式碼審查（套用 `/review` 標準）
+3. 展示審查結果
+
+🛑 **STOP**: 審查結果展示後等待使用者決定
+
+### Stop Points | 停止點
+
+| Phase | Stop Point | 等待內容 |
+|-------|-----------|---------|
+| CREATE | PR 內容預覽後 | 確認建立 |
+| REVIEW | 審查結果後 | 決定後續行動 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無遠端分支 | 建議先 push |
+| PR 已存在 | 展示現有 PR，詢問是否更新 |
+| CI 檢查失敗 | 列出失敗項目，建議修復 |
+
+## Reference | 參考
+
+- Full standard: [pr-automation-assistant](../pr-automation-assistant/SKILL.md)

package/bundled/skills/commands/refactor.md

@@ -166,6 +166,57 @@ This command integrates with:
 - **方法論系統** 追蹤重構進度
 - **TDD 助手** 用於紅-綠-重構循環
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/refactor` | 詢問重構目標和情境，引導選擇策略 |
+| `/refactor decide` | 直接執行重構 vs 重寫決策樹 |
+| `/refactor tactical` | 列出戰術性策略，詢問情境後推薦 |
+| `/refactor strategic` | 引導架構級重構規劃 |
+| `/refactor legacy` | 執行遺留程式碼安全策略引導 |
+| `/refactor debt` | 執行技術債評估 |
+
+### Interaction Script | 互動腳本
+
+#### `/refactor`（無子命令）
+1. 詢問重構情境（日常開發 / 架構變更 / 遺留程式碼）
+2. 依回答分派到 tactical / strategic / legacy
+
+#### `/refactor decide`
+1. 逐一提出決策樹問題（4 題）
+2. 等使用者回答每一題
+3. 根據答案路徑給出建議（重構 / 重寫 / 先加測試）
+
+🛑 **STOP**: 決策結果展示後等待使用者確認方向
+
+#### `/refactor tactical` / `strategic` / `legacy`
+1. 評估當前程式碼狀態（測試覆蓋率、複雜度）
+2. 推薦適合的策略
+3. 提供步驟式執行指引
+
+🛑 **STOP**: 策略推薦後等待使用者選擇，再提供執行引導
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 決策樹結果後 | 確認重構方向 |
+| 策略推薦後 | 選擇策略 |
+| 重構計畫制定後 | 確認開始執行 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 測試覆蓋率無法取得 | 建議先執行 `/coverage`，或詢問使用者估計 |
+| 重構範圍過大 | 建議分階段進行，先從最高風險區域開始 |
+| 無子命令且無法判斷情境 | 預設引導到 decide 決策樹 |
+
 ## Reference | 參考
 
 - [Refactoring Standards](../../core/refactoring-standards.md) - Core standard

package/bundled/skills/commands/release.md

@@ -49,6 +49,66 @@ Updates `CHANGELOG.md` by:
 /release finish 1.2.0
 ```
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/release` | 詢問版本號和發布類型（alpha/beta/rc/stable） |
+| `/release start <version>` | 開始指定版本的發布流程 |
+| `/release finish <version>` | 完成發布（tag、merge） |
+| `/release changelog <version>` | 更新 CHANGELOG.md |
+| `/release check` | 執行預發布檢查 |
+
+### Interaction Script | 互動腳本
+
+#### `/release start`
+1. 確認版本號和類型
+2. 執行預發布檢查（tests、lint、git status）
+
+🛑 **STOP**: 預發布檢查結果展示後等待確認
+
+3. 更新版本檔案
+
+🛑 **STOP**: 版本檔案更新後展示變更，等待確認
+
+4. 更新 CHANGELOG.md
+
+🛑 **STOP**: CHANGELOG 更新後展示內容，等待確認
+
+#### `/release finish`
+1. 確認所有檢查通過
+2. 建立 git tag
+
+🛑 **STOP**: git tag 建立前等待確認
+
+3. 展示 commit 和 push 命令
+
+🛑 **STOP**: git push 前等待確認
+
+#### `/release check`
+1. 執行所有預發布檢查腳本
+2. 展示結果摘要
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 版本檔案更新後 | 確認版本號正確 |
+| git tag 建立前 | 確認要建立 tag |
+| git push 前 | 確認要推送到遠端 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 預發布檢查失敗 | 列出失敗項目，阻止繼續 |
+| 版本號格式不正確 | 提示正確格式（X.Y.Z 或 X.Y.Z-type.N） |
+| 工作目錄不乾淨 | 建議先 commit 或 stash |
+
 ## References | 參考
 
 *   [Release Standards Skill](../release-standards/SKILL.md)

package/bundled/skills/commands/requirement.md

@@ -48,6 +48,44 @@ So that [benefit].
 - `/requirement user login` - Write requirement for specific feature
 - `/requirement "users can export data"` - Based on description
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/requirement` | 詢問使用者要定義的功能，開始互動式需求撰寫 |
+| `/requirement <feature>` | 以指定功能為目標，開始收集資訊 |
+| `/requirement "description"` | 從描述中提取需求，生成使用者故事 |
+
+### Interaction Script | 互動腳本
+
+1. 收集功能描述和使用者角色
+2. 引導定義 As a / I want / So that
+3. 引導定義 Acceptance Criteria（GWT 格式）
+4. 以 INVEST 準則逐項驗證
+
+**Decision: INVEST 驗證結果**
+- IF 全部通過 → 展示完整需求文件
+- IF 有項目未通過 → 指出哪些未通過，建議修改方式
+
+🛑 **STOP**: 展示需求文件後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 需求文件生成後 | 確認內容正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 使用者描述過於模糊 | 提出具體問題釐清範圍 |
+| AC 無法用 GWT 格式表達 | 協助轉換，展示轉換建議 |
+
 ## Reference | 參考
 
 - Full standard: [requirement-assistant](../requirement-assistant/SKILL.md)

package/bundled/skills/commands/reverse-bdd.md

@@ -41,6 +41,40 @@ Feature: User Login [Inferred]
 | `/reverse-bdd src/auth/` | Extract BDD from auth module | 從 auth 模組擷取 BDD |
 | `/reverse-bdd specs/SPEC-001.md` | Convert spec AC to BDD | 將規格 AC 轉為 BDD |
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/reverse-bdd` | 詢問目標（原始碼目錄或 spec 檔案） |
+| `/reverse-bdd <path>` | 直接分析指定路徑 |
+
+### Interaction Script | 互動腳本
+
+1. 判斷輸入類型（原始碼 or spec）
+2. 分析行為模式，擷取隱含的 Given-When-Then 流程
+3. 為每個場景標記確定性：`[Confirmed]`、`[Inferred]`
+4. 生成 Gherkin `.feature` 檔案（含 `[Source: file:line]` 引用）
+5. 展示結果
+
+🛑 **STOP**: 展示 `.feature` 內容後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| `.feature` 生成後 | 確認場景正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 行為模式模糊無法轉為場景 | 標記 `[Assumption]`，列出需人工確認的場景 |
+| 目標無可分析的行為邏輯 | 告知並建議檢查是否為正確的檔案 |
+
 ## Reference | 參考
 
 - Parent command: [/reverse](../reverse-engineer/SKILL.md)

package/bundled/skills/commands/reverse-sdd.md

@@ -45,6 +45,48 @@ Source Code ──► Analyze ──► Extract Requirements ──► Generate
 | `/reverse-sdd src/auth/` | Reverse engineer auth module | 反向工程 auth 模組 |
 | `/reverse-sdd` | Interactive — ask for target | 互動式 — 詢問目標 |
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/reverse-sdd` | 詢問使用者要分析的原始碼路徑 |
+| `/reverse-sdd <path>` | 直接分析指定路徑 |
+
+### Interaction Script | 互動腳本
+
+1. 掃描目標路徑的程式碼結構和相依性
+2. 擷取隱含需求、API 合約、商業規則
+3. 為每個發現分類確定性：`[Confirmed]`、`[Inferred]`、`[Assumption]`
+
+**Decision: 確定性門檻**
+- IF 有對應測試佐證 → `[Confirmed]`
+- IF 從程式碼邏輯推斷 → `[Inferred]`
+- IF 無直接證據 → `[Assumption]`
+
+4. 生成 SDD 格式的規格文件
+5. 展示結果（含確定性標記）
+
+🛑 **STOP**: 展示生成的 spec 後等待使用者審查並確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 生成 spec 後 | 使用者審查確定性標記，確認寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 路徑不存在 | 告知並詢問正確路徑 |
+| 程式碼過大（>50 檔案） | 建議縮小範圍，或列出模組供選擇 |
+| 無法辨識程式語言 | 詢問使用者確認語言 |
+| 所有發現都是 `[Assumption]` | 警告信心不足，建議人工審查後再使用 |
+
 ## Reference | 參考
 
 - Parent command: [/reverse](../reverse-engineer/SKILL.md)

package/bundled/skills/commands/reverse-tdd.md

@@ -45,6 +45,46 @@ Analyze gaps between BDD scenarios and TDD test coverage.
 | `/reverse-tdd features/` | Analyze all feature files | 分析所有 feature 檔案 |
 | `/reverse-tdd features/auth.feature` | Analyze specific feature | 分析特定 feature |
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/reverse-tdd` | 詢問要分析的 feature 檔案或測試目錄 |
+| `/reverse-tdd <path>` | 直接分析指定路徑 |
+
+### Interaction Script | 互動腳本
+
+1. 解析 `.feature` 檔案中的所有場景
+2. 掃描測試目錄尋找對應的單元測試
+3. 建立 BDD 場景 → TDD 測試的對應關係
+4. 識別覆蓋差距（有場景無對應測試）
+5. 生成差距報告
+
+**Decision: 差距嚴重度**
+- IF 覆蓋率 ≥ 80% → 標記為 ✅ Good，列出剩餘差距
+- IF 覆蓋率 50-79% → 標記為 ⚠️ Needs Improvement，建議優先補測試的場景
+- IF 覆蓋率 < 50% → 標記為 ❌ Critical，建議系統性補強
+
+🛑 **STOP**: 展示差距報告後等待使用者決定下一步
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 差距報告展示後 | 使用者決定是否要 AI 協助補測試 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無 `.feature` 檔案 | 引導到 `/derive-bdd` 或 `/reverse-bdd` 先生成 |
+| 測試目錄為空 | 報告 0% 覆蓋率，建議從 `/derive-tdd` 生成骨架 |
+| 場景與測試命名不一致無法自動對應 | 列出無法對應的項目，詢問使用者手動確認 |
+
 ## Reference | 參考
 
 - Parent command: [/reverse](../reverse-engineer/SKILL.md)

package/bundled/skills/commands/reverse.md

@@ -57,6 +57,47 @@ Checks if the scenarios in the feature file have corresponding unit tests.
 *   **Certainty Tags**: Use `[Confirmed]`, `[Inferred]`, `[Unknown]` tags in output.
 *   **Source Attribution**: Cite `file:line` for all reversed logic.
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/reverse` | 詢問使用者要執行哪個子命令（spec/bdd/tdd）和目標 |
+| `/reverse <subcommand> <input>` | 直接對指定目標執行指定子命令 |
+| `/reverse <subcommand>` | 執行子命令，詢問目標檔案/目錄 |
+
+### Interaction Script | 互動腳本
+
+1. 確認子命令和輸入目標
+2. 分派到對應的 `/reverse-sdd`、`/reverse-bdd`、`/reverse-tdd`
+3. 收集子命令結果
+4. 展示結果摘要
+
+**Decision: 子命令選擇**
+- IF `spec` → 分派到 `/reverse-sdd`
+- IF `bdd` → 分派到 `/reverse-bdd`
+- IF `tdd` → 分派到 `/reverse-tdd`
+- IF 未指定 → 問使用者選擇
+
+🛑 **STOP**: 結果展示後等待使用者確認
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 反向工程結果展示後 | 確認結果正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 目標檔案/目錄不存在 | 告知並詢問正確路徑 |
+| 子命令無效 | 列出可用子命令（spec/bdd/tdd） |
+| 目標為空目錄或空檔案 | 告知無內容可分析 |
+
 ## References | 參考
 
 *   [Reverse Engineering Skill](../reverse-engineer/SKILL.md)

package/bundled/skills/commands/review.md

@@ -44,6 +44,45 @@ Perform systematic code review using standardized checklists and comment prefixe
 - `/review src/auth.js` - Review specific file
 - `/review feature/login` - Review specific branch
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/review` | 執行 `git diff` 取得當前分支所有變更，開始審查 |
+| `/review <file>` | 僅審查指定檔案 |
+| `/review <branch>` | 審查指定分支相對於 main 的差異 |
+
+### Interaction Script | 互動腳本
+
+1. 取得變更內容（git diff / 讀取檔案）
+2. 逐一套用 8 個審查類別
+3. 為每個發現標記嚴重度前綴（BLOCKING / IMPORTANT / SUGGESTION / QUESTION / NOTE）
+4. 生成審查報告
+
+**Decision: 發現衝突**
+- IF 多個發現互相矛盾（如效能 vs 可讀性） → 明確說明取捨，標記為 QUESTION 請使用者決定
+- ELSE → 依嚴重度排序呈現
+
+🛑 **STOP**: 報告生成後展示結果，等待使用者決定處理方式
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 審查報告展示後 | 使用者決定是否修復 BLOCKING 項目 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無變更可審查 | 告知無差異，建議先修改程式碼 |
+| 檔案/分支不存在 | 列出可用的檔案或分支 |
+| 變更量過大（>500 行） | 建議分批審查，列出建議的分批方式 |
+
 ## Reference | 參考
 
 - Full standard: [code-review-assistant](../code-review-assistant/SKILL.md)

package/bundled/skills/commands/scan.md

@@ -0,0 +1,68 @@
+---
+description: "[UDS] Guide automated security scanning, dependency auditing and secret detection"
+allowed-tools: Read, Grep, Glob, Bash(npm:audit, npx:*)
+argument-hint: "[scan type or target | 掃描類型或目標]"
+---
+
+# Security Scan Assistant | 安全掃描助手
+
+Guide automated security scanning, dependency auditing and secret detection.
+
+引導自動化安全掃描、相依套件審計和機密偵測。
+
+## Workflow | 工作流程
+
+```
+SCAN ──► TRIAGE ──► PRIORITIZE ──► FIX ──► VERIFY
+```
+
+## Usage | 使用方式
+
+- `/scan` - Run all security scans
+- `/scan --deps` - Dependency vulnerability scan
+- `/scan --secrets` - Secret detection scan
+- `/scan --license` - License compliance check
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/scan` | 執行所有掃描類型 |
+| `/scan --deps` | 僅執行相依套件漏洞掃描 |
+| `/scan --secrets` | 僅執行機密偵測 |
+| `/scan --license` | 僅執行授權合規檢查 |
+
+### Interaction Script | 互動腳本
+
+1. 執行指定類型的掃描
+2. 收集結果，依嚴重程度分類
+3. 展示分類報告
+
+**Decision: 掃描結果**
+- IF 發現 Critical/High → 列出 SLA 修復時限，建議立即處理
+- IF 僅 Medium/Low → 列入報告，建議排程處理
+- IF 發現機密洩漏 → 立即警告，建議輪換金鑰
+
+🛑 **STOP**: 報告展示後等待使用者決定修復優先順序
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 掃描報告展示後 | 使用者決定修復項目 |
+| 修復建議展示後 | 確認套用修復 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 掃描工具未安裝 | 建議安裝（npm audit 通常內建） |
+| 無 package.json 或 lock 檔 | 告知無法執行相依掃描 |
+
+## Reference | 參考
+
+- Full standard: [security-scan-assistant](../security-scan-assistant/SKILL.md)

package/bundled/skills/commands/sdd-retro.md

@@ -33,6 +33,54 @@ Create lightweight specification documents for past changes that were committed
 /sdd-retro --last=10
 ```
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/sdd-retro` | 掃描所有 feat/fix commits（無 `Refs:` footer），顯示摘要 |
+| `/sdd-retro --since=<date>` | 僅掃描指定日期後的 commits |
+| `/sdd-retro --last=<N>` | 僅掃描最近 N 筆 commits |
+
+### Interaction Script | 互動腳本
+
+1. 執行 `git log` 掃描符合條件的 commits
+2. 過濾已有 `Refs: SPEC-` 的 commits
+3. 依 scope 分群相關 commits
+
+**Decision: 掃描結果**
+- IF 無未追蹤的 commits → 告知使用者「所有 feat/fix commits 都已追蹤」，結束
+- IF 有未追蹤的 commits → 顯示分群清單，問使用者要為哪些群組建立 retro spec
+- ELSE → 顯示清單供選擇
+
+🛑 **STOP**: 掃描結果展示後等待使用者選擇要追蹤的群組
+
+4. 為使用者選定的群組生成 retro spec（使用 SDD 格式，status: Archived）
+5. 展示生成的 spec 內容
+
+🛑 **STOP**: 展示 spec 內容後等待使用者確認寫入檔案
+
+6. 寫入 `docs/specs/` 並建議更新原 commits 的 footer（如有需要）
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 掃描結果展示後 | 使用者選擇要追蹤哪些群組 |
+| Spec 內容生成後 | 確認寫入檔案 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 不在 git 倉庫中 | 告知使用者需要在 git 倉庫中執行 |
+| git log 無結果 | 告知無符合條件的 commits |
+| `docs/specs/` 目錄不存在 | 自動建立目錄 |
+| commit message 格式不符合 Conventional Commits | 標記為 `[Unknown]` scope，仍嘗試分析 |
+
 ## Reference | 參考
 
 - SDD workflow: [sdd command](sdd.md)