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

package/bundled/skills/commands/sdd.md

@@ -10,6 +10,226 @@ Create, review, approve, implement, and verify specification documents — full
 
 建立、審查、核准、實作和驗證規格文件 — 完整 SDD 生命週期管理。
 
+## Pre-Flight Checks | 前置檢查
+
+Before executing ANY SDD phase, the AI assistant MUST run the applicable checks below. If a check fails, STOP and guide the user to the correct phase.
+
+在執行任何 SDD 階段前，AI 助手必須執行以下適用的檢查。如果檢查失敗，停止並引導使用者到正確的階段。
+
+### Phase Gate Matrix | 階段閘門矩陣
+
+| Target Phase | Pre-Flight Check | On Failure |
+|-------------|-----------------|------------|
+| `discuss` | None (entry point) | — |
+| `create` | `ls docs/specs/` → check for existing orphan specs | Warn, offer to close orphans first |
+| `review` | Spec file exists AND status = `Draft` | → Guide to `/sdd create` |
+| `approve` | Spec file exists AND status = `Review` | → Guide to `/sdd review` |
+| `implement` | 1. `ls docs/specs/SPEC-*.md` → at least one spec exists | → Guide to `/sdd create` |
+| | 2. Spec status = `Approved` (check `status:` field in spec) | → Guide to `/sdd approve` |
+| | 3. Check `.workflow-state/` for active SDD state | Resume if exists |
+| `verify` | 1. Spec status = `Implemented` or has implementation commits | → Guide to `/sdd implement` |
+| | 2. All AC have code + test references | → List incomplete ACs |
+
+### Check Commands | 檢查指令
+
+```bash
+# Check for existing specs
+ls docs/specs/SPEC-*.md 2>/dev/null
+
+# Check spec status (grep the status field)
+grep -m1 "^status:" docs/specs/SPEC-XXX.md
+
+# Check for active workflow state
+ls .workflow-state/sdd-*.yaml 2>/dev/null
+
+# Check AC implementation status
+grep -E "^- \[(x|X)\]" docs/specs/SPEC-XXX.md
+```
+
+### Enforcement Behavior | 執行行為
+
+- **Mode: `enforce`** (default) — Block phase transition, show guidance
+- **Mode: `suggest`** — Show warning but allow override
+- **Mode: `off`** — No checks
+
+Check project config: `.uds/config.yaml` → `workflow.enforcement_mode`
+
+---
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action | AI 行為 |
+|-------|-----------|--------|
+| `/sdd` | 1. 檢查 `docs/specs/` 是否有進行中的 spec 2. **有進行中的 spec** → 顯示狀態摘要，問使用者要繼續哪個還是新建 3. **無進行中的 spec** → 問使用者想做什麼功能，進入 discuss | Check for in-progress specs; show status or start discuss |
+| `/sdd <feature-name>` | 進入 **discuss** 階段（以 feature-name 為主題） | Enter discuss phase for feature |
+| `/sdd <phase>` | 進入指定 phase，執行 Pre-Flight Check。無指定 spec 時，列出該 phase 可操作的 spec 清單 | Enter specified phase, list eligible specs |
+| `/sdd <phase> <spec-file>` | 進入指定 phase，對指定 spec 執行 Pre-Flight Check 後開始 | Enter phase for specific spec |
+| `/sdd --evaluate` | 僅執行 Scope Evaluation（Phase 0），輸出範圍評估結果 | Run scope evaluation only |
+| `/sdd --sync-check` | 僅執行同步檢查，輸出同步狀態 | Run sync check only |
+
+### Interaction Script | 互動腳本
+
+#### Phase 0.5: Discuss
+
+1. 讀取相關程式碼和文件，建立對現狀的理解
+2. 列出識別到的灰色地帶（ambiguities），以編號問題呈現
+3. 逐一與使用者討論，收斂答案
+4. 鎖定範圍（In Scope / Out of Scope / Deferred）
+
+**Decision: 灰色地帶解決程度**
+- IF 所有問題都有明確答案 → 輸出 scope summary，建議進入 create
+- IF 仍有未解問題 → 列出剩餘問題，問使用者是否接受風險繼續
+- IF 使用者說「先這樣」 → 記錄未解問題為 `[OPEN]`，允許進入 create
+
+**Output format | 產出格式：**
+```markdown
+### Discuss Summary
+**Feature**: [name]
+**In Scope**: [list]
+**Out of Scope**: [list]
+**Deferred**: [list]
+**Open Questions**: [list or "None"]
+**read_first**: [file list]
+```
+
+🛑 **STOP**: 顯示 Discuss Summary 後等待使用者確認進入 create
+
+#### Phase 1: Create
+
+1. 基於 discuss 結論和 read_first 檔案，撰寫完整 spec
+2. 使用 Spec Document Structure 模板
+3. 所有 AC 使用 Given/When/Then 格式
+4. 為 spec 指定 ID（查看 `docs/specs/` 目錄決定下一個編號）
+5. 撰寫 Test Plan
+
+**Decision: Spec 放置位置**
+- IF 是 CLI 相關 → `docs/specs/cli/`
+- IF 是 Core Standard 相關 → `docs/specs/standards/`
+- IF 是 Skill 相關 → `docs/specs/skills/`
+- IF 是架構相關 → `docs/specs/architecture/`
+- IF 是跨元件 → `docs/specs/system/`
+- ELSE → `docs/specs/`
+
+🛑 **STOP**: 撰寫完 spec 後展示內容，等待使用者確認再寫入檔案
+
+#### Phase 2: Review
+
+1. 讀取指定 spec 檔案
+2. 逐項檢查以下維度：
+
+| 檢查維度 | 檢查內容 |
+|----------|---------|
+| Requirements 完整性 | 所有 REQ 都有 Scenario |
+| AC 可測試性 | 每個 AC 都是 Given/When/Then 格式 |
+| AC 覆蓋率 | 每個 REQ 至少有一個 AC 對應 |
+| Technical Design 可行性 | 設計不依賴不存在的 API/工具 |
+| Test Plan 對應 | Test Plan 涵蓋所有 AC |
+| 範圍一致性 | 沒有超出 discuss 鎖定的範圍 |
+| 無歧義 | 沒有模糊用語（「等等」「適當地」） |
+
+3. 輸出 Review 結果表格
+4. 更新 spec status 為 `Review`
+
+**Decision: Review 結果**
+- IF 全部通過 → 建議進入 approve
+- IF 有 blocking issue → 列出問題，建議修改後重新 review
+- IF 只有 suggestion → 列出建議，使用者可選擇修改或直接 approve
+
+🛑 **STOP**: 顯示 review 結果後等待使用者決定
+
+#### Phase 3: Approve
+
+1. 讀取 spec，確認 status = `Review`
+2. 逐項展示 Approval Checklist（5 項），標記通過/未通過
+3. 等待使用者確認核准
+
+**Decision: Approval 結果**
+- IF 使用者確認核准 → 更新 spec metadata（status, approved-date, approved-by）
+- IF 使用者拒絕 → 記錄原因，建議回到 review 或 create
+
+🛑 **STOP**: 展示 checklist 結果後等待使用者明確說「核准」或「approved」
+
+#### Phase 4: Implement
+
+1. 讀取 approved spec，列出所有 AC
+2. 產出實作計畫：每個 AC 要改哪些檔案、預估複雜度
+3. 等待使用者確認計畫
+
+🛑 **STOP**: 顯示實作計畫後等待使用者確認
+
+4. 逐 AC 實作：
+   a. 撰寫程式碼
+   b. 撰寫對應測試
+   c. 執行測試確認通過
+   d. 更新 spec 中的 AC checkbox
+
+**Decision: Commit 節奏**
+- IF AC 之間相互獨立 → 每完成一個 AC 就提示可以 commit
+- IF AC 之間緊耦合 → 合併完成後一起提示 commit
+- 不自動執行 git commit — 僅提示使用者
+
+**Decision: 測試失敗**
+- IF 測試失敗 → 修復後重新測試，最多重試 3 次
+- IF 3 次仍失敗 → 🛑 STOP，報告問題，等待使用者指導
+
+🛑 **STOP**: 每個獨立 AC 完成後暫停，展示進度，等待使用者確認繼續
+
+#### Phase 5: Verify
+
+1. 讀取 spec，列出所有 AC
+2. 對每個 AC 收集證據：
+   - 程式碼位置（file:line）
+   - 測試位置（file:line）
+   - 測試結果（執行測試）
+3. 檢查是否有偏差（Added / Modified / Omitted）
+4. 產生 Verification Report
+
+**Decision: 驗證結果**
+- IF 全部 PASS → 更新 spec status 為 `Implemented`，建議歸檔
+- IF 有 FAIL → 列出失敗項目，建議回到 implement 修復
+- IF 迭代次數 ≥ 3 → 🛑 STOP，強制升級（review spec / rethink / escalate）
+
+🛑 **STOP**: 顯示 Verification Report 後等待使用者決定下一步
+
+#### Phase 6: Archive
+
+1. 確認 spec status = `Implemented` 且 verify 通過
+2. 連結相關 commit/PR
+3. 更新 spec status 為 `Archived`
+
+🛑 **STOP**: 確認歸檔前等待使用者確認
+
+### Stop Points Summary | 停止點總覽
+
+| Phase | Stop Point | 等待內容 |
+|-------|-----------|---------|
+| discuss | Discuss Summary 輸出後 | 確認進入 create |
+| create | Spec 撰寫完成後 | 確認寫入檔案 |
+| review | Review 結果輸出後 | 決定修改或進入 approve |
+| approve | Checklist 展示後 | 明確核准 |
+| implement | 實作計畫展示後 | 確認開始實作 |
+| implement | 每個獨立 AC 完成後 | 確認繼續下一個 |
+| verify | Verification Report 輸出後 | 決定歸檔或修復 |
+| archive | 歸檔前 | 確認歸檔 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action | AI 行為 |
+|-----------------|-----------|--------|
+| Pre-Flight Check 失敗 | 說明哪個條件未滿足，引導到正確的 phase | State failure, guide to correct phase |
+| Spec 檔案不存在 | 列出可用的 spec 檔案，或建議 `/sdd create` | List available specs or suggest create |
+| Spec status 不符合目標 phase | 顯示當前 status，說明需要先完成哪個 phase | Show current status, explain required phase |
+| `docs/specs/` 目錄不存在 | 自動建立目錄，繼續流程 | Create directory automatically |
+| 使用者提供的 feature name 與現有 spec 重複 | 顯示現有 spec，問使用者是要繼續還是新建 | Show existing spec, ask continue or create new |
+| 實作中測試反覆失敗（>3 次） | 停止自動修復，報告問題，等待使用者指導 | Stop auto-fix, report issue, wait for guidance |
+| 非預期狀態（無法判斷正確行為） | 停止並詢問使用者，不猜測 | Stop and ask, never guess |
+
+---
+
 ## SDD Workflow | SDD 工作流程
 
 ```

package/bundled/skills/commands/security.md

@@ -0,0 +1,67 @@
+---
+description: "[UDS] Guide security review and vulnerability assessment following OWASP standards"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[module or file to audit | 要審計的模組或檔案]"
+---
+
+# Security Assistant | 安全助手
+
+Guide security review and vulnerability assessment following OWASP standards.
+
+引導安全審查和漏洞評估，遵循 OWASP 標準。
+
+## Workflow | 工作流程
+
+```
+SCOPE ──► SCAN ──► ANALYZE ──► REPORT
+```
+
+## Usage | 使用方式
+
+- `/security` - Start interactive security review
+- `/security src/auth` - Review specific module
+- `/security --owasp` - OWASP Top 10 focused review
+
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/security` | 詢問審查範圍，進入 SCOPE |
+| `/security <path>` | 直接審查指定路徑 |
+| `/security --owasp` | 聚焦 OWASP Top 10 審查 |
+
+### Interaction Script | 互動腳本
+
+1. 確認審查範圍
+2. 掃描程式碼，識別潛在漏洞
+3. 依嚴重程度分類（Critical / High / Medium / Low）
+4. 生成安全審查報告
+
+**Decision: 發現嚴重漏洞**
+- IF Critical → 立即標記，建議優先修復
+- IF High → 標記為重要，建議盡快修復
+- ELSE → 列入報告，建議排程修復
+
+🛑 **STOP**: 報告展示後等待使用者決定
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 安全報告展示後 | 使用者決定修復優先順序 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 目標路徑不存在 | 列出可用路徑 |
+| 程式碼過大無法全面掃描 | 建議聚焦高風險區域（auth、input handling、API） |
+
+## Reference | 參考
+
+- Full standard: [security-assistant](../security-assistant/SKILL.md)
+- Core guide: [security-standards](../../core/security-standards.md)

package/bundled/skills/commands/tdd.md

@@ -17,6 +17,39 @@ Guide through the Test-Driven Development (TDD) workflow: Red-Green-Refactor.
 
 引導測試驅動開發（TDD）流程：紅-綠-重構。
 
+## Pre-Flight Checks | 前置檢查
+
+Before executing TDD phases, the AI assistant MUST verify prerequisites. If a check fails, STOP and guide the user.
+
+在執行 TDD 階段前，AI 助手必須驗證前置條件。如果檢查失敗，停止並引導使用者。
+
+### Phase Gate Matrix | 階段閘門矩陣
+
+| Target Phase | Pre-Flight Check | On Failure |
+|-------------|-----------------|------------|
+| `RED` | 1. Feature/function clearly defined | → Ask user to describe the behavior |
+| | 2. If SDD project: spec exists and is Approved | → Guide to `/sdd` |
+| `GREEN` | 1. At least one failing test exists | → Guide back to RED phase |
+| | 2. Run tests → confirm failure (not error) | → Fix test syntax/setup first |
+| `REFACTOR` | 1. All tests passing (GREEN confirmed) | → Stay in GREEN phase |
+| | 2. No failing tests from previous RED cycle | → Complete GREEN first |
+
+### Red-Before-Green Enforcement | 紅燈優先強制
+
+```
+🔴 RED: Write test → run → MUST fail
+   ↓ (only proceed if test fails with expected assertion failure)
+🟢 GREEN: Write minimal code → run → MUST pass
+   ↓ (only proceed if ALL tests pass)
+🔵 REFACTOR: Clean up → run → MUST still pass
+```
+
+**Critical Rule**: The AI MUST NOT write implementation code before a failing test exists. If the user asks to "just write the code", remind them of the TDD contract and offer to write the test first.
+
+**關鍵規則**：AI 不得在失敗測試存在之前撰寫實作程式碼。如果使用者要求「直接寫程式碼」，提醒 TDD 契約並建議先寫測試。
+
+---
+
 ## Methodology Integration | 方法論整合
 
 When `/tdd` is invoked:
@@ -80,6 +113,74 @@ See [methodology-system](../methodology-system/SKILL.md) for full methodology tr
 - `/tdd calculateTotal` - TDD for specific function
 - `/tdd "user can login"` - TDD for user story
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/tdd` | 詢問要實作的功能，進入 🔴 RED 階段 |
+| `/tdd <function>` | 以指定函式為目標，直接進入 🔴 RED |
+| `/tdd "user story"` | 以使用者故事為目標，進入 🔴 RED |
+
+### Interaction Script | 互動腳本
+
+#### 🔴 RED Phase
+
+1. 確認目標功能/行為
+2. 撰寫一個會失敗的測試
+3. 執行測試，確認失敗（assertion failure，非 syntax error）
+
+**Decision: 測試結果**
+- IF 測試失敗（assertion） → 進入 🟢 GREEN
+- IF 測試出錯（syntax/runtime error） → 修正測試本身，重新執行
+- IF 測試通過 → 告知使用者測試不應該通過，檢查是否功能已存在
+
+🛑 **STOP**: 展示失敗測試後等待使用者確認進入 GREEN
+
+#### 🟢 GREEN Phase
+
+1. 撰寫最小量程式碼使測試通過
+2. 執行測試
+
+**Decision: 測試結果**
+- IF 所有測試通過 → 建議進入 🔵 REFACTOR
+- IF 仍有失敗 → 繼續修改程式碼（最多 3 次），超過則 🛑 STOP
+
+🛑 **STOP**: 測試通過後等待使用者確認進入 REFACTOR
+
+#### 🔵 REFACTOR Phase
+
+1. 分析剛寫的程式碼是否有改善空間
+2. 提出重構建議
+
+**Decision: 重構範圍**
+- IF 有明顯重複或改善點 → 列出建議，等使用者選擇
+- IF 程式碼已足夠簡潔 → 告知不需重構，建議進入下一個 RED 循環
+
+3. 執行重構，確認所有測試仍通過
+
+🛑 **STOP**: 重構完成後等待使用者決定繼續下一個 RED 循環或結束
+
+### Stop Points | 停止點
+
+| Phase | Stop Point | 等待內容 |
+|-------|-----------|---------|
+| RED | 失敗測試撰寫後 | 確認進入 GREEN |
+| GREEN | 測試通過後 | 確認進入 REFACTOR |
+| REFACTOR | 重構完成後 | 決定繼續或結束 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 使用者要求跳過 RED 直接寫程式碼 | 提醒 TDD 契約，建議先寫測試 |
+| 測試框架未偵測到 | 詢問使用者指定框架 |
+| 測試語法錯誤導致無法執行 | 修正語法後重新執行，不計入嘗試次數 |
+| GREEN 階段 3 次仍無法通過 | 停止，分析失敗原因，等待使用者指導 |
+
 ## Reference | 參考
 
 - Full standard: [tdd-assistant](../tdd-assistant/SKILL.md)

package/bundled/skills/commands/update.md

@@ -344,6 +344,67 @@ Skills are managed separately:
 **"Skills previously declined"**
 - Run `/config skills` to reinstall declined Skills
 
+## AI Agent Behavior | AI 代理行為
+
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action | AI 行為 |
+|-------|-----------|--------|
+| `/update` | 檢查狀態 → 詢問更新偏好 → 執行 → 檢查 Skills/Commands | Check, ask, execute, post-check |
+| `/update --yes` | 跳過確認直接更新（不自動安裝 Skills） | Update without confirmation |
+| `/update --beta` | 檢查 beta 版本更新 | Check beta updates |
+| `/update --skills` | 僅更新 Skills | Update Skills only |
+| `/update --commands` | 僅更新 Commands | Update Commands only |
+| `/update --offline` | 跳過 npm registry 檢查 | Skip network check |
+
+### Interaction Script | 互動腳本
+
+1. 執行 `uds check --summary` 顯示目前狀態
+
+**Decision: 有無可用更新**
+- IF 已是最新 → 顯示「Already up to date」，跳至 Step 4 檢查 Skills/Commands
+- IF 有更新 → 進入 Step 2
+
+2. 詢問更新偏好（AskUserQuestion）
+
+**Decision: 版本類型**
+- IF stable 可用 → 選項：Update Now（建議）/ Check Beta / Skip
+- IF 僅 pre-release → 顯示具體類型：Update to Alpha/Beta/RC / Skip
+
+🛑 **STOP**: 展示版本資訊後等待使用者選擇
+
+3. 執行更新 `uds update --yes` 或 `uds update --beta --yes`
+
+4. 檢查 Skills/Commands 狀態（Smart Grouping 策略）
+   - 偵測缺少的 Skills → 使用 Smart Grouping 詢問安裝
+   - 偵測缺少的 Commands → 使用 Smart Grouping 詢問安裝
+   - 已拒絕的工具不再顯示
+
+**IMPORTANT**: AskUserQuestion 最多 4 個選項。3+ 工具時必須使用兩階段策略。
+
+🛑 **STOP**: 每個 Skills/Commands 安裝決策點等待使用者選擇
+
+5. 說明結果（更新內容、安裝結果、下一步）
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 更新偏好選擇 | 使用者選擇更新版本或跳過 |
+| Skills 安裝詢問 | 使用者選擇安裝位置或跳過 |
+| Commands 安裝詢問 | 使用者選擇安裝位置或跳過 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 標準未初始化 | 提示執行 `/init` |
+| npm registry 無法連線 | 建議加 `--offline`，或稍後重試 |
+| 更新失敗（寫入錯誤） | 顯示錯誤，建議檢查檔案權限 |
+| Skills 之前被拒絕 | 不再詢問，提示可透過 `/config skills` 重新安裝 |
+
 ## Reference | 參考
 
 - CLI documentation: `uds update --help`

package/bundled/skills/commit-standards/SKILL.md

@@ -114,12 +114,18 @@ When `commit_language` is `traditional-chinese`, use Chinese types and body:
 After `/commit` completes, the AI assistant should suggest:
 
 > **提交完成。建議下一步 / Commit complete. Suggested next steps:**
-> - 執行 `/changelog` 更新變更日誌 — Update the changelog
 > - 執行 `git push` 推送到遠端 — Push to remote
-> - 執行 `/release`（若準備發布）— Start release process (if ready)
+> - 準備發布時 → 執行 `/changelog` + `/release` — When preparing a release → Run `/changelog` + `/release`
 > - 發現重複模式或規範摩擦 → 執行 `/audit --report` 回報 — Patterns or friction detected → Run `/audit --report` to submit feedback
 
 ## Reference | 參考
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [commit-message-guide.md](../../core/commit-message-guide.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/commit`](../commands/commit.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/commit`](../commands/commit.md#ai-agent-behavior--ai-代理行為)

package/bundled/skills/database-assistant/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: database
+scope: universal
+description: |
+  Guide database design, migration, and query optimization.
+  Use when: schema design, migration planning, query optimization, index strategy.
+  Keywords: database, schema, migration, SQL, index, query, 資料庫, 遷移, 查詢.
+allowed-tools: Read, Grep, Glob
+argument-hint: "[schema or migration to review | 要審查的 schema 或遷移]"
+---
+
+# Database Assistant | 資料庫助手
+
+Guide database design, migration planning, and query optimization.
+
+引導資料庫設計、遷移規劃和查詢最佳化。
+
+## Core Principles | 核心原則
+
+| Principle | Description | 說明 |
+|-----------|-------------|------|
+| Normalization | Eliminate redundancy (3NF minimum) | 消除冗餘（至少 3NF） |
+| Referential Integrity | Enforce FK constraints | 強制外鍵約束 |
+| Index Strategy | Index query patterns, not all columns | 依查詢模式建立索引 |
+| Migration Safety | Always reversible, zero-downtime | 可逆、零停機 |
+| Data Protection | Encrypt sensitive fields, audit access | 加密敏感欄位、稽核存取 |
+
+## Schema Design Checklist | Schema 設計檢查清單
+
+- [ ] Primary keys defined (prefer UUID or BIGINT) | 主鍵已定義
+- [ ] Foreign keys with proper ON DELETE/UPDATE | 外鍵含適當的級聯策略
+- [ ] NOT NULL constraints on required fields | 必填欄位加 NOT NULL
+- [ ] Indexes on frequently queried columns | 常查詢欄位建立索引
+- [ ] Created/Updated timestamps on all tables | 所有表加建立/更新時間戳
+- [ ] Sensitive data encrypted at rest | 敏感資料靜態加密
+- [ ] Naming conventions consistent (snake_case) | 命名慣例一致（snake_case）
+
+## Normalization Quick Reference | 正規化快速參考
+
+| Normal Form | Rule | 規則 |
+|-------------|------|------|
+| **1NF** | Atomic values, no repeating groups | 原子值、無重複群組 |
+| **2NF** | 1NF + no partial dependencies | 1NF + 無部分相依 |
+| **3NF** | 2NF + no transitive dependencies | 2NF + 無遞移相依 |
+| **Denormalize** | Only for proven read performance needs | 僅針對已證實的讀取效能需求 |
+
+## Migration Workflow | 遷移工作流程
+
+```
+PLAN ──► WRITE ──► TEST ──► DEPLOY ──► VERIFY
+```
+
+### 1. Plan — Assess Impact | 評估影響
+Identify affected tables, estimate data volume, plan rollback strategy.
+
+識別受影響的表、估算資料量、規劃回滾策略。
+
+### 2. Write — Create Migration | 撰寫遷移
+Write forward and rollback scripts. Use incremental, numbered migrations.
+
+撰寫正向和回滾腳本。使用遞增編號的遷移。
+
+### 3. Test — Validate Migration | 驗證遷移
+Run on staging with production-like data. Verify data integrity post-migration.
+
+在 staging 環境使用類生產資料執行。驗證遷移後資料完整性。
+
+### 4. Deploy — Execute Migration | 執行遷移
+Apply during maintenance window or use online schema change tools.
+
+在維護窗口執行，或使用線上 Schema 變更工具。
+
+### 5. Verify — Confirm Success | 確認成功
+Check row counts, constraint validity, application functionality.
+
+檢查列數、約束有效性、應用程式功能。
+
+## Index Strategy | 索引策略
+
+| Type | Use Case | 使用場景 |
+|------|----------|----------|
+| B-tree | Equality, range queries (default) | 等值、範圍查詢（預設） |
+| Hash | Exact match only | 僅精確匹配 |
+| GIN | Full-text search, JSONB | 全文搜尋、JSONB |
+| Partial | Filtered subsets | 過濾子集 |
+| Composite | Multi-column queries | 多欄位查詢 |
+
+## Usage | 使用方式
+
+```
+/database                - Interactive database design guide | 互動式資料庫設計引導
+/database schema         - Review schema design | 審查 Schema 設計
+/database --migration    - Migration planning assistant | 遷移規劃助手
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/database` completes, the AI assistant should suggest:
+
+> **資料庫設計完成。建議下一步 / Database design complete. Suggested next steps:**
+> - 執行 `/security` 檢查資料保護措施 — Check data protection measures
+> - 執行 `/testing` 規劃資料庫測試策略 — Plan database testing strategy
+> - 執行 `/checkin` 確認遷移符合提交規範 — Verify migrations meet check-in standards
+> - 產生 API 端點 → 執行 `/api-design` — Generate API endpoints → Run `/api-design`
+
+## Reference | 參考
+
+- Core standard: [database-standards.md](../../core/database-standards.md)
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更說明 |
+|---------|------|---------|----------|
+| 1.0.0 | 2026-03-23 | Initial release | 初始版本 |
+
+## License | 授權
+
+CC BY 4.0 — Documentation content