universal-dev-standards 5.13.3 → 5.15.1

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

@@ -0,0 +1,172 @@
+---
+name: orchestrate
+source: ../../../../skills/orchestrate/SKILL.md
+source_version: 2.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+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,239 @@
+---
+name: plan
+source: ../../../../skills/plan/SKILL.md
+source_version: 2.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+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, 專案結構, 目錄配置.
 ---
 
 # 專案結構指南

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

@@ -0,0 +1,241 @@
+---
+name: push
+source: ../../../../skills/push/SKILL.md
+source_version: 2.0.0
+translation_version: 1.0.0
+last_synced: 2026-05-28
+scope: universal
+description: |
+  [UDS] AI 輔助 git push 安全層：品質閘門 + 協作護欄。
+  Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
+  Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保護分支, 品質閘門.
+allowed-tools: Read, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(bun:*)
+argument-hint: "[--force] [--target <branch>] [--skip-gates] [--no-pr]"
+---
+
+# 推送助手
+
+> **語言**: [English](../../../../skills/push/SKILL.md) | 繁體中文
+
+**版本**：2.0.0
+**建立日期**：2026-04-23
+**適用範圍**：Claude Code Skills
+
+---
+
+`git push` 的 AI 輔助安全層。偵測保護分支、強制 force-push 護欄、執行 pre-push 品質閘門、輸出結構化推送收據，並整合 PR 自動化。
+
+## 核心標準
+
+本 Skill 實作 [`.standards/push-standards.ai.yaml`](../../../../.standards/push-standards.ai.yaml)。
+
+---
+
+## 執行工作流程
+
+呼叫 `/push` 後，Claude 原生依序執行以下步驟：
+
+### Step 1：偵測保護分支
+執行 `git rev-parse --abbrev-ref HEAD` 取得目前分支。
+比對 `protected_branches` 清單（預設：main、master、release/*、hotfix/*）。
+若為保護分支：顯示警告 + 待推送的 commit 列表，需使用者明確確認才能繼續。
+
+### Step 2：偵測 Force Push
+若偵測到 `--force` 或 `--force-with-lease`：
+執行 `git log origin/<branch>..HEAD --oneline` 找出將被覆蓋的 commits。
+顯示數量與作者列表。需要使用者輸入 `yes, force push` 才能繼續。
+
+### Step 3：執行 Pre-Push 品質閘門
+依序使用 Bash tool 執行每個已設定的閘門：
+- `lint`：偵測並執行專案 lint 指令
+- `test`：偵測並執行專案測試指令
+- `type-check`（選用）：TypeScript 型別檢查
+- `ac-coverage`（選用）：驗收條件覆蓋率
+- `security-scan`（選用）：安全漏洞掃描
+
+若任何必要閘門失敗：中止並顯示錯誤訊息。
+
+### Step 4：執行推送
+執行 `git push <remote> <branch> [--force]`。
+若推送失敗：顯示 git 錯誤並建議修正方式。
+
+### Step 5：發出推送收據
+將結構化收據輸出到 console（可選擇寫入 `~/.uds/push-history.jsonl`）：
+```json
+{
+  "branch": "<branch>",
+  "commit_sha": "<sha>",
+  "gates_passed": ["lint", "test"],
+  "force_push": false,
+  "timestamp": "<ISO8601>",
+  "target_remote": "origin"
+}
+```
+
+### Step 6：PR 整合
+若 `auto_pr=true` **且** `repo_mode=team` **且**該分支無 open PR：
+建議使用者執行 `/pr-automation-assistant` 建立 Pull Request。
+
+---
+
+## 功能說明
+
+### 1. 推送目標風險偵測
+
+推送前偵測目標分支是否為保護分支（例如 `main`、`master`、`release/*`、`hotfix/*`）。
+
+- 顯示**警告**，列出分支名稱與 commit 清單
+- 需要使用者明確確認才能繼續
+- 使用者未確認則中止推送
+
+### 2. Force-Push 護欄
+
+偵測到 `--force` 時，推送前顯示影響範圍。
+
+- 計算遠端將被覆蓋的 commits
+- 顯示被覆蓋 commits 的數量與作者
+- 要求使用者輸入確認字串（`yes, force push`）
+- 在推送收據中記錄 `force_push: true`
+
+### 3. Pre-Push 品質閘門
+
+推送前依序執行已設定的品質閘門。
+
+| 閘門 | 說明 |
+|------|------|
+| `lint` | 執行 lint 檢查 |
+| `test` | 執行測試 |
+| `type-check` | TypeScript 型別檢查（選用） |
+| `ac-coverage` | AC 覆蓋率檢查（選用） |
+| `security-scan` | 安全掃描（選用） |
+
+### 4. 推送收據
+
+推送成功後輸出結構化收據，供稽核追蹤使用。
+
+```json
+{
+  "branch": "feature/my-feature",
+  "commit_sha": "a1b2c3d",
+  "gates_passed": ["lint", "test"],
+  "gates_skipped": false,
+  "force_push": false,
+  "timestamp": "2026-04-23T10:00:00Z",
+  "target_remote": "origin"
+}
+```
+
+可選擇附加到 `~/.uds/push-history.jsonl` 以持久化稽核追蹤。
+
+### 5. PR 自動化整合入口
+
+推送 feature branch 後，若尚無 PR，提示使用者建立 Pull Request。
+
+- 檢查該分支是否已有 open PR
+- 提示使用者執行 `pr-automation-assistant`
+- 在 `single-owner` repo 模式或使用 `--no-pr` 旗標時跳過
+
+---
+
+## 使用方式
+
+```bash
+# 標準推送（自動執行品質閘門）
+/push
+
+# Force push（顯示被覆蓋 commits，需要確認）
+/push --force
+
+# 推送到指定的遠端分支
+/push --target main
+
+# 跳過品質閘門（緊急情況）
+/push --skip-gates
+
+# 推送但不提示建立 PR
+/push --no-pr
+
+# Force push 且不提示建立 PR（例如更新個人分支）
+/push --force --no-pr
+```
+
+## 參數說明
+
+| 參數 | 說明 |
+|------|------|
+| `--force` | 啟用 force push，含護欄確認 |
+| `--target <branch>` | 明確指定目標遠端分支 |
+| `--skip-gates` | 跳過品質閘門（僅緊急情況） |
+| `--no-pr` | 推送後不提示建立 PR |
+
+---
+
+## 設定
+
+透過 `uds.project.yaml` 設定：
+
+```yaml
+push:
+  repo_mode: team           # "team" | "single-owner"
+  protected_branches:
+    - main
+    - master
+    - "release/*"
+    - "hotfix/*"
+  push_gates:
+    default:
+      - lint
+      - test
+    optional:
+      - type-check
+      - ac-coverage
+      - security-scan
+  receipt:
+    output: console          # "console" | "file" | "both"
+    file_path: "~/.uds/push-history.jsonl"
+  auto_pr: true              # 推送到非保護分支後是否提示建立 PR
+```
+
+### 選項模式
+
+| Option 檔案 | 模式 | 說明 |
+|-------------|------|------|
+| [`options/push/team-mode.md`](../../../../options/push/team-mode.md) | `team` | 完整協作護欄（預設） |
+| [`options/push/single-owner-mode.md`](../../../../options/push/single-owner-mode.md) | `single-owner` | 個人 repo 低摩擦模式 |
+
+---
+
+## 下一步引導
+
+`/push` 完成後，AI 助手應建議：
+
+> **推送完成。建議下一步：**
+> - 執行 `/pr-automation-assistant` 建立或更新 Pull Request ⭐ **推薦** — 確保協作流程完整
+> - 執行 `/checkin` 確認程式碼簽入品質 — 下次提交前的品質確認
+> - 查看 `~/.uds/push-history.jsonl` 確認推送紀錄 — 稽核追蹤
+
+---
+
+## 相關標準
+
+- [Push Standards](../../../../.standards/push-standards.ai.yaml) — 核心推送安全規則
+- [Git Workflow](../../../../.standards/git-workflow.ai.yaml) — 分支策略
+- [Commit Message](../../../../.standards/commit-message.ai.yaml) — Commit 慣例
+- [PR Automation](../pr-automation-assistant/SKILL.md) — Pull Request 自動化
+
+---
+
+## 版本歷程
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 2.0.0 | 2026-04-28 | 還原 workflow 執行步驟（XSPEC-097 採用層解耦）；移除棄用通知 |
+| 1.0.0 | 2026-04-23 | 初始版本 — XSPEC-081 Phase 1 |
+
+---
+
+## 授權
+
+本 Skill 採用 [MIT License](https://opensource.org/licenses/MIT) 與 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 雙重授權發布。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)