universal-dev-standards 5.14.0 → 5.16.0

package/bundled/locales/zh-TW/skills/observability-assistant/guide.md

@@ -0,0 +1,188 @@
+---
+source: ../../../../skills/observability-assistant/guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 760e3ec43846
+status: current
+scope: universal
+description: |
+  引導跨三大支柱的 observability 實作：Logs、Metrics 與 Traces。
+  使用時機：建立監控、選擇 metric 類型、實作 tracing、評估成熟度。
+  關鍵字：observability, metrics, traces, logs, golden signals, OpenTelemetry, 可觀測性, 監控。
+---
+
+# Observability Assistant
+
+> **語言**：[English](../../../../skills/observability-assistant/guide.md) | 繁體中文
+
+**版本**：1.0.0
+**最後更新**：2026-04-01
+**適用範圍**：Claude Code Skills
+
+---
+
+## 用途
+
+本 skill 透過提供三大支柱（Logs、Metrics、Traces）、metric 類型選擇、Golden Signals 監控與成熟度自我評估的指引，協助團隊建構可觀測的系統。
+
+---
+
+## 快速參考（YAML 壓縮版）
+
+```yaml
+# === THREE PILLARS 三大支柱 ===
+three_pillars:
+  logs:
+    captures: "Discrete events with context / 帶上下文的離散事件"
+    use_for: "Debugging, audit trails, error details"
+    granularity: "High (per-event)"
+  metrics:
+    captures: "Numerical measurements over time / 隨時間變化的數值量測"
+    use_for: "Dashboards, alerting, capacity planning"
+    granularity: "Low (aggregated)"
+  traces:
+    captures: "Request flow across services / 跨服務的請求流"
+    use_for: "Latency analysis, dependency mapping"
+    granularity: "Medium (per-request)"
+
+correlation:
+  metric_to_trace: "Use Exemplars to link anomalous metric → specific trace"
+  trace_to_logs: "Use trace_id + span_id embedded in logs"
+  logs_to_metric: "Aggregate log patterns into metrics (e.g., error rate)"
+  key_fields: ["trace_id", "service.name"]
+
+# === METRIC TYPES 指標類型 ===
+metric_types:
+  counter:
+    behavior: "Monotonically increasing (resets on restart) / 只增不減"
+    examples: ["request count", "error count", "bytes sent"]
+  gauge:
+    behavior: "Point-in-time value, can go up or down / 當前值，可升可降"
+    examples: ["temperature", "queue depth", "active connections"]
+  histogram:
+    behavior: "Distribution across buckets / 跨桶分布"
+    examples: ["request duration", "response size"]
+  summary:
+    behavior: "Client-computed percentiles / 客戶端計算百分位"
+    examples: ["legacy systems needing client-side quantiles"]
+
+metric_type_decision:
+  only_goes_up: "→ Counter"
+  need_distribution: "→ Histogram"
+  current_state_value: "→ Gauge"
+  legacy_client_percentiles: "→ Summary"
+
+naming: "<domain>.<entity>.<action>.<unit>"
+# e.g., http.server.request.duration.seconds
+
+# === GOLDEN SIGNALS 黃金信號 ===
+golden_signals:
+  latency:
+    what: "Request duration P50/P95/P99 / 請求延遲"
+    metric: "http.server.request.duration.seconds"
+    alert: "P99 > threshold sustained 5 min"
+  traffic:
+    what: "Requests per second (RPS) / 每秒請求數"
+    metric: "http.server.request.total (Counter, rate)"
+    alert: "Sudden drop >50% or spike >200%"
+  errors:
+    what: "Error rate = 5xx / total / 錯誤率"
+    metric: "http.server.request.total{status=~'5..'}"
+    alert: "Error rate > X% sustained 5 min"
+  saturation:
+    what: "Resource utilization / 資源飽和度"
+    metrics: ["system.cpu.utilization", "system.memory.utilization", "db.client.connection.pool.usage"]
+    alert: "Resource > 80% sustained 10 min"
+
+# === MATURITY MODEL 成熟度模型 ===
+maturity:
+  L0_no_observability:
+    characteristics: "No structured logs; debugging via SSH + tail -f / 無結構化日誌"
+    upgrade: "Implement structured logging; centralize collection"
+  L1_basic_logging:
+    characteristics: "Structured JSON logs; centralized; basic search / 結構化日誌+集中收集"
+    upgrade: "Add business metrics; create first dashboard"
+  L2_metrics_driven:
+    characteristics: "Logs + Metrics; dashboards; basic alerting / 日誌+指標+儀表板"
+    upgrade: "Enable distributed tracing; SLO-based alerting"
+  L3_full_observability:
+    characteristics: "All three pillars; correlation; SLO alerts; Golden Signals / 三支柱完整"
+    upgrade: "Add anomaly detection; auto-remediation"
+  L4_intelligent:
+    characteristics: "AIOps; predictive alerting; automatic remediation / 智慧化可觀測"
+    upgrade: "Maintain, optimize, share learnings"
+
+self_assessment:
+  - "Can you find logs for a specific request across all services? (L1+)"
+  - "Can you view dashboards showing error rate and latency? (L2+)"
+  - "Can you trace a request from ingress to database and back? (L3+)"
+  - "Does your system auto-detect anomalies before users report? (L4)"
+
+# === INSTRUMENTATION CHECKLIST 儀器化清單 ===
+pre_production_checklist:
+  - "Structured logging enabled (JSON + trace_id)"
+  - "HTTP/gRPC entry metrics (count, duration histogram, error rate)"
+  - "Critical business operation custom metrics"
+  - "Distributed tracing enabled (sampling rate set, W3C headers)"
+  - "Health check endpoints (liveness + readiness)"
+  - "Dashboard covering Golden Signals"
+  - "Alert rules defined (SLO burn rate)"
+  - "Log retention configured"
+  - "Sensitive data excluded from logs/traces"
+```
+
+---
+
+## 與相關技能整合 / Integration with Related Skills
+
+| Skill | 整合點 | 說明 |
+|-------|-------------------|-------------|
+| `/slo` | 以 SLO 為基礎的告警 | 以 metrics 作為 SLI 資料來源；burn rate 告警參照 Golden Signals |
+| `/incident` | 事件診斷 | 三大支柱提供診斷資料；correlation 加速 MTTD/MTTR |
+| `/observability --alerting` | 告警設計 | Golden Signals 引導告警規則建立 |
+
+---
+
+## 設定偵測
+
+### 偵測順序
+
+1. 檢查 `CONTRIBUTING.md` 是否有「Disabled Skills」段落
+2. 檢查 `CONTRIBUTING.md` 是否有「Observability Standards」段落
+3. 若未找到，**預設採用標準 observability 實務**
+
+---
+
+## 詳細指引
+
+完整標準請參閱：
+- [Observability Standards](../../core/observability-standards.md)
+- [Logging Standards](../../core/logging-standards.md)
+
+---
+
+## 相關標準
+
+- [Observability Standards](../../core/observability-standards.md) - 核心標準
+- [SLO Standards](../../core/slo-standards.md) - SLI/SLO/Error Budget
+- [Alerting Standards](../../core/alerting-standards.md) - 告警設計
+- [Performance Standards](../../core/performance-standards.md) - 效能目標
+- [SLO Assistant](../slo-assistant/SKILL.md) - SLO 工作流程
+- [Runbook Assistant](../runbook-assistant/SKILL.md) - 維運程序
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|---------|------|---------|
+| 1.0.0 | 2026-04-01 | 初版發布 |
+
+---
+
+## 授權
+
+本 skill 以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/orchestrate/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: orchestrate
+source: ../../../../skills/orchestrate/SKILL.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: 40e97479c7da
+scope: universal
+description: |
+  [UDS] 以 Claude 原生 Agent tool 編排多任務執行計畫（DAG-based，無外部引擎）。
+  Use when: executing a plan.json file with parallel/sequential task dependencies.
+  Keywords: orchestrate, plan, execute, DAG, task plan, 編排, 執行計畫, 並行.
+argument-hint: "<plan.json> [--dry-run]"
+---
+
+# /orchestrate — 任務計畫編排 Skill
+
+> **語言**: [English](../../../../skills/orchestrate/SKILL.md) | 繁體中文
+
+## 用法
+
+```
+/orchestrate <plan.json>           # 執行計畫
+/orchestrate <plan.json> --dry-run # 僅驗證，不執行
+```
+
+---
+
+## 執行流程
+
+### Step 1：讀取與解析計畫（Claude-native）
+
+使用 Read tool 讀取 plan.json，直接由 Claude 解析：
+
+1. 讀取 JSON 檔案，解析為任務清單
+2. 驗證結構：`tasks` 非空、每個 task 含 `id`、`title`、`spec`
+3. 安全掃描：檢查 `task.spec` 是否含危險指令（`rm -rf /`、`DROP DATABASE`、`git push --force`）
+   - 若發現安全問題，列出所有問題並**詢問使用者是否繼續**
+4. 拓撲排序：依 `depends_on` 欄位將 tasks 分組為執行層（layers）
+   - Layer 0：沒有依賴的 tasks（可並行）
+   - Layer N：依賴全部在 Layer 0..N-1 中的 tasks
+
+若 `validation.valid` 為 false，輸出錯誤訊息並停止。
+
+---
+
+### Step 2：呈現執行計畫
+
+向使用者顯示解析結果：
+
+```
+計畫：<project>  品質：<quality>
+──────────────────────────────────
+Layer 0 (並行)：T-001, T-002
+Layer 1 (序列)：T-003 (依賴 T-001)
+Layer 2 (序列)：T-004 (依賴 T-002, T-003)
+──────────────────────────────────
+共 4 個任務，3 個執行層
+```
+
+若使用 `--dry-run`：顯示以上摘要後**立即停止**，不啟動任何 Agent。
+
+---
+
+### Step 3：逐層執行
+
+對 `layers` 陣列中的每一層：
+
+1. **同層並行**：同一層的 tasks 在同一訊息中啟動多個 Agent tool
+2. **Agent tool 參數**：
+   - `prompt`：task.spec + acceptance_criteria + user_intent 組合而成的執行提示
+   - `isolation: "worktree"`：每個 task 在獨立 git worktree 執行
+   - `description`：`"Task {task.id}: {task.title}"`
+3. **等待完成**：所有同層 agents 完成後，才進入下一層
+
+**Agent 提示範本**：
+```
+Task: {task.title}
+
+Spec:
+{task.spec}
+
+Acceptance Criteria:
+{task.acceptance_criteria 逐條列出}
+
+User Intent:
+{task.user_intent}
+
+After completing the task, run: {task.verify_command}
+```
+
+---
+
+### Step 4：依賴失敗處理
+
+如果某個 task 的 agent 回報失敗：
+- 標記該 task 為 `failed`
+- 後續層中 `depends_on` 包含該 task ID 的所有 tasks 標記為 `skipped`
+- 繼續執行不受影響的 tasks
+- 最終報告中標示失敗原因
+
+---
+
+### Step 5：Quality Gate
+
+每個 task 完成後，若 task 定義了 `verify_command`：
+
+1. 使用 Bash tool 執行 `verify_command`
+2. **成功**：記錄 `status: "success"`
+3. **失敗**：
+   - 若 `quality` 為 `"strict"` 或 `"standard"`：啟動 Fix Loop
+   - Fix Loop：將錯誤輸出回傳給 agent，重新執行（最多 3 次）
+   - 超過重試上限：標記為 `failed`
+
+---
+
+### Step 6：Judge 審查（選用）
+
+如果 task 定義了 `judge: true`：
+- 啟動一個額外的 Agent tool 進行審查
+- 提示：`審查 task {id} 的 git diff，依照 code-review 標準檢查`
+- Judge 結果附加到最終報告
+
+---
+
+### Step 7：產出報告
+
+彙整所有 task 結果，輸出執行報告：
+
+```json
+{
+  "summary": {
+    "total_tasks": 4,
+    "succeeded": 3,
+    "failed": 1,
+    "skipped": 0,
+    "total_duration_ms": 120000
+  },
+  "tasks": [
+    { "task_id": "T-001", "status": "success", "duration_ms": 30000 },
+    { "task_id": "T-002", "status": "failed",  "error": "..." },
+    { "task_id": "T-003", "status": "skipped", "reason": "依賴任務失敗" }
+  ]
+}
+```
+
+---
+
+## 品質設定檔
+
+| Profile | 行為 |
+|---------|------|
+| `strict` | 全部檢查 + Fix Loop 最多 5 次 |
+| `standard` | lint + test + Fix Loop 最多 3 次（預設） |
+| `minimal` | 僅跑 verify_command，不 Fix Loop |
+| `none` | 不執行任何驗證 |
+
+---
+
+## 重要注意事項
+
+- 每個 Agent tool 的 `isolation: "worktree"` 會自動建立 git worktree
+- `depends_on: []` 的 tasks 在同一層內全部並行
+- 使用繁體中文回覆使用者
+
+---
+
+## 版本歷程
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 2.0.0 | 2026-04-28 | 升格為 UDS 正式 Skill；Step 1 改為 Claude-native 解析（移除 plan-resolver-cli.js 依賴）；新增 Quality Gate / Fix Loop 章節（XSPEC-097 Phase 3） |
+| 1.0.0 | 2026-04-09 | 初始發布（從上游遷移） |

package/bundled/locales/zh-TW/skills/plan/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: plan
+source: ../../../../skills/plan/SKILL.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: 6fbb1a1b8040
+scope: universal
+description: |
+  [UDS] 從 Spec 文件、OpenSpec 變更或自由文字需求生成 plan.json。
+  Use when: converting specifications into executable task plans for /orchestrate.
+  Keywords: plan, spec, task plan, 計畫, 規格, 任務, plan.json, DAG.
+argument-hint: "[spec-file.md | openspec-dir/ | \"需求描述文字\" | (互動模式)]"
+---
+
+# /plan — 從 Spec 自動生成 plan.json
+
+> **語言**: [English](../../../../skills/plan/SKILL.md) | 繁體中文
+
+## 用法
+
+```
+/plan <spec-file.md>              # Spec 模式（自有格式 / SpecKit）
+/plan <openspec-change-dir/>      # OpenSpec 模式
+/plan "需求描述文字"               # 需求模式
+/plan                             # 互動模式（自動偵測）
+```
+
+---
+
+## 執行流程
+
+### Step 1：輸入辨識與格式偵測
+
+根據引數類型判斷使用模式：
+
+**引數是 .md 檔案：**
+1. 讀取檔案內容
+2. 偵測格式：
+   - 含 `## Requirements` **且** `## Technical Design` → **自有格式**（SPEC-NNN-*.md）
+   - 含 `## Summary` **且** `## Detailed Design` → **SpecKit 格式**
+   - 其他 .md → 嘗試解析為通用 Spec（按自有格式處理，缺少的欄位由 AI 補充）
+
+**引數是目錄：**
+1. 檢查是否含 `proposal.md` + `tasks.md` → **OpenSpec 格式**
+2. 否則報錯：「此目錄不符合 OpenSpec 結構」
+
+**引數是字串描述（非檔案路徑）：**
+→ **需求模式**
+
+**無引數：**
+→ **互動模式**
+1. 偵測 `openspec/` 目錄存在？ → 列出 changes 讓使用者選擇
+2. 偵測 `specs/*.md` 存在？ → 列出可用 Spec 讓使用者選擇
+3. 都沒有 → 進入需求模式問答
+
+---
+
+### Step 2：專案 Context 收集
+
+讀取目標專案的關鍵資訊：
+
+1. **CLAUDE.md / AGENTS.md** — 語言、框架、測試工具、開發規範
+2. **package.json / pyproject.toml** — 可用 scripts（build, test, lint）
+
+從 Context 推斷：
+- 主要語言（TypeScript / Python / 其他）
+- 預設 verify_command（如 `pnpm build && pnpm test`、`pytest -x`）
+- 預設 lint_command（如 `pnpm lint`、`ruff check .`）
+
+---
+
+### Step 3：Spec 解析
+
+依偵測到的格式，解析 Spec 內容：
+
+#### 自有格式（SPEC-NNN-*.md）
+
+提取以下區段：
+- **Summary / Motivation** → 理解背景與需求動機
+- **Requirements (REQ-NNN)** → 功能需求列表
+- **Acceptance Criteria (AC-N)** → Given/When/Then 驗收條件
+- **Technical Design** → Phase 分層、每個 Phase 的實作項目
+- **Test Plan** → 測試清單
+- **Risks** → 風險評估
+
+#### OpenSpec（change 目錄）
+
+讀取以下檔案：
+- `proposal.md` → Why（動機）、What Changes（變更項目）、Impact
+- `tasks.md` → `- [ ]` checklist 項目
+- `design.md`（若存在）→ 技術決策
+- `specs/*/spec.md`（若存在）→ Requirements（SHALL / MUST 語句）、Scenarios
+
+#### SpecKit（SPEC-ID.md）
+
+提取以下區段：
+- **Summary / Motivation** → 背景
+- **Detailed Design** → 技術實作步驟
+- **Acceptance Criteria** → checkbox 驗收條件
+- **Dependencies** → 外部依賴
+- **Risks** → 風險
+
+---
+
+### Step 4：Task 切分
+
+依格式套用不同映射規則：
+
+#### 自有格式映射規則
+
+| Spec 區段 | plan.json 欄位 | 映射規則 |
+|-----------|---------------|----------|
+| Technical Design > Phase | 一組 tasks | 每個 Phase 的每個實作項目 = 1 個 task |
+| Phase 實作項目描述 | `task.spec` | 合併：項目描述 + 相關 REQ + 技術細節 |
+| Acceptance Criteria (AC-N) | `task.acceptance_criteria` | 分配到最相關的 task |
+| Summary / Motivation | `task.user_intent` | 萃取與 task 最相關的意圖 |
+| Test Plan | `task.verify_command` | 推斷測試指令 |
+
+#### OpenSpec 映射規則
+
+| OpenSpec 檔案 | plan.json 欄位 | 映射規則 |
+|--------------|---------------|----------|
+| `tasks.md` 的 checklist 項目 | tasks | 每個 `- [ ]` 項目 = 1 個 task |
+| `proposal.md` > Why | `task.user_intent` | 所有 tasks 共用 |
+| `proposal.md` > What Changes | 融入 `task.spec` | 提供變更脈絡 |
+| `design.md` 技術細節 | 融入 `task.spec` | 補充實作指引 |
+| `specs/*/spec.md` > Scenarios | `task.acceptance_criteria` | 每個 Scenario 映射為一條 criteria |
+| `specs/*/spec.md` > Requirements | 融入 `task.spec` | SHALL / MUST 語句轉為具體實作指引 |
+
+---
+
+### Step 5：依賴推斷
+
+為 tasks 建立 `depends_on` 關係：
+
+1. **Phase / Stage 順序**：後面的 Phase 的第一個 task depends_on 前面 Phase 的最後一個 task
+2. **同 Phase 內順序**：型別定義 → 實作 → 整合 → 測試
+3. **檔案依賴**：A 建立的檔案被 B import → B depends_on A
+4. **無依賴的 tasks**：`depends_on: []`（可並行）
+
+---
+
+### Step 6：verify_command 推斷
+
+依以下優先順序推斷：
+
+1. **Test Plan / Scenarios 有明確測試項** → 對應測試指令
+2. **TypeScript 專案** → `pnpm build && pnpm test`
+3. **Python 專案** → `pytest -x`
+4. **其他** → 使用 Step 2 收集的專案 scripts
+5. **無法推斷** → 不設（後續品質警告會提醒）
+
+---
+
+### Step 7：品質設定
+
+- 預設 `quality: "standard"`
+- 使用者可在互動確認時調整
+
+---
+
+### Step 8：組裝 plan.json
+
+```json
+{
+  "project": "<專案名稱>",
+  "quality": "standard",
+  "defaults": {
+    "max_turns": 30,
+    "max_budget_usd": 2.0,
+    "verify_command": "<推斷的預設驗證指令>"
+  },
+  "tasks": [
+    {
+      "id": "T-001",
+      "title": "<task 標題>",
+      "spec": "<詳細的 task 規格說明>",
+      "depends_on": [],
+      "verify_command": "<task 層級驗證指令（可選）>",
+      "acceptance_criteria": ["<驗收條件 1>"],
+      "user_intent": "<使用者意圖>"
+    }
+  ]
+}
+```
+
+**注意事項：**
+- Task ID 格式：`T-NNN`（如 T-001, T-002）
+- `spec` 欄位應詳盡——它是 agent 執行任務的唯一規格輸入
+- `acceptance_criteria` 每條都必須是可觀察、可驗證的
+
+---
+
+### Step 9：驗證（Claude-native）
+
+Claude 對 plan.json 執行以下驗證（無需外部引擎）：
+
+1. **結構驗證**：`tasks` 陣列存在且非空、每個 task 含必填欄位（id, title, spec）
+2. **DAG 合法性**：`depends_on` 中的所有 ID 均存在、無循環依賴
+3. **安全掃描**：task.spec 不含危險指令（`rm -rf /`、`DROP DATABASE`、`git push --force`）
+4. **品質警告**：task 缺少 verify_command、spec 過短（< 20 字）等
+
+若發現問題，在呈現前先自動修正（若可修正）或標示警告。
+
+---
+
+### Step 10：呈現與確認
+
+向使用者呈現生成結果：
+
+1. **摘要表格**：
+   ```
+   | Task ID | 標題 | 依賴 | 驗證指令 |
+   |---------|------|------|----------|
+   | T-001   | ...  | -    | ...      |
+   | T-002   | ...  | T-001| ...      |
+   ```
+
+2. **DAG 拓撲**：
+   ```
+   Layer 0: T-001, T-002（並行）
+   Layer 1: T-003（依賴 T-001）
+   Layer 2: T-004（依賴 T-002, T-003）
+   ```
+
+3. **品質設定**：`quality: standard`
+
+4. **品質警告**（若有）
+
+5. **詢問使用者**：確認或修改？確認後寫入檔案（預設路徑：`plans/<spec-name>.plan.json`）
+
+---
+
+## 版本歷程
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 2.0.0 | 2026-04-28 | 升格為 UDS 正式 Skill；移除 [DEVAP] 標記；Step 9 改為 Claude-native 驗證（XSPEC-097 Phase 3） |
+| 1.0.0 | 2026-04-09 | 初始發布（從上游遷移） |

package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md

@@ -3,8 +3,12 @@ name: project-structure-guide
 source: ../../../../skills/project-structure-guide/SKILL.md
 source_version: 1.1.0
 translation_version: 1.1.0
-last_synced: 2026-03-04
+last_synced: 2026-05-28
 status: current
+description: |
+  [UDS] 引導依語言特性最佳實踐組織專案目錄結構。
+  Use when: creating projects, reorganizing structure, adding modules, setting up builds, deciding file placement.
+  Keywords: project, structure, directory, layout, gitignore, scaffold, file placement, 專案結構, 目錄配置.
 ---
 
 # 專案結構指南