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

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

@@ -0,0 +1,119 @@
+---
+name: migrate
+scope: universal
+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 systematic code migration, framework upgrades, and technology modernization.
+
+引導系統性程式碼遷移、框架升級與技術現代化。
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/migrate` | Start interactive migration guide | 啟動互動式遷移引導 |
+| `/migrate --assess` | Risk assessment only | 僅風險評估 |
+| `/migrate "Vue 2 to 3"` | Guide specific migration | 引導特定遷移 |
+| `/migrate --deps` | Dependency upgrade analysis | 依賴升級分析 |
+| `/migrate --rollback` | Plan rollback strategy | 規劃回滾策略 |
+
+## Migration Types | 遷移類型
+
+| Type | Examples | Risk | 風險 |
+|------|----------|------|------|
+| **Framework Upgrade** | React 17→18, Vue 2→3, Angular 15→17 | Medium-High | 中高 |
+| **Language Migration** | JS→TS, Python 2→3, Java 8→17 | High | 高 |
+| **API Version** | REST v1→v2, GraphQL schema update | Medium | 中 |
+| **Database Migration** | MySQL→PostgreSQL, SQL→NoSQL | Very High | 極高 |
+| **Build Tool** | Webpack→Vite, Grunt→ESBuild | Low-Medium | 低中 |
+| **Package Manager** | npm→pnpm, pip→poetry | Low | 低 |
+
+## Risk Assessment Matrix | 風險評估矩陣
+
+| | Low Impact | Medium Impact | High Impact |
+|---|-----------|---------------|-------------|
+| **Low Complexity** | Safe (proceed) | Caution | Plan carefully |
+| **Medium Complexity** | Caution | Plan + test | Staged rollout |
+| **High Complexity** | Plan + test | Staged rollout | Full SDD spec |
+
+| | 低影響 | 中影響 | 高影響 |
+|---|--------|--------|--------|
+| **低複雜度** | 安全（直接進行） | 謹慎 | 仔細規劃 |
+| **中複雜度** | 謹慎 | 規劃 + 測試 | 分階段發布 |
+| **高複雜度** | 規劃 + 測試 | 分階段發布 | 完整 SDD 規格 |
+
+## Workflow | 工作流程
+
+1. **ASSESS** - Evaluate current state, identify breaking changes
+2. **PLAN** - Create migration checklist with dependencies
+3. **PREPARE** - Set up codemods, compatibility layers, feature flags
+4. **MIGRATE** - Execute migration in phases with tests
+5. **VERIFY** - Run full test suite, check for regressions
+6. **CLEANUP** - Remove compatibility shims, old dependencies
+
+---
+
+1. **評估** - 評估現狀、識別破壞性變更
+2. **規劃** - 建立含依賴關係的遷移清單
+3. **準備** - 設定 codemods、相容層、功能旗標
+4. **遷移** - 分階段執行遷移並測試
+5. **驗證** - 執行完整測試套件、檢查回歸
+6. **清理** - 移除相容層、舊依賴
+
+## Rollback Strategy | 回滾策略
+
+| Approach | When to Use | 使用時機 |
+|----------|-------------|---------|
+| **Git revert** | Small, atomic changes | 小型、原子性變更 |
+| **Feature flag** | Gradual rollout needed | 需要逐步發布 |
+| **Dual-run** | Critical systems, zero downtime | 關鍵系統、零停機 |
+| **Branch freeze** | Full migration in one go | 一次性完整遷移 |
+
+## Usage Examples | 使用範例
+
+```
+User: /migrate "Vue 2 to 3"
+AI: Migration Assessment: Vue 2 → Vue 3
+    Breaking changes found: 12
+    - Options API → Composition API (47 components)
+    - Filters removed (8 usages)
+    - Event bus removed (3 usages)
+    Risk: Medium-High
+    Estimated effort: 2-3 weeks
+    Recommended: Staged migration with @vue/compat
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/migrate` completes, the AI assistant should suggest:
+
+> **遷移分析完成。建議下一步 / Migration analysis complete. Suggested next steps:**
+> - 執行 `/reverse` 深入理解現有程式碼 — Understand current codebase
+> - 執行 `/testing` 確保遷移後測試通過 — Verify post-migration tests
+> - 執行 `/commit` 提交遷移變更 — Commit migration changes
+
+## Reference | 參考
+
+- Core standard: [refactoring-standards.md](../../core/refactoring-standards.md)
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更 |
+|---------|------|---------|------|
+| 1.0.0 | 2026-03-24 | Initial release | 初始版本 |
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/migrate`](../commands/migrate.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/migrate`](../commands/migrate.md#ai-agent-behavior--ai-代理行為)
+
+## License | 授權
+
+CC BY 4.0

package/bundled/skills/pr-automation-assistant/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: pr
+scope: universal
+description: |
+  Guide pull request creation, review automation, and merge strategies.
+  Use when: creating PRs, automating reviews, configuring merge policies.
+  Keywords: pull request, PR, merge, review, GitHub, GitLab, 合併請求, 審查.
+allowed-tools: Read, Grep, Glob, Bash(git:*, gh:*)
+argument-hint: "[branch name or PR number | 分支名稱或 PR 編號]"
+---
+
+# PR Automation Assistant | PR 自動化助手
+
+Streamline the pull request lifecycle from creation to merge.
+
+簡化從建立到合併的 Pull Request 生命週期。
+
+## PR Creation Checklist | PR 建立檢查清單
+
+| Item | Rule | 規則 |
+|------|------|------|
+| Title | `<type>(<scope>): <summary>` under 70 chars | 70 字元內，遵循 conventional commits |
+| Description | Use structured template below | 使用下方結構化模板 |
+| Labels | At least one category label | 至少一個分類標籤 |
+| Reviewers | Assign based on CODEOWNERS or domain | 依 CODEOWNERS 或領域指派 |
+| Branch | Up to date with base branch | 與基礎分支同步 |
+
+## PR Description Template | PR 描述模板
+
+```markdown
+## Summary | 摘要
+<1-3 bullet points describing the change>
+
+## Changes | 變更內容
+- Added / Modified / Removed ...
+
+## Test Plan | 測試計畫
+- [ ] Unit tests pass
+- [ ] Manual verification steps
+
+## Screenshots | 截圖
+(if UI changes)
+```
+
+## Merge Strategy Decision | 合併策略決策
+
+| Strategy | When to Use | 使用時機 |
+|----------|-------------|----------|
+| **Squash merge** | Feature branches with messy commits | 功能分支，提交記錄零散 |
+| **Merge commit** | Release branches, preserve history | 發布分支，保留完整歷史 |
+| **Rebase** | Linear history, small changes | 線性歷史，小幅變更 |
+
+## Auto-Review Triggers | 自動審查觸發條件
+
+| Trigger | Threshold | Action | 動作 |
+|---------|-----------|--------|------|
+| PR size | > 400 lines changed | Request split | 要求拆分 |
+| No tests | 0 test files changed | Block merge | 阻止合併 |
+| CI failure | Any check fails | Block merge | 阻止合併 |
+| Stale PR | > 7 days no activity | Notify author | 通知作者 |
+| Draft PR | Marked as draft | Skip reviewers | 跳過審查者指派 |
+
+## Workflow | 工作流程
+
+```
+CREATE ──► REVIEW ──► APPROVE ──► MERGE ──► CLEANUP
+```
+
+1. **Create** — Branch, commit, push, open PR with template
+2. **Review** — Automated checks + human review
+3. **Approve** — All checks green, required approvals met
+4. **Merge** — Apply chosen merge strategy
+5. **Cleanup** — Delete source branch, update linked issues
+
+## Usage | 使用方式
+
+```
+/pr                  - Guide PR creation for current branch | 引導建立當前分支的 PR
+/pr create           - Create PR with template | 使用模板建立 PR
+/pr --template       - Show PR description template | 顯示 PR 描述模板
+/pr review 123       - Review specific PR | 審查特定 PR
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/pr` completes, the AI assistant should suggest:
+
+> **PR 操作完成。建議下一步 / PR operation complete. Suggested next steps:**
+> - 執行 `/review` 進行詳細程式碼審查 — Run detailed code review
+> - 執行 `/commit` 修正審查發現的問題 — Fix issues found in review
+> - 執行 `/changelog` 更新變更日誌 — Update changelog
+> - 檢查 CI 狀態 → `gh pr checks` — Check CI status
+
+## Reference | 參考
+
+- Core standard: [code-review-checklist.md](../../core/code-review-checklist.md)
+- Core standard: [git-workflow.md](../../core/git-workflow.md)
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更說明 |
+|---------|------|---------|----------|
+| 1.0.0 | 2026-03-23 | Initial release | 初始版本 |
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/pr`](../commands/pr.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/pr`](../commands/pr.md#ai-agent-behavior--ai-代理行為)
+
+## License | 授權
+
+CC BY 4.0 — Documentation content

package/bundled/skills/project-discovery/SKILL.md

@@ -71,3 +71,10 @@ After `/discover` completes, the AI assistant should suggest based on the assess
 ## Reference | 參考
 
 - Detailed guide: [guide.md](./guide.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/discover`](../commands/discover.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/discover`](../commands/discover.md#ai-agent-behavior--ai-代理行為)

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

@@ -85,3 +85,10 @@ After `/refactor` completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [refactoring-standards.md](../../core/refactoring-standards.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/refactor`](../commands/refactor.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/refactor`](../commands/refactor.md#ai-agent-behavior--ai-代理行為)

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

@@ -69,3 +69,10 @@ After `/release` completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [versioning.md](../../core/versioning.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/release`](../commands/release.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/release`](../commands/release.md#ai-agent-behavior--ai-代理行為)

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

@@ -73,3 +73,10 @@ After `/requirement` completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [requirement-engineering.md](../../core/requirement-engineering.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/requirement`](../commands/requirement.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/requirement`](../commands/requirement.md#ai-agent-behavior--ai-代理行為)

package/bundled/skills/reverse-engineer/SKILL.md

@@ -122,3 +122,10 @@ After `/reverse` (full or `spec`) completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [reverse-engineering-standards.md](../../core/reverse-engineering-standards.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/reverse`](../commands/reverse.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/reverse`](../commands/reverse.md#ai-agent-behavior--ai-代理行為)

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

@@ -0,0 +1,105 @@
+---
+name: security
+scope: universal
+description: |
+  Guide security review and vulnerability assessment following OWASP standards.
+  Use when: security audit, vulnerability check, secure coding review, threat modeling.
+  Keywords: security, OWASP, vulnerability, authentication, authorization, 安全, 漏洞, 認證.
+allowed-tools: Read, Grep, Glob
+argument-hint: "[module or file to audit | 要審計的模組或檔案]"
+---
+
+# Security Assistant | 安全審計助手
+
+Guide systematic security reviews following OWASP Top 10 and industry best practices.
+
+引導系統化的安全審查，遵循 OWASP Top 10 和業界最佳實踐。
+
+## Quick Checklist — OWASP Top 10 Prevention | 快速檢查清單
+
+| ID | Risk | Prevention | 預防措施 |
+|----|------|------------|----------|
+| A01 | Broken Access Control | Enforce least privilege, deny by default | 最小權限原則，預設拒絕 |
+| A02 | Cryptographic Failures | Use strong algorithms, protect keys | 使用強加密演算法，保護金鑰 |
+| A03 | Injection | Parameterized queries, input validation | 參數化查詢、輸入驗證 |
+| A04 | Insecure Design | Threat modeling, secure design patterns | 威脅建模、安全設計模式 |
+| A05 | Security Misconfiguration | Hardened defaults, minimal permissions | 強化預設值、最小權限 |
+| A06 | Vulnerable Components | Track dependencies, patch regularly | 追蹤相依套件、定期修補 |
+| A07 | Auth Failures | MFA, strong password policies | 多因素認證、強密碼策略 |
+| A08 | Data Integrity Failures | Verify signatures, use trusted sources | 驗證簽章、使用可信來源 |
+| A09 | Logging Failures | Log security events, monitor alerts | 記錄安全事件、監控告警 |
+| A10 | SSRF | Validate URLs, restrict outbound traffic | 驗證 URL、限制對外流量 |
+
+## Security Review Workflow | 安全審查工作流程
+
+```
+SCOPE ──► SCAN ──► ANALYZE ──► REPORT
+```
+
+### 1. Scope — Define Audit Boundary | 定義審計範圍
+Identify target modules, data flows, and trust boundaries.
+
+識別目標模組、資料流和信任邊界。
+
+### 2. Scan — Identify Vulnerabilities | 識別漏洞
+Review code for OWASP Top 10 patterns, check dependencies, inspect configurations.
+
+檢查程式碼的 OWASP Top 10 模式、檢查相依套件、檢視配置。
+
+### 3. Analyze — Assess Risk | 評估風險
+Classify findings by severity (Critical/High/Medium/Low) and exploitability.
+
+依嚴重程度（Critical/High/Medium/Low）和可利用性分類。
+
+### 4. Report — Document Findings | 記錄發現
+Produce actionable findings with remediation recommendations.
+
+產出可行動的發現報告，附帶修復建議。
+
+## Severity Classification | 嚴重程度分類
+
+| Level | Criteria | 標準 |
+|-------|----------|------|
+| **Critical** | Remote code execution, data breach | 遠端程式碼執行、資料洩漏 |
+| **High** | Authentication bypass, privilege escalation | 認證繞過、權限提升 |
+| **Medium** | Information disclosure, CSRF | 資訊洩漏、CSRF |
+| **Low** | Missing headers, verbose errors | 缺少 Header、冗長錯誤訊息 |
+
+## Usage | 使用方式
+
+```
+/security                - Full security review of current project | 完整安全審查
+/security src/auth       - Audit specific module | 審計特定模組
+/security --owasp        - OWASP Top 10 focused review | OWASP Top 10 重點審查
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/security` completes, the AI assistant should suggest:
+
+> **安全審查完成。建議下一步 / Security review complete. Suggested next steps:**
+> - 執行 `/checkin` 確認修復符合提交規範 — Verify fixes meet check-in standards
+> - 執行 `/review` 進行程式碼審查 — Run code review on security fixes
+> - 執行 `/commit` 提交安全修復 — Commit security fixes
+> - 檢查相依套件更新 → `npm audit` 或 `pip audit` — Check dependency updates
+
+## Reference | 參考
+
+- Core standard: [security-standards.md](../../core/security-standards.md)
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更說明 |
+|---------|------|---------|----------|
+| 1.0.0 | 2026-03-23 | Initial release | 初始版本 |
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/security`](../commands/security.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/security`](../commands/security.md#ai-agent-behavior--ai-代理行為)
+
+## License | 授權
+
+CC BY 4.0 — Documentation content

package/bundled/skills/security-scan-assistant/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: scan
+scope: universal
+description: |
+  Guide automated security scanning, dependency auditing, and secret detection.
+  Use when: dependency audit, CVE scanning, secret detection, license compliance.
+  Keywords: scan, audit, CVE, dependency, secret, SBOM, vulnerability, 掃描, 漏洞.
+allowed-tools: Read, Grep, Glob, Bash(npm:audit, npx:*)
+argument-hint: "[scan type or target | 掃描類型或目標]"
+---
+
+# Security Scan Assistant | 安全掃描助手
+
+Automate security scanning for dependencies, secrets, and license compliance.
+
+自動化相依套件、機密資訊和授權合規的安全掃描。
+
+## Scan Types | 掃描類型
+
+| Type | Tool Examples | Purpose | 用途 |
+|------|---------------|---------|------|
+| **Dependency audit** | npm audit, pip-audit, Snyk | Find known CVEs in dependencies | 檢測相依套件已知 CVE |
+| **Secret detection** | gitleaks, trufflehog | Find leaked credentials in code | 偵測程式碼中洩漏的憑證 |
+| **License compliance** | license-checker, SPDX | Verify OSS license compatibility | 驗證開源授權相容性 |
+| **SAST** | Semgrep, CodeQL | Static analysis for code patterns | 靜態分析程式碼模式 |
+
+## Tool Integration | 工具整合
+
+| Tool | Command | Scope | 範圍 |
+|------|---------|-------|------|
+| npm audit | `npm audit --json` | Node.js dependencies | Node.js 相依套件 |
+| Snyk | `npx snyk test` | Multi-language deps | 多語言相依套件 |
+| Trivy | `trivy fs .` | Filesystem & containers | 檔案系統與容器 |
+| gitleaks | `gitleaks detect` | Git history secrets | Git 歷史機密 |
+| SPDX | `npx spdx-tool` | License SBOM generation | 授權 SBOM 產出 |
+
+## Severity Classification & SLA | 嚴重程度分類與 SLA
+
+| Severity | SLA | Criteria | 標準 |
+|----------|-----|----------|------|
+| **Critical** | 24 hours | RCE, auth bypass, data exfil | 遠端執行、認證繞過、資料外洩 |
+| **High** | 72 hours | Privilege escalation, SQLi | 權限提升、SQL 注入 |
+| **Medium** | 2 weeks | XSS, CSRF, info disclosure | XSS、CSRF、資訊洩漏 |
+| **Low** | Next sprint | Missing headers, verbose errors | 缺少 Header、冗長錯誤訊息 |
+
+## Workflow | 工作流程
+
+```
+SCAN ──► TRIAGE ──► PRIORITIZE ──► FIX ──► VERIFY
+```
+
+1. **Scan** — Run automated scanners on codebase and dependencies
+2. **Triage** — Filter false positives, confirm real vulnerabilities
+3. **Prioritize** — Rank by severity and exploitability
+4. **Fix** — Apply patches, update dependencies, rotate secrets
+5. **Verify** — Re-scan to confirm remediation
+
+## Usage | 使用方式
+
+```
+/scan                - Full scan (deps + secrets + license) | 完整掃描
+/scan --deps         - Dependency audit only | 僅相依套件審計
+/scan --secrets      - Secret detection only | 僅機密偵測
+/scan --license      - License compliance check | 授權合規檢查
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/scan` completes, the AI assistant should suggest:
+
+> **掃描完成。建議下一步 / Scan complete. Suggested next steps:**
+> - 執行 `/security` 深入安全審查 — Run deep security review
+> - 執行 `/checkin` 確認修復符合提交規範 — Verify fixes meet check-in standards
+> - 執行 `/commit` 提交安全修復 — Commit security fixes
+> - 更新相依套件 → `npm update` 或 `pip install --upgrade` — Update dependencies
+
+## Reference | 參考
+
+- Core standard: [security-standards.md](../../core/security-standards.md)
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更說明 |
+|---------|------|---------|----------|
+| 1.0.0 | 2026-03-23 | Initial release | 初始版本 |
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/scan`](../commands/scan.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/scan`](../commands/scan.md#ai-agent-behavior--ai-代理行為)
+
+## License | 授權
+
+CC BY 4.0 — Documentation content

package/bundled/skills/spec-driven-dev/SKILL.md

@@ -12,12 +12,55 @@ Create, review, and manage specification documents before writing code.
 
 在撰寫程式碼前，建立、審查和管理規格文件。
 
+## When to Use `/sdd` vs `uds spec` | 何時使用
+
+| Scenario | `/sdd` | `uds spec` |
+|----------|--------|------------|
+| Formal feature development with review cycle | ✅ | ❌ |
+| Full spec lifecycle (Draft → Archived) | ✅ | ❌ |
+| Quick prototyping / Vibe coding | ❌ | ✅ |
+| Small incremental changes | ❌ | ✅ |
+| Stakeholder sign-off required | ✅ | ❌ |
+| Micro-spec from natural language intent | ❌ | ✅ |
+
+> **`/sdd`** = Full specification lifecycle for formal development
+> **`uds spec`** = Lightweight micro-specs for rapid iteration
+>
+> **`/sdd`** = 正式開發的完整規格生命週期
+> **`uds spec`** = 快速迭代的輕量微規格
+
+## TL;DR Quick Checklist | 快速檢查清單
+
+- Search existing specs: look in `specs/`, `docs/specs/`, or project spec directory
+- Decide scope: new feature vs modify existing capability
+- Pick a unique spec ID: `SPEC-NNN` or kebab-case change ID
+- Write proposal with clear AC (Given/When/Then format)
+- Get approval before implementation begins
+- Implement tasks sequentially, verify against spec
+- Archive spec after completion
+
+## Decision Tree | 決策樹
+
+```
+New request? | 新需求？
+├─ Bug fix restoring spec behavior? → Fix directly | 直接修復
+├─ Typo/format/comment? → Fix directly | 直接修復
+├─ Dependency update (non-breaking)? → Fix directly | 直接修復
+├─ New feature/capability? → Create proposal | 建立提案
+├─ Breaking change? → Create proposal | 建立提案
+├─ Architecture change? → Create proposal | 建立提案
+└─ Unclear? → Create proposal (safer) | 建立提案（較安全）
+```
+
 ## Workflow | 工作流程
 
 ```
-CREATE ──► REVIEW ──► APPROVE ──► IMPLEMENT ──► VERIFY
+DISCUSS ──► CREATE ──► REVIEW ──► APPROVE ──► IMPLEMENT ──► VERIFY ──► ARCHIVE
 ```
 
+### 0. Discuss - Clarify Scope | 釐清範圍
+Capture gray areas, establish governing principles, resolve ambiguities before writing spec.
+
 ### 1. Create - Write Spec | 撰寫規格
 Define requirements, technical design, acceptance criteria, and test plan.
 
@@ -33,6 +76,9 @@ Develop following the approved spec, referencing requirements and AC.
 ### 5. Verify - Confirm | 驗證
 Ensure implementation matches spec, all tests pass, AC satisfied.
 
+### 6. Archive - Close | 歸檔
+Archive completed spec with links to commits/PRs.
+
 ## Spec States | 規格狀態
 
 | State | Description | 說明 |
@@ -46,13 +92,22 @@ Ensure implementation matches spec, all tests pass, AC satisfied.
 ## Spec Structure | 規格結構
 
 ```markdown
-# Feature: [Name]
+# [SPEC-ID] Feature: [Name]
 
 ## Overview
-Brief description.
+Brief description of the proposed change.
+
+## Motivation
+Why is this change needed? What problem does it solve?
 
 ## Requirements
-- REQ-001: [Description]
+### Requirement: [Name]
+The system SHALL [behavior description].
+
+#### Scenario: [Success case]
+- **GIVEN** [initial context]
+- **WHEN** [action performed]
+- **THEN** [expected result]
 
 ## Acceptance Criteria
 - AC-1: Given [context], when [action], then [result]
@@ -65,6 +120,24 @@ Brief description.
 - [ ] Integration tests for [flow]
 ```
 
+### Scenario Formatting Rules | 場景格式規則
+
+- Use `#### Scenario:` (h4 header) for each scenario
+- Every requirement MUST have at least one scenario
+- Use **GIVEN/WHEN/THEN** format for structured behavior
+- Use **SHALL/MUST** for normative requirements, **SHOULD** for recommendations
+
+## Delta Operations | 變更操作
+
+When modifying existing specs, use delta sections:
+
+| Operation | Description | 說明 |
+|-----------|-------------|------|
+| `## ADDED Requirements` | New capabilities | 新增功能 |
+| `## MODIFIED Requirements` | Changed behavior | 修改行為 |
+| `## REMOVED Requirements` | Deprecated features | 移除功能 |
+| `## RENAMED Requirements` | Name changes | 重新命名 |
+
 ## Usage | 使用方式
 
 ```
@@ -89,3 +162,10 @@ After `/sdd` completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [spec-driven-development.md](../../core/spec-driven-development.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/sdd`](../commands/sdd.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/sdd`](../commands/sdd.md#ai-agent-behavior--ai-代理行為)