universal-dev-standards 6.4.0 → 6.5.0

package/bundled/ai/standards/agent-dispatch.ai.yaml

@@ -0,0 +1,162 @@
+# Agent Dispatch & Parallel Coordination - AI Optimized
+# Source: core/agent-dispatch.md
+# Inspired by Superpowers dispatching-parallel-agents / subagent-driven-development (MIT)
+#
+# Reinstated by XSPEC-362 R5a. This file was removed in 6.0.0 as part of the
+# XSPEC-086 Phase 2 / DEC-049 migration, which moved the machine-readable copy to
+# dev-autopilot as canonical owner. That owner entered maintenance mode on 2026-04-28,
+# so the machine-readable form has had no maintained home since — while
+# core/agent-dispatch.md continued to ship in the npm bundle. Adopters installing with
+# `--format ai` therefore received the prose nowhere and the rules not at all.
+
+standard:
+  id: agent-dispatch
+  name: Agent Dispatch & Parallel Coordination
+  description: AI 子代理的並行派遣、工作協調與狀態回報標準
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-03-20"
+    source: core/agent-dispatch.md
+    description: "並行派遣、獨立域判準、狀態回報協定、prompt 設計原則"
+    inspired_by: superpowers/dispatching-parallel-agents
+    reinstated:
+      in_version: "unreleased"   # 由 bump-version 於發版時決定，此處不預先宣稱版本號
+      reason: >
+        XSPEC-362 R5a。6.0.0（XSPEC-086 Phase 2 / DEC-049）將機器可讀版遷至 dev-autopilot 作為
+        canonical 位置後移除本檔；該 canonical owner 於 2026-04-28 進入維護模式，
+        機器可讀版自此無人維護，而散文版仍隨 bundle 出貨。此為出貨缺口，非刻意的能力刪減。
+
+  scope:
+    covers: "怎麼派 — 並行安全、獨立域判準、狀態回報協定、prompt 設計"
+    does_not_cover: "派給誰、想多深 — 見 model-selection 標準（模型軸 × effort 軸）"
+    boundary_rule: >
+      並行安全規則屬於本標準。model-selection 及其衍生的 agent 定義必須「引用」本標準，
+      不得重寫一份——兩份並行安全規則會各自漂移，而漂移的樣子與正常的樣子無從分辨。
+
+  guidelines:
+    - "派遣前必須識別獨立域 — 無共享可變狀態才可並行"
+    - "每個子代理的 prompt 必須聚焦、自足、輸出格式明確"
+    - "子代理完成時必須回報四態之一"
+    - "並行代理返回後，先檢查檔案衝突再跑完整測試"
+
+  core_principle:
+    id: independence_before_parallelism
+    statement: "在並行派遣代理之前，先驗證其任務域彼此獨立（無共享可變狀態）"
+    independent_domain_criterion: "無共享可變狀態（no shared mutable state）"
+
+  prompt_design_principles:
+    - id: focused
+      name_zh: "聚焦"
+      rule: "每個代理只處理單一問題域，不混合無關任務"
+    - id: self_contained
+      name_zh: "自足"
+      rule: "prompt 包含執行所需的完整上下文；代理不需額外提問或搜尋"
+      note: >
+        子代理載入的是「主 session 工作目錄」的專案指示與技能清單，不是它實際要操作的那個 repo 的。
+        同 repo 派工時規則會自行到位；跨 repo 派工時，目標 repo 的規則完全不在 context 中——
+        commit 格式、測試指令、授權邊界若未寫進 prompt，就等於不存在。
+      note_correction:
+        corrected_on: "2026-08-12"
+        previous_claim: "子代理不會自動載入目標專案的專案指示，也無法呼叫目標專案的技能"
+        why_it_was_wrong: >
+          該陳述在宿主文件與實測下都不成立：子代理會載入 CLAUDE.md 階層，也能經 Skill 工具呼叫技能。
+          真正的限制是「載入的是哪一份」——主 session 工作目錄的那一份。
+        why_the_distinction_matters: >
+          只寫「不會載入」的話，下一個讀宿主文件的人會判定本規則已過時而移除它，
+          而跨 repo 的缺口仍然存在。差別在「哪一份」，不在「有沒有」。
+        measurement: >
+          2026-08-12：自工作目錄為 repo A 的 session 派出一個被禁用所有工具的子代理，
+          要它僅憑啟動時的 context 說出看得到哪些 CLAUDE.md，答完後才准跑 pwd。
+          結果：context 內只有使用者層 ~/.claude/CLAUDE.md 與 repo A 的 CLAUDE.md；
+          目標 repo B 的不在其中；pwd 回傳 repo A。
+        host_documentation_agrees: >
+          宿主文件的措辭是「every level of the CLAUDE.md hierarchy the main conversation loads」——
+          載重的是 the main conversation 這幾個字。
+        host_layer_artifact: integrations/claude-code/dispatch-template.md
+    - id: specific_output
+      name_zh: "明確輸出"
+      rule: "明確定義期望的回報格式"
+
+  status_protocol:
+    description: "子代理完成時必須回報四態之一"
+    states:
+      - id: DONE
+        description: "任務成功完成"
+        orchestrator_action: "繼續下一個任務"
+      - id: DONE_WITH_CONCERNS
+        description: "完成，但有需要記錄的疑慮"
+        orchestrator_action: "記錄疑慮，繼續"
+      - id: NEEDS_CONTEXT
+        description: "需要更多上下文才能完成"
+        orchestrator_action: "注入上下文後重新派遣（不是重試）"
+      - id: BLOCKED
+        description: "無法完成，需要升級"
+        orchestrator_action: "升級模型層級或拆分任務（層級選擇見 model-selection）"
+    decision_flow: |
+      代理完成工作
+        ├── 全部驗收標準達成？        → DONE
+        ├── 標準達成但有疑慮？        → DONE_WITH_CONCERNS
+        ├── 缺少資訊無法繼續？        → NEEDS_CONTEXT
+        └── 根本上無法完成？          → BLOCKED
+
+  conflict_detection:
+    description: "並行代理返回時，orchestrator 必須執行的檢查"
+    steps:
+      - "檢查檔案衝突 — 是否有多個代理修改了同一個檔案"
+      - "執行完整測試套件 — 合併所有變更後驗證整合"
+      - "解決衝突 — 自動處理或標記交由人工審查"
+
+  rules:
+    - id: AD-001
+      trigger: "多個代理編輯同一個檔案"
+      action: "標記衝突，要求合併解決"
+      priority: critical
+    - id: AD-002
+      trigger: "代理回報 BLOCKED"
+      action: "升級模型層級並重試一次（層級選擇判準見 model-selection）"
+      priority: high
+    - id: AD-003
+      trigger: "所有並行代理完成"
+      action: "執行完整測試套件以驗證整合"
+      priority: high
+
+  examples:
+    good_parallel_independent:
+      description: "兩個代理處理獨立模組 — 無共享檔案，可安全並行"
+      agents:
+        - task: "為 /api/users 端點加上 rate limiting"
+          files: ["src/api/users.ts", "src/api/users.test.ts"]
+        - task: "為 /api/products 端點加上快取"
+          files: ["src/api/products.ts", "src/api/products.test.ts"]
+    bad_parallel_dependent:
+      description: "兩個代理修改共享狀態 — 同一檔案，會衝突"
+      agents:
+        - task: "重構資料庫連線池"
+          files: ["src/db.ts"]
+        - task: "加上連線重試邏輯"
+          files: ["src/db.ts"]
+
+  related_standards:
+    - id: model-selection
+      relationship: >
+        model-selection 管「派給誰、想多深」（模型軸 × effort 軸），本標準管「怎麼派」。
+        兩者互補；AD-002 的「升級模型層級」其判準定義在 model-selection，不在這裡。
+    - id: git-worktree
+      relationship: "並行代理若必須在同一 repo 工作，以 worktree 隔離取代共享工作區"
+    - id: agent-communication-protocol
+      relationship: "代理之間的訊息格式；本標準只規範對 orchestrator 的狀態回報"
+
+physical_spec:
+  type: checklist
+  validator:
+    type: ai_review
+    rule: "檢查並行派遣前是否驗證過任務域獨立性，且每個代理都回報了四態之一"
+  checks:
+    - "並行派遣前是否確認任務域無共享可變狀態"
+    - "每個子代理的 prompt 是否聚焦於單一問題域"
+    - "prompt 是否自足（含目標專案的關鍵規則，不倚賴代理自行載入）"
+    - "prompt 是否明確定義回報格式"
+    - "子代理是否回報 DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED 之一"
+    - "並行代理返回後是否檢查檔案衝突"
+    - "合併所有變更後是否執行完整測試套件"

package/bundled/ai/standards/ai-friendly-architecture.ai.yaml

@@ -59,7 +59,7 @@ principles:
     rule: Enable understanding through configuration and entry point analysis
     key_files:
       - .ai-context.yaml
-      - package.json / pyproject.toml
+      - "package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml / build.gradle / Gemfile"
       - Entry point files
       - QUICK-REF.md files
 

package/bundled/ai/standards/ai-instruction-standards.ai.yaml

@@ -3,30 +3,205 @@
 
 id: ai-instruction-standards
 meta:
-  version: "1.1.0"
-  updated: "2026-05-28"
+  version: "2.1.0"
+  updated: "2026-08-12"
   source: core/ai-instruction-standards.md
-  description: Best practices for creating AI instruction files (root and skill level) with universal/project-specific separation and i18n strategy
+  description: Best practices for creating AI instruction files (root and skill level) with universal/project-specific separation, i18n strategy, and a detailed cross-tool support matrix
 
+# ─────────────────────────────────────────────
+# 工具支援清單 (2026-04-28 更新)
+# ─────────────────────────────────────────────
 supported_tools:
+
+  # CLI / Agent 型（終端機代理）
   - tool: Claude Code
-    file: CLAUDE.md
-    format: Markdown
+    vendor: Anthropic
+    category: cli_agent
+    primary_file: CLAUDE.md
+    additional_files:
+      - path: .claude/rules/*.md
+        note: glob-based conditional rules
+    workflow_mechanism: Skills (.claude/skills/*.md → /{skill-name})
+    subagent_config: .claude/agents/
+    mcp_support: true
+    hooks: true
+    notes: Hierarchical CLAUDE.md (global → project → subdir); most advanced hook system
+
+  - tool: Gemini CLI
+    vendor: Google
+    category: cli_agent
+    primary_file: GEMINI.md
+    workflow_mechanism: ".gemini/commands/*.toml → /{command-name}; supports !{shell} inline"
+    subagent_config: .gemini/agents/
+    mcp_support: true
+    hooks: false
+    notes: "1M context window; A2A remote agents; free tier with Google account; Apache 2.0 open source"
+
+  - tool: OpenAI Codex CLI
+    vendor: OpenAI
+    category: cli_agent
+    primary_file: AGENTS.md
+    additional_files:
+      - path: AGENTS.override.md
+        note: temporary override, highest priority
+      - path: ~/.codex/AGENTS.md
+        note: global fallback
+    workflow_mechanism: "Local team commands; /review (non-destructive code review)"
+    subagent_config: .codex/agents/
+    mcp_support: true
+    hooks: true
+    notes: "Direct Agents SDK integration; spawn_agents_on_csv batch processing; AGENTS.md traverses from Git root to cwd"
+
+  - tool: OpenCode
+    vendor: Open Source
+    category: cli_agent
+    primary_file: AGENTS.md
+    additional_files:
+      - path: CLAUDE.md
+        note: auto-recognized for migration compatibility
+    workflow_mechanism: "No custom slash commands; /init /undo /redo /share built-in"
+    subagent_config: .opencode/agents/
+    mcp_support: true
+    hooks: true
+    notes: "75+ LLM providers; CLAUDE.md backward-compatible; HTTP API for programmatic control; 95K+ GitHub stars"
+
+  # AI-native IDE / 編輯器整合
   - tool: Cursor
-    file: .cursorrules
-    format: Markdown
+    vendor: Anysphere
+    category: ide
+    primary_file: .cursor/rules/*.mdc
+    deprecated_file: .cursorrules
+    additional_files:
+      - path: AGENTS.md
+        note: also supported for agent context
+    workflow_mechanism: "@-mentions for context; /multitask for parallel subagents; no custom slash commands"
+    subagent_config: Background Agents (cloud VM); /multitask inline
+    mcp_support: true
+    hooks: true
+    notes: ".cursorrules is DEPRECATED — migrate to .cursor/rules/*.mdc with MDC frontmatter (description, globs, alwaysApply); Background Agents run on cloud Ubuntu VM; BugBot auto-reviews PRs"
+
+  - tool: GitHub Copilot
+    vendor: GitHub / Microsoft
+    category: ide
+    primary_file: .github/copilot-instructions.md
+    additional_files:
+      - path: .github/instructions/*.instructions.md
+        note: conditional, file-glob scoped (applyTo frontmatter)
+      - path: .github/prompts/*.prompt.md
+        note: reusable task templates, exposed as slash commands
+      - path: .github/agents/*.agent.md
+        note: custom agents with fine-grained tool access
+      - path: AGENTS.md
+        note: also recognized
+    workflow_mechanism: ".github/prompts/*.prompt.md → /{prompt-name}; .github/agents/*.agent.md → named agents"
+    subagent_config: ".github/agents/*.agent.md; Local/CLI/Cloud/Third-party 4 deployment models"
+    mcp_support: true
+    hooks: true
+    notes: "Organization-level instructions for enterprise; priority: personal > repo > org; multi-model (Claude, GPT-5, Gemini)"
+
   - tool: Windsurf
-    file: .windsurfrules
-    format: Markdown
+    vendor: Codeium
+    category: ide
+    primary_file: .windsurfrules
+    additional_files:
+      - path: .windsurf/rules/*.md
+        note: MDC frontmatter, structured rules
+      - path: AGENTS.md
+        note: auto-recognized; subdir scope via location-based activation
+    workflow_mechanism: ".windsurf/workflows/*.md → /{workflow-name}; nestable workflows"
+    subagent_config: "Up to 5 parallel agents (Wave 13); each in isolated Git worktree"
+    mcp_support: true
+    hooks: true
+    notes: "Arena Mode: compare multiple agents on same task; SWE-1.5 proprietary coding model; MDM enterprise policy deployment; VS Code extension compatible"
+
   - tool: Cline
-    file: .clinerules
-    format: Markdown
+    vendor: Open Source
+    category: ide
+    primary_file: .clinerules
+    workflow_mechanism: Chat-based, no custom slash commands
+    subagent_config: null
+    mcp_support: true
+    hooks: false
+    notes: VS Code extension; MCP-first design
+
+# ─────────────────────────────────────────────
+# 跨工具通用標準：AGENTS.md
+# ─────────────────────────────────────────────
+cross_tool_standard:
+  file: AGENTS.md
+  description: |
+    AGENTS.md is emerging as the de-facto cross-tool instruction standard.
+    Supported by: Gemini CLI, OpenAI Codex CLI, OpenCode, GitHub Copilot, Windsurf, Cursor.
+    Recommendation: use AGENTS.md as the universal baseline, then add tool-specific files for advanced features.
+  supported_by:
+    - Gemini CLI
+    - OpenAI Codex CLI
+    - OpenCode
+    - GitHub Copilot
+    - Windsurf
+    - Cursor
+  not_supported_by:
+    - Claude Code  # uses CLAUDE.md; AGENTS.md not auto-recognized
+    - Cline        # uses .clinerules
+
+# ─────────────────────────────────────────────
+# Slash Commands / Workflow 機制對照
+# ─────────────────────────────────────────────
+workflow_mechanisms:
+  - tool: Claude Code
+    mechanism: Skills
+    file_pattern: .claude/skills/{name}/SKILL.md
+    trigger: "/{skill-name}"
+    shareable: true
+    notes: Supports allowed-tools, scope, argument-hint frontmatter
+
+  - tool: Gemini CLI
+    mechanism: Custom Commands
+    file_pattern: ".gemini/commands/{name}.toml (or {namespace}/{name}.toml)"
+    trigger: "/{command-name} or /{namespace}:{name}"
+    shareable: true
+    notes: "Supports !{shell} inline execution; MCP prompts auto-exposed as slash commands"
+
+  - tool: Windsurf
+    mechanism: Workflows
+    file_pattern: .windsurf/workflows/{name}.md
+    trigger: "/{workflow-name}"
+    shareable: true
+    notes: Nestable; manual trigger only (not auto-invoked by Cascade)
+
   - tool: GitHub Copilot
-    file: .github/copilot-instructions.md
-    format: Markdown
+    mechanism: Prompt Files + Agent Skills
+    file_pattern: ".github/prompts/{name}.prompt.md"
+    trigger: "/{prompt-name}"
+    shareable: true
+    notes: ".github/agents/*.agent.md for specialized agents with tool access control"
+
+  - tool: Cursor
+    mechanism: None (native)
+    file_pattern: null
+    trigger: "@-mentions, /multitask"
+    shareable: false
+    notes: No custom slash command system; use rules files for persistent behavior
+
+  - tool: OpenAI Codex CLI
+    mechanism: Team Commands
+    file_pattern: local team config
+    trigger: custom
+    shareable: false
+    notes: Limited; primary interaction via chat
+
   - tool: OpenCode
-    file: .opencode/instructions.md
-    format: Markdown
+    mechanism: None (native)
+    file_pattern: null
+    trigger: Built-in only (/init /undo /redo /share)
+    shareable: false
+    notes: No custom slash command system
+
+  - tool: Cline
+    mechanism: None
+    file_pattern: null
+    trigger: null
+    shareable: false
 
 content_types:
   universal:

package/bundled/ai/standards/class-level-fix.ai.yaml

@@ -7,13 +7,17 @@ standard:
   description: 類別層修正標準——修正瞄準集合，不是瞄準成員
 
   meta:
-    version: "1.0.0"
-    updated: "2026-08-10"
+    version: "1.1.0"
+    updated: "2026-08-14"
     source: core/class-level-fix.md
     description: >
       一個缺陷幾乎從不孤單，它是某個集合的一員。修掉被指出的那一員，
       集合裡其餘的原封不動，而沒有東西會通知你下一個在哪。
       本標準要求修正瞄準集合：指出可窮舉集合，並加上一個「走訪」而非「列舉」該集合的檢查。
+      v1.1.0：新增負向控制的極限聲明（CLF-007：通過一次只證明認得那一個案例，
+      不證明認得該規則的每一種違反）；新增窄涵蓋登記規則（CLF-008，與
+      verification-evidence VE-012 共用：涵蓋缺口須登記到帶到期日的例外清冊，
+      單純揭露不滿足本條）。
 
   iron_law: >
     修一個缺陷之前，先指出它所屬的可窮舉集合，並加上一個走訪該集合的檢查。
@@ -63,6 +67,11 @@ standard:
     granularity: per_subset
     why_per_subset: >
       一道涵蓋五份清單、卻只對第一份測過的檢查，是一道涵蓋一份清單的檢查。
+    limitation: >
+      一次通過的負向控制只證明一個已知壞案例能到達檢查器的失敗路徑，
+      不證明檢查器認得該規則的每一種違反。一道 grep 閘可以 fail-closed 得很完美，
+      卻守著一個拼字而不是一個行為——合成成員證明的是線路接通了，不是那張網夠寬，
+      足以抓住它自稱要抓的東西。
 
   output_requirement:
     must_print: ["實際檢查的數量（分母）", "被排除的數量"]
@@ -82,6 +91,24 @@ standard:
       逐份清冊——一種宣告一道檢查，各自知道自己的基準與條目形狀。
       說出清冊有幾份，並確認每一份都有檢查。
 
+  # ── v1.1.0 窄涵蓋登記規則（B-01 借鑒，與 verification-evidence VE-012 共用同一條要求）──
+  narrow_coverage_registration:
+    description: "當一道閘門的實際涵蓋面窄於它所服務的規則時，只寫一句話揭露是不夠的——揭露必須登記，不能只揭露"
+    why: >
+      散文式揭露很便宜，比擴大涵蓋面便宜得多。每一道被審過一次的窄閘門都會長出一段
+      誠實的文字，然後永遠維持窄下去。揭露本身不換來任何東西；只有配上一個能證明
+      它沒有淪為永久藉口的機制，它才換得到東西。
+    requirement: >
+      任何這一類已記錄的涵蓋缺口，必須同時登記到一份帶到期日的例外清冊——一份獨立於
+      標準本文之外的清單，指名缺口、說明成因、並附上覆核或到期日期。沒有登記到這種
+      清冊裡的揭露，不滿足本條。
+    falsifiable_condition: >
+      若某條目連續兩期清冊審查都未變動，該揭露就已經變成逃生口，本條對該條目失效——
+      不是「部分滿足」，是失效。清冊機制本身（放在哪裡、什麼格式、多久審一次）留給
+      採用它的專案自行決定；本標準要求的是「有這麼一份東西存在，且條目會動」。
+    shared_with: verification-evidence
+    shared_rule_id: VE-012
+
   anti_patterns:
     - pattern: "修掉被回報的那一員就結案"
       why: "集合沒有變；下一個成員會以新事故的形式抵達"
@@ -93,6 +120,8 @@ standard:
       why: "證明的是那一個成員，不是那個類別"
     - pattern: "`✓ all pass` 而沒有分母"
       why: "掃了全部與什麼都沒掃，輸出一模一樣"
+    - pattern: "一句揭露文字，沒有登記到帶到期日的例外清冊"
+      why: "比擴大涵蓋面便宜，而且沒有任何東西逼它改變"
 
   rules:
     - id: CLF-001
@@ -113,6 +142,12 @@ standard:
     - id: CLF-006
       rule: "集合無法走訪時，須記錄理由與解除條件"
       severity: warning
+    - id: CLF-007
+      rule: "宣稱一道類別層檢查『涵蓋』某規則前，須指出檢查辨識的是規則的字面/語法特徵，還是它想守護的行為——通過一次負向控制只證明檢查器認得那一個案例"
+      severity: warning
+    - id: CLF-008
+      rule: "當閘門的實際涵蓋面窄於它所服務的規則時，該缺口必須登記到一份帶到期日的例外清冊，單純寫下揭露文字不滿足本條（與 verification-evidence VE-012 共用）"
+      severity: warning
 
   # 本標準自己沒有自動閘門——依它自己的規則，這件事必須寫下來而不是暗示強制力存在
   enforcement:
@@ -131,7 +166,7 @@ standard:
 
   related:
     - id: verification-evidence
-      relation: "同一族：工具靜默失敗時，其輸出與真結果無從分辨。本標準是同一件事套用在**範圍**而非**執行**上"
+      relation: "同一族：工具靜默失敗時，其輸出與真結果無從分辨。本標準是同一件事套用在**範圍**而非**執行**上；也與本標準共用「窄涵蓋必須登記」規則（VE-012 / CLF-008）"
     - id: anti-hallucination
       relation: "那個防「沒查」；這個防「查了其中一個，卻對全部下結論」"
 

package/bundled/ai/standards/commit-message.ai.yaml

@@ -120,6 +120,8 @@ physical_spec:
 
 enforcement:
   hook_type: PreCommit
+  trigger: UserPromptSubmit
   script_ref: "scripts/hooks/validate-commit-msg.js"
+  hook_script: "scripts/hooks/validate-commit-msg.js"
   severity: error
   timeout_ms: 500