universal-dev-standards 5.16.0 → 6.0.0

package/bundled/locales/zh-TW/skills/workflows/README.md

@@ -0,0 +1,451 @@
+---
+source: skills/workflows/README.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS Workflows
+
+> **語言**: [English](../../../../skills/workflows/README.md) | 繁體中文
+
+**Version**: 1.1.0
+**Last Updated**: 2026-01-21
+**Status**: Experimental
+
+---
+
+## 概觀
+
+UDS Workflows 透過 orchestrate 多個 agent 來完成複雜的開發任務。每個 workflow 定義一連串步驟，其中每個步驟可由 agent 執行，或需要人工介入。
+
+## Workflow YAML 格式
+
+### Schema
+
+```yaml
+name: workflow-name          # Unique identifier (kebab-case)
+version: 1.0.0               # Semantic version
+description: |               # Multi-line description
+  Brief description of the workflow.
+
+# Workflow metadata
+metadata:
+  author: universal-dev-standards
+  category: development       # development | review | testing | documentation
+  difficulty: intermediate    # beginner | intermediate | advanced
+  estimated_steps: 6          # Approximate number of steps
+
+# Prerequisites
+prerequisites:
+  - Project initialized with UDS
+  - Git repository configured
+  - AI tool with Task support (recommended)
+
+# Steps definition
+steps:
+  - id: step-1
+    name: Step Name
+    description: What this step does
+    type: agent               # agent | manual | conditional
+    agent: agent-name         # Required if type=agent
+    inputs:                   # Optional: what this step needs
+      - user_requirements
+    outputs:                  # Optional: what this step produces
+      - analysis_report
+
+  - id: step-2
+    name: Manual Step
+    type: manual
+    description: Human intervention required
+    instructions: |
+      Detailed instructions for the manual step.
+    checklist:
+      - [ ] Item 1
+      - [ ] Item 2
+
+  - id: step-3
+    name: Conditional Step
+    type: conditional
+    condition: analysis_report.has_issues
+    then:
+      agent: reviewer
+      task: Review and fix issues
+    else:
+      skip: true
+
+# Output artifacts
+outputs:
+  - name: final_report
+    description: Generated documentation
+    format: markdown
+```
+
+### RLM Context 設定 (v1.1.0)
+
+Workflow 可納入受 RLM 啟發的 context 處理機制，以因應大型程式庫：
+
+```yaml
+# === RLM CONTEXT CONFIGURATION ===
+context-strategy:
+  enable-rlm: true                    # Enable RLM-aware processing
+  max-context-per-step: 100000        # Maximum tokens per step
+  context-inheritance: selective      # full | selective | summary
+
+steps:
+  - id: parallel-analysis
+    type: parallel-agents             # NEW: Execute agent on multiple inputs
+    agent: code-architect
+    foreach: ${modules}               # Dynamic iteration variable
+    context-mode: focused             # minimal | focused | full
+    merge-strategy: aggregate         # aggregate | sequential | summary
+    outputs: [analysis_results]
+```
+
+#### Context 繼承模式
+
+| 模式 | 說明 | 使用情境 |
+|------|-------------|----------|
+| `full` | 將所有先前的 output 傳遞給下一個步驟 | 循序分析 |
+| `selective` | 僅傳遞指定的 output | 記憶體效率高的 pipeline |
+| `summary` | 傳遞 output 的摘要版本 | 大規模處理 |
+
+#### 步驟的 Context 模式
+
+| 模式 | 說明 | Token 用量 |
+|------|-------------|-------------|
+| `minimal` | 僅必要的 context | 低 |
+| `focused` | 與目前項目相關的 context | 中 |
+| `full` | 完整可用的 context | 高 |
+
+#### 平行結果的 Merge 策略
+
+| 策略 | 說明 | Output 格式 |
+|----------|-------------|---------------|
+| `aggregate` | 將所有結果合併為陣列 | 結果陣列 |
+| `sequential` | 維持處理順序 | 有序清單 |
+| `summary` | AI 產生的所有結果摘要 | 單一摘要 |
+
+### 步驟類型
+
+| 類型 | 說明 | 執行方式 |
+|------|-------------|-----------|
+| `agent` | 由 UDS agent 執行 | 自動 |
+| `manual` | 需要人工介入 | 互動式 |
+| `conditional` | 依條件分支 | 視條件而定 |
+| `parallel-agents` | 對多個輸入並行執行 agent | 平行 (v1.1.0) |
+
+#### Parallel-Agents 步驟設定 (v1.1.0)
+
+```yaml
+- id: parallel-module-analysis
+  name: Analyze Modules in Parallel
+  type: parallel-agents
+  agent: code-architect
+  foreach: ${modules}           # Variable containing items to iterate
+  context-mode: focused         # minimal | focused | full
+  merge-strategy: aggregate     # How to combine results
+  max-concurrent: 3             # Optional: limit concurrent executions
+  timeout: 300                  # Optional: timeout per item (seconds)
+  inputs:                       # Optional: additional inputs
+    - project_context
+  outputs:
+    - module_analysis_results
+```
+
+## 內建 Workflows
+
+| Workflow | 步驟數 | 說明 |
+|----------|-------|-------------|
+| [integrated-flow](../../../../skills/workflows/integrated-flow.workflow.yaml) | 8 | 完整的 ATDD → SDD → BDD → TDD 循環 |
+| [feature-dev](../../../../skills/workflows/feature-dev.workflow.yaml) | 6 | 功能開發 workflow |
+| [code-review](../../../../skills/workflows/code-review.workflow.yaml) | 4 | 全面性 code review workflow |
+| [large-codebase-analysis](../../../../skills/workflows/large-codebase-analysis.workflow.yaml) | 4 | 針對 50+ 檔案專案的 RLM 強化 workflow |
+
+## 用法
+
+### CLI 安裝
+
+```bash
+# List available workflows
+uds workflow list
+
+# Install specific workflow
+uds workflow install integrated-flow
+
+# Install all workflows
+uds workflow install --all
+```
+
+### 執行
+
+Workflow 採逐步執行。對於支援 Task tool 的工具（Claude Code、OpenCode）：
+
+```
+User: Start the integrated-flow workflow for user authentication
+
+AI: Starting Integrated Development Flow...
+
+Step 1/8: Specification Workshop (spec-analyst)
+[Agent executes analysis...]
+
+Step 2/8: Spec Proposal (spec-analyst)
+[Agent drafts proposal...]
+
+Step 3/8: Spec Review (manual)
+Please review the specification:
+- [ ] Requirements are clear
+- [ ] Acceptance criteria defined
+- [ ] Risks identified
+
+[User confirms...]
+
+Step 4/8: Discovery (test-specialist)
+[Agent identifies test scenarios...]
+
+...continues...
+```
+
+### 不支援 Task 的工具
+
+Workflow 會轉換為引導式檢查清單：
+
+```markdown
+## Integrated Development Flow
+
+### Step 1: Specification Workshop
+**Agent**: spec-analyst
+**Task**: Analyze requirements and identify acceptance criteria
+
+[Copy this to your AI assistant]
+
+### Step 2: Spec Proposal
+...
+```
+
+## 建立自訂 Workflow
+
+### 1. 建立 Workflow 檔案
+
+```bash
+mkdir -p .claude/workflows
+touch .claude/workflows/my-workflow.workflow.yaml
+```
+
+### 2. 定義 Workflow
+
+```yaml
+name: my-custom-workflow
+version: 1.0.0
+description: Custom workflow for my project
+
+steps:
+  - id: analyze
+    name: Analyze Requirements
+    type: agent
+    agent: spec-analyst
+    outputs: [requirements_doc]
+
+  - id: implement
+    name: Implementation
+    type: manual
+    description: Implement based on analysis
+
+  - id: review
+    name: Code Review
+    type: agent
+    agent: reviewer
+    inputs: [code_changes]
+```
+
+## Workflow vs Agent vs Skill
+
+| 面向 | Workflow | Agent | Skill |
+|--------|----------|-------|-------|
+| **目的** | orchestrate 多步驟流程 | 執行自主任務 | 提供知識／context |
+| **組成** | 包含多個 agent | 使用 skill 作為 context | 獨立運作 |
+| **狀態** | 追蹤跨步驟的進度 | 單一任務狀態 | 無狀態 |
+| **使用者參與** | 可包含人工步驟 | 最少 | 無 |
+
+## 以 Wave 為基礎的平行執行 (v1.2.0)
+
+Workflow 中的步驟可分組為 **wave** 以進行平行執行。同一 wave 中的步驟彼此獨立，可由不同的 sub-agent 並行執行。Wave 之間循序執行——wave N 中的所有步驟都必須完成，wave N+1 才會開始。
+
+### Wave 設定
+
+```yaml
+steps:
+  # Wave 1: Independent analysis steps (run in parallel)
+  - id: analyze-requirements
+    name: Analyze Requirements
+    type: agent
+    agent: spec-analyst
+    wave: 1
+    outputs: [requirements_analysis]
+
+  - id: analyze-architecture
+    name: Analyze Architecture
+    type: agent
+    agent: code-architect
+    wave: 1
+    outputs: [architecture_analysis]
+
+  # Wave 2: Depends on wave 1 outputs (barrier point)
+  - id: design
+    name: Design Solution
+    type: agent
+    agent: code-architect
+    wave: 2
+    inputs: [requirements_analysis, architecture_analysis]
+    outputs: [design_doc]
+
+  # Manual steps are automatic barrier points
+  - id: review
+    name: Review Design
+    type: manual
+    wave: 3
+```
+
+### Wave 規則
+
+| 規則 | 說明 |
+|------|-------------|
+| **獨立性** | 同一 wave 中的步驟不得彼此相依 |
+| **Barrier** | wave N 中的所有步驟必須完成，wave N+1 才會開始 |
+| **Manual barrier** | `manual` 類型步驟為自動 barrier 點 |
+| **選填欄位** | `wave` 欄位為選填；若未指定，步驟將循序執行 |
+| **向後相容** | 沒有 wave 欄位的 workflow 仍如以往運作 |
+
+---
+
+## 步驟驗證 Pipeline (v1.2.0)
+
+每個 workflow 步驟可包含兩層驗證，靈感來自 CrewAI 的驗證 pipeline 與 DSPy 的 metric 函式。
+
+### 兩層驗證
+
+```yaml
+steps:
+  - id: generate-spec
+    name: Generate Specification
+    type: agent
+    agent: spec-analyst
+    outputs: [spec_document]
+    validation:
+      # Layer 1: Deterministic (always runs first)
+      deterministic:
+        - check: file_exists
+          path: "docs/specs/{{spec_id}}.md"
+        - check: contains_sections
+          sections: [Summary, Motivation, "Acceptance Criteria"]
+        - check: ac_format
+          pattern: "Given .+, When .+, Then .+"
+
+      # Layer 2: Semantic (only runs if Layer 1 passes)
+      semantic:
+        - check: consistency
+          description: AC covers all requirements mentioned in Motivation
+        - check: completeness
+          description: No TODO or placeholder sections remain
+```
+
+### 驗證規則
+
+| Layer | 類型 | 執行時機 | 失敗時 |
+|-------|------|-------------|------------|
+| **Layer 1** | Deterministic | 永遠最先執行 | 立即停止，顯示修正選項 |
+| **Layer 2** | Semantic | Layer 1 通過後 | 警告，建議改善 |
+
+**Fail-fast 原則**：若 deterministic 驗證失敗，semantic 檢查將完全跳過。這可避免在根本上已損壞的 output 上浪費時間進行品質評估。
+
+---
+
+## Agent Communication Protocol (v1.2.0)
+
+定義 agent 在 workflow 內如何交換資料。
+
+### 三個通訊層
+
+| Layer | 機制 | 說明 |
+|-------|-----------|-------------|
+| **Artifact passing** | 以檔案為基礎 | 步驟產生檔案作為 output；下游步驟透過檔案路徑讀取 |
+| **Reducer patterns** | append / replace / merge | 多個 output 如何合併 |
+| **Context isolation** | 每步驟乾淨啟動 | 每個 agent 步驟以乾淨 context 啟動，僅接收指定的 input |
+
+### Reducer 模式
+
+```yaml
+steps:
+  - id: collect-reviews
+    type: parallel-agents
+    agent: reviewer
+    foreach: ${modules}
+    outputs: [review_results]
+    reducer: append        # Collect all results into array
+
+  - id: merge-configs
+    type: agent
+    agent: code-architect
+    inputs: [review_results]
+    reducer: merge         # Deep merge results into single object
+```
+
+| 模式 | 說明 | 使用情境 |
+|---------|-------------|----------|
+| `append` | 將所有結果收集為有序清單 | 平行 review、多模組分析 |
+| `replace` | 後到的 output 覆寫先前的 | Config 覆寫、最新者勝 |
+| `merge` | 將結果深度合併為單一物件 | 結合部分分析 |
+
+### Context Isolation
+
+每個 agent 步驟以**乾淨 context** 啟動，僅包含：
+1. 該步驟宣告的 `inputs`（來自前一步驟的 output）
+2. 該 agent 的 skill（來自 AGENT.md 的 `skills` 欄位）
+3. Workflow 共享的 `prerequisites`
+
+這可防止 context 污染，並確保 agent 行為可重現。
+
+---
+
+## 最佳實踐
+
+### 該做的
+
+- 將複雜任務拆解為離散步驟
+- 為關鍵決策納入人工檢查點
+- 為每個步驟定義清楚的 input／output
+- 使用 conditional 步驟進行錯誤處理
+- 清楚記錄 prerequisites
+
+### 不該做的
+
+- 不要建立過長的 workflow（>10 步驟）
+- 不要跳過 review／verification 步驟
+- 不要假設所有工具都支援自動執行
+- 不要把步驟切得太細
+
+---
+
+## 相關資源
+
+- [Agents 文件](../agents/README.md)
+- [Skills 文件](../README.md)
+- [方法論系統](../dev-methodology/SKILL.md)
+
+---
+
+## 版本歷史
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.2.0 | 2026-03-17 | Added wave-based parallel execution, step validation pipeline, agent communication protocol |
+| 1.1.0 | 2026-01-21 | Added RLM context configuration, parallel-agents step type, large-codebase-analysis workflow |
+| 1.0.0 | 2026-01-20 | Initial release |
+
+---
+
+## License
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/README.md

@@ -32,7 +32,7 @@ These skills provide standard guidance and workflows. They can be accessed via s
 | `guide` | `/guide` | [UDS] Access all standard guides |
 | `checkin-assistant` | `/checkin` | [UDS] Pre-commit quality gates |
 | `commit-standards` | `/commit` | [UDS] Conventional Commits format |
-| `code-review-assistant` | `/review` | [UDS] Systematic code review |
+| `code-review-assistant` | `/code-review` | [UDS] Systematic code review |
 | `tdd-assistant` | `/tdd` | [UDS] Test-Driven Development |
 | `bdd-assistant` | `/bdd` | [UDS] Behavior-Driven Development |
 | `atdd-assistant` | `/atdd` | [UDS] Acceptance Test-Driven Development |

package/bundled/skills/ac-coverage/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ac-coverage
 scope: universal
+anchor_standard: acceptance-criteria-traceability
 description: "[UDS] Analyze AC-to-test traceability and coverage"
 allowed-tools: Read, Grep, Glob
 argument-hint: "[spec file path | 規格檔案路徑]"
@@ -8,6 +9,12 @@ argument-hint: "[spec file path | 規格檔案路徑]"
 
 # AC Coverage Assistant | AC 覆蓋率助手
 
+**Version**: 1.1.0
+**Last Updated**: 2026-06-19
+**Applicability**: Claude Code Skills
+
+> **Core Standard**: This skill implements [Acceptance Criteria Traceability Standards](../../core/acceptance-criteria-traceability.md). For the authoritative methodology, refer to the core standard.
+
 Analyze Acceptance Criteria (AC) to test traceability and generate coverage reports.
 
 分析驗收條件（AC）與測試之間的追蹤關係，並產生覆蓋率報告。
@@ -24,7 +31,7 @@ Analyze Acceptance Criteria (AC) to test traceability and generate coverage repo
 ## Workflow | 工作流程
 
 1. **Parse SPEC** — Extract AC definitions (AC-1, AC-2, ...) from the specification file
-2. **Scan Tests** — Search test files for `@AC` and `@SPEC` annotations using standard linking conventions
+2. **Scan Tests** — Search test files for the **canonical annotation** `@SPEC-<id> @AC-<n>` (a single combined tag)
 3. **Build Matrix** — Map each AC to its test references (file, test name, line)
 4. **Classify Status** — Mark each AC as ✅ covered, ⚠️ partial, or ❌ uncovered
 5. **Calculate Coverage** — Apply formula: `Coverage % = (covered + partial × 0.5) / total × 100`
@@ -32,13 +39,17 @@ Analyze Acceptance Criteria (AC) to test traceability and generate coverage repo
 
 ## Linking Convention | 標註慣例
 
-Tests MUST reference their source AC using standard annotations:
+Tests MUST reference their source AC using the **canonical annotation**:
+`@SPEC-<id> @AC-<n>` — a single combined tag, e.g. `@SPEC-001 @AC-1`. Keeping the
+attribution on **one line** is what forward-derivation and test-runner tag
+filters consume. **Do not** split it into separate `@AC` / `@SPEC` lines.
+
+使用**標準合併標註** `@SPEC-<id> @AC-<n>`（單一合併標籤），保持同一行；**勿**拆成 `@AC` / `@SPEC` 兩行。
 
 ```typescript
 // TypeScript/JavaScript
 describe('AC-1: User login with valid credentials', () => {
-  // @AC AC-1
-  // @SPEC SPEC-001
+  // @SPEC-001 @AC-1
   it('should redirect to dashboard on successful login', () => { ... });
 });
 ```
@@ -47,8 +58,7 @@ describe('AC-1: User login with valid credentials', () => {
 # Python
 class TestAC1_UserLogin:
     """AC-1: User login with valid credentials
-    @AC AC-1
-    @SPEC SPEC-001
+    @SPEC-001 @AC-1
     """
     def test_redirect_to_dashboard(self): ...
 ```
@@ -81,7 +91,7 @@ Use `--full` flag to extend from 2-layer (AC→Test) to 4-layer traceability.
 Layer 0: Requirement / User Story (REQ)
     ↓ (defines)
 Layer 1: Acceptance Criteria (AC)
-    ↓ (@AC annotations)
+    ↓ (@SPEC-NNN @AC-N annotations)
 Layer 2: Test Cases
     ↓ (covers)
 Layer 3: Source Code (@implements)

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

@@ -139,7 +139,7 @@ docs/adr/
 | Skill | Integration | 整合方式 |
 |-------|-------------|---------|
 | `/sdd` | Reference ADRs in Technical Design; suggest creating ADR for major decisions | 在技術設計中引用 ADR |
-| `/review` | Reference ADRs as design rationale during code review | 程式碼審查時引用 ADR |
+| `/code-review` | Reference ADRs as design rationale during code review | 程式碼審查時引用 ADR |
 | `/commit` | Include `ADR-NNN` in commit footer for traceability | 提交時在 footer 加入 ADR 編號 |
 | `/brainstorm` | Feed brainstorm output into ADR option analysis | 腦力激盪結果作為 ADR 選項分析輸入 |
 

package/bundled/skills/agents/code-architect.md

@@ -57,7 +57,7 @@ triggers:
 
 # Code Architect Agent
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/code-architect.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/code-architect.md) | [简体中文](../../locales/zh-CN/skills/agents/code-architect.md)
 
 ## Purpose
 

package/bundled/skills/agents/doc-writer.md

@@ -55,7 +55,7 @@ triggers:
 
 # Documentation Writer Agent
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/doc-writer.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/doc-writer.md) | [简体中文](../../locales/zh-CN/skills/agents/doc-writer.md)
 
 ## Purpose
 

package/bundled/skills/agents/reviewer.md

@@ -50,12 +50,12 @@ triggers:
     - 程式碼審查
     - 審查
   commands:
-    - /review
+    - /code-review
 ---
 
 # Code Reviewer Agent
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/reviewer.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/reviewer.md) | [简体中文](../../locales/zh-CN/skills/agents/reviewer.md)
 
 ## Purpose
 

package/bundled/skills/agents/spec-analyst.md

@@ -86,7 +86,7 @@ triggers:
 
 # Specification Analyst Agent
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/spec-analyst.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/spec-analyst.md) | [简体中文](../../locales/zh-CN/skills/agents/spec-analyst.md)
 
 ## Purpose
 

package/bundled/skills/agents/test-specialist.md

@@ -57,7 +57,7 @@ triggers:
 
 # Test Specialist Agent
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/test-specialist.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/test-specialist.md) | [简体中文](../../locales/zh-CN/skills/agents/test-specialist.md)
 
 ## Purpose
 

package/bundled/skills/ai-collaboration-standards/SKILL.md

@@ -190,9 +190,9 @@ This project uses **English** certainty tags.
 After `/ai-collaboration` completes, the AI assistant should suggest:
 
 > **AI 協作行為規範已掌握。建議下一步 / AI collaboration behavior standards understood. Suggested next steps:**
-> - 執行 `/ai-instructions` 建立或更新 CLAUDE.md 等 AI 指令檔案 ⭐ **Recommended / 推薦** — 將協作標準寫入專案配置 / Write collaboration standards into project configuration
+> - 執行 `/ai-instruction-standards` 建立或更新 CLAUDE.md 等 AI 指令檔案 ⭐ **Recommended / 推薦** — 將協作標準寫入專案配置 / Write collaboration standards into project configuration
 > - 執行 `/ai-friendly-architecture` 設計 AI 友善架構 — 從長期架構層面優化 AI 協作 / Optimize AI collaboration at the architecture level
-> - 執行 `/review` 運用確定性標籤進行程式碼審查 — 實踐基於證據的分析 / Practice evidence-based analysis
+> - 執行 `/code-review` 運用確定性標籤進行程式碼審查 — 實踐基於證據的分析 / Practice evidence-based analysis
 
 ---
 

package/bundled/skills/ai-friendly-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ai-friendly-architecture
-scope: uds-specific
+scope: universal
 description: |
   Design AI-friendly architecture with explicit patterns, layered documentation, and semantic boundaries.
   Use when: structuring projects for AI collaboration, optimizing codebase for AI analysis, setting up AI context.
@@ -210,7 +210,7 @@ After `/ai-friendly-architecture` completes, the AI assistant should suggest:
 > **AI 友善架構指南已掌握。建議下一步 / AI-friendly architecture guide understood. Suggested next steps:**
 > - 執行 `/sdd` 將 AI 友善架構設計納入正式規格 ⭐ **Recommended / 推薦** — 確保架構決策有規格追蹤 / Ensure architecture decisions are tracked in specs
 > - 建立 `.ai-context.yaml` 和 `QUICK-REF.md` — 立即實作 AI 友善結構 / Implement AI-friendly structure immediately
-> - 執行 `/ai-instructions` 更新 CLAUDE.md 以反映架構配置 — 讓 AI 指令檔案與架構保持同步 / Keep AI instruction files in sync with architecture
+> - 執行 `/ai-instruction-standards` 更新 CLAUDE.md 以反映架構配置 — 讓 AI 指令檔案與架構保持同步 / Keep AI instruction files in sync with architecture
 
 ---
 

package/bundled/skills/ai-instruction-standards/SKILL.md

@@ -291,7 +291,7 @@ If no AI instruction file found:
 
 ## Next Steps Guidance
 
-After `/ai-instructions` completes, suggest:
+After `/ai-instruction-standards` completes, suggest:
 
 > - Create or update project's `CLAUDE.md` / `AGENTS.md` ⭐ **Recommended** — Apply standards immediately
 > - Run `/ai-friendly-architecture` to optimize AI collaboration at the architecture level

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

@@ -4,6 +4,7 @@ scope: partial
 description: "[UDS] Guide through Acceptance Test-Driven Development workflow"
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[feature or spec | 功能或規格]"
+status: reference
 ---
 <!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
   ATDD lifecycle orchestration (5-phase: WORKSHOP→DISTILLATION→DEVELOPMENT→DEMO→DONE,
@@ -15,6 +16,9 @@ argument-hint: "[feature or spec | 功能或規格]"
 
 # ATDD Assistant | ATDD 助手
 
+> ⚠️ **Status: Reference（參考用，非可執行流程）** — 5 階段 ATDD 生命週期協調（WORKSHOP→DISTILLATION→DEVELOPMENT→DEMO→DONE、INVEST 驗證、AC→Gherkin 轉換、RED/GREEN 執行、PO sign-off gates）已於 2026-04-28 移至 **adoption layer（XSPEC-095）**。此處保留 INVEST 準則、ATDD 循環圖、Gherkin AC 格式、Three Amigos 結構供參考。
+> Lifecycle orchestration has moved to the adoption layer (XSPEC-095); this document is **reference-only**. For enforced execution, use your adoption layer's toolchain.
+
 Guide through the Acceptance Test-Driven Development (ATDD) workflow for defining and validating user stories.
 
 引導驗收測試驅動開發（ATDD）流程，用於定義和驗證使用者故事。
@@ -30,6 +34,9 @@ WORKSHOP ──► DISTILLATION ──► DEVELOPMENT ──► DEMO ──► D
 
 ## Workflow | 工作流程
 
+> 📖 以下為流程的**參考結構**，非可執行步驟；自動化／強制執行請用 adoption layer 工具鏈（XSPEC-095）。
+> The steps below are a **reference structure**, not an executable workflow.
+
 ### 1. WORKSHOP - Define AC | 定義驗收條件
 PO presents user story, team asks clarifying questions, define acceptance criteria together.
 

package/bundled/skills/atdd-assistant/acceptance-criteria-guide.md

@@ -388,7 +388,7 @@ And my original discount should remain
 Becomes:
 
 ```gherkin
-@AC-1
+@SPEC-001 @AC-1
 Scenario: Successful password reset
   Given I have a registered account with email "user@example.com"
   When I request a password reset for "user@example.com"