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

package/bundled/skills/commands/checkin.md

@@ -30,6 +30,7 @@ Verify pre-commit quality gates before committing code to ensure codebase stabil
 | **Build** | Code compiles with zero errors | 編譯零錯誤 |
 | **Tests** | All existing tests pass (100%) | 所有測試通過 |
 | **Coverage** | Test coverage not decreased | 覆蓋率未下降 |
+| **AC Coverage** | AC-to-test coverage ≥ 80% ([`/ac-coverage`](./ac-coverage.md)) | AC 覆蓋率 ≥ 80% |
 | **Code Quality** | Follows coding standards, no code smells | 符合編碼規範 |
 | **Security** | No hardcoded secrets or vulnerabilities | 無硬編碼密鑰 |
 | **Documentation** | API docs and CHANGELOG updated if needed | 文件已更新 |
@@ -47,7 +48,52 @@ Verify pre-commit quality gates before committing code to ensure codebase stabil
 
 After verification passes, proceed with `/commit` to create the commit message.
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/checkin` | 自動執行所有品質關卡檢查 |
+
+### Interaction Script | 互動腳本
+
+1. 執行 `git status` 確認有待提交的變更
+2. 依序檢查每個品質關卡：
+   - Build → Tests → Coverage → Code Quality → Security → Documentation → Workflow
+3. 為每個關卡標記 ✅ PASS / ❌ FAIL
+4. 生成摘要報告
+
+**Decision: 測試指令偵測**
+- IF 專案有 `package.json` → 使用 `npm test`
+- IF 專案有 `pyproject.toml` → 使用 `pytest`
+- IF 無法偵測 → 詢問使用者
+
+**Decision: 檢查結果**
+- IF 全部通過 → 建議執行 `/commit`
+- IF 有 FAIL → 列出失敗項目和修復建議，不建議 commit
+
+🛑 **STOP**: 報告展示後等待使用者決定（修復 or 強制 commit）
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 品質報告展示後 | 使用者決定修復或 commit |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無待提交變更 | 告知無變更可檢查 |
+| 測試指令執行失敗 | 報告錯誤，建議檢查測試環境 |
+| lint 工具未安裝 | 跳過該關卡，標記 ⚠️ SKIP |
+
 ## References | 參考
 
 *   [Check-in Assistant Skill](../checkin-assistant/SKILL.md)
 *   [Core Standard](../../core/checkin-standards.md)
+*   [AC Coverage Command](./ac-coverage.md) — AC-to-test traceability analysis
+*   [AC Traceability Standard](../../core/acceptance-criteria-traceability.md)

package/bundled/skills/commands/ci-cd.md

@@ -0,0 +1,69 @@
+---
+description: "[UDS] Guide CI/CD pipeline design, configuration and optimization"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[pipeline config or stage | Pipeline 配置或階段]"
+---
+
+# CI/CD Assistant | CI/CD 助手
+
+Guide CI/CD pipeline design, configuration and optimization.
+
+引導 CI/CD 管線設計、配置和優化。
+
+## Workflow | 工作流程
+
+```
+BUILD ──► TEST ──► ANALYZE ──► DEPLOY ──► VERIFY
+```
+
+## Usage | 使用方式
+
+- `/ci-cd` - Start interactive pipeline design
+- `/ci-cd github-actions` - Design for specific platform
+- `/ci-cd --optimize` - Optimize existing pipeline
+- `/ci-cd build` - Focus on build stage
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/ci-cd` | 偵測現有 CI 配置（`.github/workflows/`、`.gitlab-ci.yml` 等），展示狀態或開始設計 |
+| `/ci-cd <platform>` | 為指定平台設計管線 |
+| `/ci-cd --optimize` | 分析現有管線，提出優化建議 |
+| `/ci-cd <stage>` | 聚焦特定階段（build/test/deploy） |
+
+### Interaction Script | 互動腳本
+
+1. 偵測專案技術棧和現有 CI 配置
+2. 依據需求設計或優化管線
+
+**Decision: 現有配置**
+- IF 已有 CI 配置 → 分析現狀，建議優化
+- IF 無 CI 配置 → 引導從頭設計
+- IF `--optimize` → 直接進入優化分析
+
+3. 逐階段設計（BUILD→TEST→ANALYZE→DEPLOY→VERIFY）
+4. 展示完整管線配置
+
+🛑 **STOP**: 配置展示後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 管線設計完成後 | 確認配置正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無法偵測 CI 平台 | 列出支援的平台供選擇 |
+| 現有配置語法錯誤 | 報告錯誤位置，建議修正 |
+
+## Reference | 參考
+
+- Full standard: [ci-cd-assistant](../ci-cd-assistant/SKILL.md)

package/bundled/skills/commands/commit.md

@@ -10,6 +10,35 @@ Generate well-formatted commit messages following the Conventional Commits stand
 
 根據 staged 的變更，產生符合 Conventional Commits 格式的 commit message。
 
+## Pre-Flight Checks | 前置檢查
+
+Before generating a commit, the AI assistant MUST run these checks:
+
+在產生 commit 前，AI 助手必須執行以下檢查：
+
+| Check | Command | On Failure |
+|-------|---------|------------|
+| Staged changes exist | `git diff --cached --stat` | → Guide user to `git add` |
+| No merge conflicts | `grep -r "<<<<<<< " --include="*.{js,ts,md,yaml}" .` | → Resolve conflicts first |
+| Tests pass (if feat/fix) | `cd cli && npm run test:unit` (or project test cmd) | → Fix tests before committing |
+| Spec reference (feat/fix) | Check `docs/specs/SPEC-*.md` for active specs | → Suggest `Refs: SPEC-XXX` in footer |
+
+### Spec Tracking Gate | Spec 追蹤閘門
+
+For `feat` and `fix` type commits:
+1. **Check**: `ls docs/specs/SPEC-*.md 2>/dev/null` — any active specs?
+2. **If specs exist**: Suggest adding `Refs: SPEC-XXX` to commit footer
+3. **If no specs and change is significant** (>3 files or new API): Suggest creating a spec via `/sdd`
+4. **Mode**: This is advisory (non-blocking) — user can always proceed without a spec reference
+
+對於 `feat` 和 `fix` 類型的提交：
+1. **檢查**：是否有活躍的規格？
+2. **如果有規格**：建議在 footer 加入 `Refs: SPEC-XXX`
+3. **如果沒有規格且變更顯著**：建議透過 `/sdd` 建立規格
+4. **模式**：這是建議性的（非阻斷）— 使用者可以不引用規格
+
+---
+
 ## Workflow | 工作流程
 
 1. **Check status** - Run `git status` and `git diff --staged` to understand changes
@@ -49,6 +78,56 @@ If a spec is linked, add `Refs: SPEC-XXX` to the commit footer. This is advisory
 - `/commit` - Auto-analyze changes and suggest commit message
 - `/commit fix login bug` - Generate message based on provided description
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action | AI 行為 |
+|-------|-----------|--------|
+| `/commit` | 執行 Pre-Flight Checks → 分析 staged 變更 → 產生 commit message → 等待確認 | Run checks, analyze, generate, confirm |
+| `/commit <description>` | 以描述為基礎，結合 staged diff 產生 commit message → 等待確認 | Use description + diff to generate message |
+
+### Interaction Script | 互動腳本
+
+1. 執行 `git diff --cached --stat` 確認有 staged 變更
+2. 執行 `git status` 和 `git diff --staged` 了解變更內容
+3. 判斷 commit 類型（feat/fix/refactor/docs/...）和範圍
+
+**Decision: Pre-Flight Check 結果**
+- IF 無 staged 變更 → 引導使用者 `git add`，停止
+- IF 有合併衝突標記 → 提示先解決衝突，停止
+- IF 類型為 feat/fix → 執行測試 + Spec 追蹤評估
+
+4. 產生 commit message（subject + body + footer）
+5. 展示完整 message 供使用者確認
+
+**Decision: Spec 追蹤（僅 feat/fix）**
+- IF 有活躍 spec → 建議在 footer 加 `Refs: SPEC-XXX`
+- IF 無 spec 且變更顯著（>3 檔案或新 API） → 建議 `/sdd`
+- 此為建議性（non-blocking），使用者可忽略
+
+🛑 **STOP**: 展示 commit message 後等待使用者確認或修改
+
+6. 使用者確認後執行 `git commit`
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| Pre-Flight 失敗 | 使用者修復問題後重新執行 |
+| Message 展示後 | 確認 message 正確，或要求修改 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無 staged 變更 | 顯示 `git add` 指引，不嘗試 commit |
+| 合併衝突存在 | 提示解決衝突，列出衝突檔案 |
+| 測試失敗（feat/fix） | 顯示失敗摘要，建議修復後再 commit |
+| commit 執行失敗 | 顯示 git 錯誤訊息，不重試 |
+
 ## Reference | 參考
 
 - Full standard: [commit-standards](../commit-standards/SKILL.md)

package/bundled/skills/commands/config.md

@@ -206,6 +206,54 @@ CLI 在 `manifest.declinedFeatures` 中追蹤拒絕的 Skills/Commands：
 | `--yes`, `-y` | Skip confirmation prompt | 跳過確認提示 |
 | `-E`, `--experimental` | Enable experimental features | 啟用實驗性功能 |
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action | AI 行為 |
+|-------|-----------|--------|
+| `/config` | 顯示目前狀態 → 詢問配置類型 → 執行 | Show status, ask type, execute |
+| `/config <type>` | 直接執行指定類型配置（如 `skills`、`ai_tools`） | Execute specific config type |
+| `/config --ai-tool <tool>` | 非互動式為特定工具安裝 Skills/Commands | Non-interactive install for tool |
+
+### Interaction Script | 互動腳本
+
+1. 執行 `uds check --summary` 顯示目前狀態
+
+**Decision: 有無指定 type**
+- IF 指定了 type → 直接執行 `uds configure --type <type>`
+- IF 指定了 `--ai-tool` → 非互動式執行安裝
+- ELSE → 進入互動流程
+
+2. 詢問配置類型（AskUserQuestion）：
+   - Basic Options / AI Tools / Skills / Commands / Advanced / All
+
+3. 根據選擇執行對應 CLI 命令
+
+**Decision: Skills/Commands 配置**
+- IF 選擇 Skills → 顯示安裝狀態 + 拒絕狀態 → 動作選單
+- IF 選擇 Commands → 同上流程
+
+🛑 **STOP**: 顯示目前狀態後等待使用者選擇配置類型
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 狀態顯示後 | 使用者選擇要配置的類型 |
+| Skills/Commands 動作選單 | 使用者選擇安裝/更新/重新安裝 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 標準未初始化 | 提示先執行 `/init` |
+| 無效的 config type | 列出可用類型供選擇 |
+| 指定的 AI tool 不支援 | 列出支援的工具清單 |
+| 之前拒絕的 Skills/Commands | 提示可透過此命令重新安裝 |
+
 ## Reference | 參考
 
 - CLI documentation: `uds configure --help`

package/bundled/skills/commands/coverage.md

@@ -53,7 +53,60 @@ Analyze test coverage across multiple dimensions and provide actionable recommen
 - `/coverage src/auth` - Analyze specific module
 - `/coverage --recommend` - Get test recommendations
 
+## AC Coverage (Requirement-Level) | AC 覆蓋率（需求層級）
+
+This command (`/coverage`) analyzes **code-level** coverage (line/branch/function). For **requirement-level** coverage — tracking which Acceptance Criteria have corresponding tests — use [`/ac-coverage`](./ac-coverage.md).
+
+本命令（`/coverage`）分析**程式碼層級**覆蓋率。若需**需求層級**覆蓋率 — 追蹤哪些 AC 有對應測試 — 請使用 [`/ac-coverage`](./ac-coverage.md)。
+
+| | `/coverage` | `/ac-coverage` |
+|-|-------------|----------------|
+| **Level** | Code (line/branch/function) | Requirements (AC-to-test) |
+| **Question** | "How much code is tested?" | "Which AC have tests?" |
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/coverage` | 偵測測試框架，執行全專案覆蓋率分析 |
+| `/coverage <path>` | 僅分析指定模組/路徑 |
+| `/coverage --recommend` | 分析後重點輸出測試建議 |
+
+### Interaction Script | 互動腳本
+
+1. 偵測專案測試框架和覆蓋率工具
+2. 執行覆蓋率報告
+3. 解析結果，識別低覆蓋率區域
+4. 依風險和重要性排序
+5. 提出具體測試建議
+
+**Decision: 覆蓋率結果**
+- IF 覆蓋率 ≥ 目標 → 展示摘要，標記 ✅
+- IF 覆蓋率 < 目標但 ≥ 60% → 展示差距，建議優先補測試的區域
+- IF 覆蓋率 < 60% → 警告，建議系統性補強計畫
+
+🛑 **STOP**: 報告展示後等待使用者決定是否補寫測試
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 覆蓋率報告展示後 | 使用者決定是否補測試 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無測試框架 | 詢問使用者選擇框架 |
+| 覆蓋率工具執行失敗 | 報告錯誤，建議手動檢查配置 |
+| 指定路徑不存在 | 列出可用路徑 |
+
 ## Reference | 參考
 
 - Full standard: [test-coverage-assistant](../test-coverage-assistant/SKILL.md)
 - Core guide: [testing-standards](../../core/testing-standards.md)
+- AC coverage: [/ac-coverage](./ac-coverage.md) — requirement-level traceability

package/bundled/skills/commands/database.md

@@ -0,0 +1,70 @@
+---
+description: "[UDS] Guide database design, migration planning and query optimization"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[schema or migration to review | 要審查的 schema 或遷移]"
+---
+
+# Database Assistant | 資料庫助手
+
+Guide database design, migration planning and query optimization.
+
+引導資料庫設計、遷移規劃和查詢最佳化。
+
+## Workflow | 工作流程
+
+```
+PLAN ──► WRITE ──► TEST ──► DEPLOY ──► VERIFY
+```
+
+## Usage | 使用方式
+
+- `/database` - Start interactive database design
+- `/database schema` - Review or design schema
+- `/database --migration` - Plan migration
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/database` | 詢問任務類型（schema 設計 / 遷移規劃 / 查詢優化） |
+| `/database schema` | 進入 schema 設計/審查模式 |
+| `/database --migration` | 進入遷移規劃模式 |
+
+### Interaction Script | 互動腳本
+
+1. 確認任務類型和目標
+2. 分析現有 schema 或遷移檔案
+
+**Decision: 任務類型**
+- IF schema 設計 → 引導正規化、索引設計、關聯定義
+- IF 遷移規劃 → 評估風險、產生遷移腳本、規劃回滾
+- IF 查詢優化 → 分析慢查詢、建議索引
+
+3. 展示設計/計畫結果
+
+🛑 **STOP**: 結果展示後等待使用者確認
+
+🛑 **STOP**: 遷移腳本寫入前等待使用者確認
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 設計/計畫展示後 | 確認方案 |
+| 遷移腳本生成後 | 確認寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 無法偵測資料庫類型 | 詢問使用者（PostgreSQL/MySQL/MongoDB 等） |
+| 遷移存在資料遺失風險 | 明確警告，要求使用者確認 |
+
+## Reference | 參考
+
+- Full standard: [database-assistant](../database-assistant/SKILL.md)
+- Core guide: [database-standards](../../core/database-standards.md)

package/bundled/skills/commands/derive-all.md

@@ -46,6 +46,46 @@ SPEC-XXX.md ──► /derive-bdd ──► /derive-tdd ──► [/derive-atdd]
 # Step 4: Implement — fill [TODO] markers
 ```
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/derive-all` | 列出 status=Approved 的 spec 供選擇 |
+| `/derive-all <spec-file>` | 直接對指定 spec 執行完整推演 |
+
+### Interaction Script | 互動腳本
+
+1. 讀取並驗證 spec（status = Approved）
+2. 依序執行：`/derive-bdd` → `/derive-tdd` → 詢問是否需要 `/derive-atdd`
+
+**Decision: ATDD 推演**
+- IF 使用者要求 → 執行 `/derive-atdd`
+- ELSE → 跳過 ATDD
+
+🛑 **STOP**: BDD + TDD 推演完成後，詢問是否需要 ATDD 推演
+
+3. 生成 `DERIVATION-REPORT.md` 彙總所有輸出
+4. 展示報告摘要
+
+🛑 **STOP**: 展示所有生成檔案清單後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 所有推演完成後 | 確認寫入所有檔案 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| Spec status ≠ Approved | 引導到 `/sdd approve` |
+| 子命令推演失敗 | 報告哪個推演失敗，已成功的仍保留，詢問是否繼續 |
+
 ## Reference | 參考
 
 - Parent command: [/derive](../forward-derivation/SKILL.md)

package/bundled/skills/commands/derive-atdd.md

@@ -43,6 +43,39 @@ SPEC-XXX.md ──► Parse AC ──► Generate acceptance.md ──► Review
 
 > **Note**: BDD scenarios already serve as executable acceptance tests. `/derive-atdd` is for specialized manual testing workflows.
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/derive-atdd` | 列出 status=Approved 的 spec 供選擇 |
+| `/derive-atdd <spec-file>` | 直接從指定 spec 推演 ATDD 表格 |
+
+### Interaction Script | 互動腳本
+
+1. 讀取 spec，擷取所有 AC
+2. 將每個 AC 映射為驗收測試表格（Given-When-Then 欄位）
+3. 為每個 AC 生成多筆測試資料（正向 + 反向 + 邊界值）
+4. 展示生成的 `acceptance.md` 內容
+
+🛑 **STOP**: 展示表格後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 驗收測試表格生成後 | 確認內容正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| AC 缺乏具體的輸入/輸出描述 | 標記 `[TODO: needs test data]`，繼續其餘 AC |
+| Spec 無 AC | 告知並引導修改 spec |
+
 ## Reference | 參考
 
 - Parent command: [/derive](../forward-derivation/SKILL.md)

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

@@ -41,6 +41,45 @@ Feature: [Feature Name]
 | `/derive-bdd specs/SPEC-001.md` | Derive BDD from specific spec | 從特定規格推演 BDD |
 | `/derive-bdd` | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/derive-bdd` | 列出 status=Approved 的 spec 供選擇 |
+| `/derive-bdd <spec-file>` | 直接從指定 spec 推演 BDD 場景 |
+
+### Interaction Script | 互動腳本
+
+1. 讀取 spec，擷取所有 AC
+2. 將每個 AC 映射為一個 Gherkin Scenario（1:1）
+3. 加入 `@SPEC-XXX` 和 `@AC-N` tags
+4. 展示生成的 `.feature` 內容
+
+**Decision: 輸出位置**
+- IF 專案有 `tests/features/` 目錄 → 輸出到該目錄
+- IF 專案有 `features/` 目錄 → 輸出到該目錄
+- ELSE → 詢問使用者輸出位置
+
+🛑 **STOP**: 展示 `.feature` 內容後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| `.feature` 生成後 | 確認內容正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| AC 非 GWT 格式 | 嘗試轉換並標記 `[Derived]`，展示供確認 |
+| Spec 無 AC | 告知並引導修改 spec |
+| 生成的 Gherkin 語法無效 | 自動修正語法，標記修正處 |
+
 ## Reference | 參考
 
 - Parent command: [/derive](../forward-derivation/SKILL.md)

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

@@ -42,6 +42,46 @@ describe('SPEC-001: [Feature Name]', () => {
 | `/derive-tdd specs/SPEC-001.md` | Derive TDD from specific spec | 從特定規格推演 TDD |
 | `/derive-tdd` | Interactive — ask for spec file | 互動式 — 詢問規格檔案 |
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/derive-tdd` | 列出 status=Approved 的 spec 供選擇 |
+| `/derive-tdd <spec-file>` | 直接從指定 spec 推演 TDD 骨架 |
+
+### Interaction Script | 互動腳本
+
+1. 讀取 spec，擷取所有 AC
+2. 偵測專案語言和測試框架
+
+**Decision: 語言/框架偵測**
+- IF 找到 `vitest.config` / `jest.config` → 使用對應框架
+- IF 找到 `pytest.ini` / `pyproject.toml` → 使用 pytest
+- IF 無法偵測 → 詢問使用者
+
+3. 將每個 AC 映射為 `describe`/`it` block（含 AAA 註解和 `[TODO]` 標記）
+4. 展示生成的測試檔案內容
+
+🛑 **STOP**: 展示測試骨架後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 測試骨架生成後 | 確認內容正確並寫入 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| AC 過於抽象無法轉為測試 | 標記 `[TODO: AC needs refinement]`，繼續其餘 AC |
+| 無法偵測語言/框架 | 詢問使用者指定 |
+| Spec 無 AC | 告知並引導修改 spec |
+
 ## Reference | 參考
 
 - Parent command: [/derive](../forward-derivation/SKILL.md)

package/bundled/skills/commands/derive.md

@@ -66,6 +66,53 @@ Generate derived artifacts (BDD scenarios, TDD skeletons, ATDD tables) from appr
 /derive atdd specs/SPEC-001.md
 ```
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/derive` | 列出 `docs/specs/` 中 status=Approved 的 spec，問使用者選擇 spec 和子命令 |
+| `/derive <subcommand> <spec-file>` | 直接對指定 spec 執行指定子命令 |
+| `/derive <subcommand>` | 執行指定子命令，列出可用 spec 供選擇 |
+| `/derive <spec-file>` | 對指定 spec 執行 `all`（預設子命令） |
+
+### Interaction Script | 互動腳本
+
+1. 讀取 spec 檔案，驗證 status = Approved
+2. 擷取所有 AC，確認使用 GWT 格式
+
+**Decision: AC 格式**
+- IF AC 使用 GWT 格式 → 直接推演
+- IF AC 不是 GWT 格式 → 嘗試轉換，標記 `[Derived]`，展示轉換結果
+- IF AC 無法轉換 → 🛑 STOP，請使用者先修改 spec 中的 AC 格式
+
+🛑 **STOP**: AC 格式轉換後展示結果，等待使用者確認轉換正確再繼續
+
+3. 依子命令分派到 `/derive-bdd`、`/derive-tdd`、`/derive-atdd`
+4. 驗證 1:1 對應（每個 AC 恰好一個測試/場景）
+5. 展示推演摘要
+
+🛑 **STOP**: 展示生成的測試工件後等待使用者確認寫入
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| AC 格式轉換後 | 確認轉換結果 |
+| 測試工件生成後 | 確認寫入檔案 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| Spec status ≠ Approved | 告知當前 status，引導到 `/sdd approve` |
+| Spec 檔案不存在 | 列出可用 spec，或引導到 `/sdd create` |
+| AC 數量為 0 | 告知 spec 無 AC，引導修改 spec |
+| 1:1 對應驗證失敗 | 列出不對應項目，停止並報告 |
+
 ## References | 參考
 
 *   [Forward Derivation Standard](../forward-derivation/SKILL.md)