skills/analyze-prd/README.zh-TW.md

@@ -0,0 +1,39 @@
+# 分析 PRD (Analyze PRD) 技能指南
+
+## 概述
+`analyze-prd` 是 Architect Pipeline 的第一個步驟，用來從 PRD 中提取架構需求、識別相關知識領域、標記模糊之處。此技能只做分析，不做設計，產出為內部分析而非檔案。
+
+## 輸入與輸出
+### 輸入
+- `docs/prd/{feature}.md`
+
+### 輸出
+- 無檔案產出，僅供內部分析使用
+
+## 運作方式
+1. 完整閱讀 PRD
+2. 檢查現有 codebase 架構
+3. 提取功能性需求及其架構影響
+4. 提取非功能性需求及其架構影響
+5. 識別 13 個相關知識領域
+6. 識別所需的可交付技能
+7. 標記阻擋設計決策的模糊之處
+8. 將需求對應到 18 個架構輸出章節
+
+## 分析重點
+- 每個 PRD 需求是否都有對應的架構元件
+- 每個 NFR 是否都有對應的架構決策
+- 哪些知識領域與此功能相關
+- 哪些可交付技能需要被引用
+
+## 下游用途
+- 分析結果供 `design-architecture` 使用
+- 知識領域對應供 `design-architecture` 參考知識合約
+- 識別的模糊之處需先與 PM 澄清才能進入設計
+
+## 不應做的事
+- 不做架構設計
+- 不做技術選型
+- 不定義 API 合約、資料表或服務邊界
+- 不寫架構決策
+- 不產生任何檔案

skills/api-contract-design/README.zh-TW.md

@@ -0,0 +1,26 @@
+# API 合約設計 (API Contract Design) 知識合約指南
+
+## 概述
+`api-contract-design` 是知識合約，不是 workflow 技能。用來定義 API 合約的設計原則，包含請求/回應結構、狀態碼、分頁機制、認證邊界與冪等性行為。供 `design-architecture` 在定義 API 時參考。
+
+## 核心原則
+- API 是生產者與消費者之間的合約，穩定性與清晰度至關重要
+- 每個端點必須服務至少一個 PRD 功能需求
+- 合約必須明確、完整且無歧義
+- 破壞性變更必須避免；必須規劃版本管理
+
+## 設計重點
+- REST API：端點定義、請求結構、回應結構、狀態碼、分頁、過濾
+- 非 REST API：GraphQL schema、gRPC service 定義、WebSocket 訊息格式
+- 錯誤回應格式：一致的錯誤碼、機器可讀與人類可讀的訊息
+- 版本策略：URL path versioning 與 header versioning 的適用場景
+
+## 知識合約職責
+- 提供 API 設計的理論指引
+- 不直接產生 API 規格（由 `generate_openapi_spec` 負責格式）
+- 與 `generate_openapi_spec` 搭配使用：前者提供原則，後者提供格式
+
+## 不應做的事
+- 不產生 API 規格檔案
+- 不替特定端點命名或定義結構（那是 `design-architecture` 的職責）
+- 不做最終技術選型

skills/architecture-patterns/README.zh-TW.md

@@ -0,0 +1,28 @@
+# 架構模式 (Architecture Patterns) 知識合約指南
+
+## 概述
+`architecture-patterns` 是知識合約，用來提供架構模式選擇的原則與取決框架。涵蓋 Modular Monolith、Microservices、Layered、Clean、Hexagonal、Event-Driven、CQRS、Saga、Outbox 等模式。供 `design-architecture` 在選擇架構模式時參考。
+
+## 核心原則
+選擇模式唯一的原因是它解決了 PRD 中實際存在的問題。不要因為時尚或覺得以後可能需要就採用模式。
+
+## 模式選項
+- **Modular Monolith**：單一部署單元，內部有明確模組邊界
+- **Microservices**：多個獨立部署服務，每個職責單一
+- **Layered Architecture**：水平分層（展示層、業務層、資料層）
+- **Clean Architecture**：以用例為中心，依賴反轉
+- **Hexagonal Architecture**：透過埠與轉接器隔離商業邏輯
+- **Event-Driven**：透過事件而非直接呼叫溝通
+- **CQRS**：讀取模型與寫入模型分離
+- **Saga Pattern**：跨服務分散式交易的補償機制
+- **Outbox Pattern**：可靠事件發布的確保機制
+
+## 知識合約職責
+- 提供各模式的 Use When / Avoid When 判斷原則
+- 說明各模式的 Trade-offs
+- 不替 PRD 做最終模式選擇
+
+## 不應做的事
+- 不替系統選擇特定模式
+- 不提供具體實作建議
+- 不產生任何架構產出

skills/architecture-research/README.zh-TW.md

@@ -0,0 +1,39 @@
+# 架構研究 (Architecture Research) 技能指南
+
+## 概述
+`architecture-research` 是可選的前置工作，用來在嚴格 Architect Pipeline 開始前調查技術環境、現有系統限制與可比較架構。此技能只做研究，不做設計，產出為內部分析而非檔案。
+
+## 輸入與輸出
+### 輸入
+- `docs/prd/{feature}.md`
+
+### 輸出
+- 無檔案產出，僅供內部分析使用
+
+## 界線：研究 vs 設計
+此技能嚴格限定為**研究**。它只能：
+- **彙編限制**：現有系統限制、服務邊界、資料流、技術棧、整合依賴
+- **列出選項**：可用技術選項、架構模式及其取捨
+- **呈現取捨**：候選方案的優缺點，不做最終選擇
+
+此技能**嚴禁**：
+- 做最終架構決策
+- 選擇技術棧
+- 定義服務邊界
+- 定義 API 合約或資料模型
+- 寫 ADR
+- 推薦單一方案
+
+界線很簡單：**研究彙編可能選項；設計決定我們建什麼。**
+
+## 研究重點
+- 現有 codebase 架構
+- 系統限制：延遲需求、規模預期、合規需求
+- 可比較系統架構
+- 技術選項的取捨
+
+## 不應做的事
+- 不做架構設計
+- 不做技術選型
+- 不做最終架構決策
+- 不產生任何檔案

skills/async-queue-design/README.zh-TW.md

@@ -0,0 +1,23 @@
+# 非同步與佇列設計 (Async Queue Design) 知識合約指南
+
+## 概述
+`async-queue-design` 是知識合約，用來設計非同步工作流程、佇列主題、生產者、消費者、重試策略、DLQ、排序保證與逾時行為。供 `design-architecture` 在設計非同步模型時參考。
+
+## 核心原則
+非同步處理必須有 PRD 需求支撐。不要因為非同步「比較好」或「更有擴展性」就採用。每個非同步決策必須可追溯到特定 PRD 功能需求或 NFR。
+
+## 設計重點
+- **何時用非同步**：長時運行操作、PRD 要求非同步、多個消費者需反應同一事件、吞吐量需求超過同步處理能力
+- **佇列/主題設計**：Topic vs Queue 的選擇、訊息結構、排序保證、持久性保證
+- **重試策略**：最大重試次數、退避策略（Fixed、Exponential、Exponential with Jitter）、重試預算
+- **DLQ 策略**：何時路由到 DLQ、DLQ 訊息保留、監控與警報
+- **逾時與取消**：處理逾時的定義、取消訊號機制
+
+## 知識合約職責
+- 提供非同步設計的理論指引
+- 不直接產生非同步流程規格（由 `design-architecture` 的 Async / Queue Design 章節負責）
+
+## 不應做的事
+- 不替系統選擇特定訊息代理
+- 不定義具體的佇列名稱或主題名稱
+- 不產生實作程式碼

skills/challenge-architecture/README.zh-TW.md

@@ -0,0 +1,52 @@
+# 架構挑戰 (Challenge Architecture) 技能指南
+
+## 概述
+`challenge-architecture` 是 Architect Pipeline 的第三個步驟，用來對架構決策做高強度審查、驗證 PRD 可追溯性、偵測過度設計與不足設計。此技能以安靜的批次審計模式運作，不會互動式提問。
+
+## 輸入與輸出
+### 輸入
+- `docs/architecture/{feature}.md`
+- `docs/prd/{feature}.md`
+
+### 輸出
+- 更新後的 `docs/architecture/{feature}.md`
+
+## 審計模式
+此技能以**安靜審計 / 批次審查**模式運作：
+- 完整閱讀 PRD 與架構文件
+- 安靜執行所有驗證階段
+- 產出單一結構化審查報告
+- 直接將所有修補套用到架構文件
+- 不會一次問一個問題或互動式提示
+
+## 審計階段
+1. **可追溯性**：每個架構元素是否回溯到 PRD 需求
+2. **覆蓋度**：每個 PRD 需求是否有架構對應
+3. **擴展性**：服務是否能獨立擴展、是否有單點失敗
+4. **一致性**：一致性模型是否明確、Race condition 是否識別
+5. **安全性**：認證/授權邊界是否定義
+6. **整合**：外部系統整合是否識別、失敗模式是否定義
+7. **可觀測性**：Logs、Metrics、Traces 是否完整
+8. **資料完整性**：資料是否可能遺失、交易邊界是否合適
+9. **過度設計偵測**：過於複雜的架構決策
+10. **不足設計偵測**：遺漏的需求對應
+
+## 審查輸出格式
+- Traceability Gaps
+- Missing Decisions
+- Over-Engineering
+- Under-Engineering
+- Risks
+- Required Revisions
+
+## 閘道決策
+- **PASS**：所有修補已套用，無剩餘阻擋
+- **CONDITIONAL PASS**：存在不阻擋 Planner 交接的小缺口
+- **FAIL**：需要重大修訂，需回到 `design-architecture`
+
+## 不應做的事
+- 不以互動方式提問
+- 不改變 PRD 範圍
+- 不從頭設計架構
+- 不做實作層級決策
+- 不拆分任務

skills/consistency-transaction-design/README.zh-TW.md

@@ -0,0 +1,34 @@
+# 一致性與交易設計 (Consistency Transaction Design) 知識合約指南
+
+## 概述
+`consistency-transaction-design` 是知識合約，用來提供一致性与交易設計的原則與模式。涵蓋 Strong vs Eventual Consistency、Idempotency、Deduplication、Retry、Outbox Pattern、Saga 與 Compensation。供 `design-architecture` 在定義一致性模型時參考。此合約取代了原有的 `idempotency-design`。
+
+## 核心原則
+### CAP Theorem
+- Consistency：每次讀取都獲得最新寫入或錯誤
+- Availability：每個請求都獲得回應（不保證是最新寫入）
+- Partition tolerance：網路分割時系統仍可運作
+- 三者無法同時滿足，根據業務需求選擇。
+
+### 一致性光譜
+- **Strong Consistency**：讀取永遠返回最新寫入
+- **Eventual Consistency**：讀取可能返回過時資料，最終收斂
+- **Session Consistency**：同一 session 內讀取看到自己的寫入
+- **Causal Consistency**：讀取遵守因果順序
+
+## 設計重點
+- **一致性模型選擇**：按資料域選擇，而非按系統選擇
+- **Idempotency 設計**：何時需要、Key 策略、TTL、儲存位置
+- **Deduplication**：Idempotency key、Content hash、Sequence number
+- **Retry**：Fixed interval、Exponential backoff、Circuit breaker
+- **Outbox Pattern**：確保可靠事件發布
+- **Saga Pattern**：跨服務分散式交易的補償機制（Choreography vs Orchestration）
+
+## 知識合約職責
+- 提供一致性與交易設計的理論指引
+- 不直接產生一致性模型規格（由 `design-architecture` 的 Consistency Model 章節負責）
+
+## 不應做的事
+- 不替系統選擇特定一致性策略
+- 不定義具體的 Idempotency key 格式或 TTL
+- 不產生實作程式碼

skills/data-modeling/README.zh-TW.md

@@ -0,0 +1,28 @@
+# 資料建模 (Data Modeling) 知識合約指南
+
+## 概述
+`data-modeling` 是知識合約，用來定義資料庫結構、分區鍵、索引、查詢模式、反正規化策略、TTL/快取與資料所有權。供 `design-architecture` 在設計資料模型時參考。
+
+## 核心原則
+- 資料模型必須由查詢與寫入模式驅動，而非理論純度
+- 每個資料表必須有明確目的，可追溯到 PRD 需求
+- 索引必須有明確的查詢模式支撐
+- 資料所有權必須明確：每筆資料只屬於一個服務
+
+## 設計重點
+- **資料表定義**：資料表名稱、目的、欄位定義、主鍵、外鍵關係
+- **索引設計**：索引必須有查詢模式支撐，避免 speculation 索引
+- **分區鍵**：分散式資料儲存的分區鍵選擇、熱分割風險
+- **關係**：One-to-one、One-to-many、Many-to-many，(含義與 cascade 行為)
+- **反正規化策略**：何時反正規化、資料同步機制、過時容忍度
+- **TTL 與快取**：Ephemeral 資料的 TTL、快取類型與失效策略
+- **資料所有權**：每筆資料的唯一擁有服務、其他服務透過 API 或事件存取
+
+## 知識合約職責
+- 提供資料建模的理論指引
+- 不直接產生資料庫結構定義（由 `design_database_schema` 負責格式）
+
+## 不應做的事
+- 不替特定資料庫選擇資料表名稱或欄位
+- 不定義具體的索引名稱或類型
+- 不產生 Schema 檔案

skills/design-architecture/README.zh-TW.md

@@ -0,0 +1,54 @@
+# 設計架構 (Design Architecture) 技能指南
+
+## 概述
+`design-architecture` 是 Architect Pipeline 的核心步驟，用來基於 PRD 需求設計完整系統架構，產出單一嚴格輸出檔案 `docs/architecture/{feature}.md`。
+
+## 輸入與輸出
+### 輸入
+- `docs/prd/{feature}.md`
+
+### 輸出
+- `docs/architecture/{feature}.md`（唯一檔案，所有交付物必須嵌入此檔案）
+
+## 必備章節（18 個）
+1. Overview
+2. System Architecture
+3. Service Boundaries
+4. Data Flow
+5. Database Schema
+6. API Contract
+7. Async / Queue Design
+8. Consistency Model
+9. Error Model
+10. Security Boundaries
+11. Integration Boundaries
+12. Observability
+13. Scaling Strategy
+14. Non-Functional Requirements
+15. Mermaid Diagrams
+16. ADR
+17. Risks
+18. Open Questions
+
+## 設計原則
+1. **High Availability** — 設計容錯與復原力，勝過完美一致性
+2. **Scalability** — 設計水平擴展，勝過垂直擴展
+3. **Stateless First** — 偏好無狀態服務，外部化狀態到資料庫或快取
+4. **API First** — 先定義合約再實作，API 是主要介面
+5. **Event Driven First** — 偏好事件驅動溝通
+6. **Async First** — 偏好非同步處理
+
+## 知識合約與可交付技能引用
+- **知識合約**：13 個（system-decomposition、api-contract-design、data-modeling、distributed-system-basics、architecture-patterns、storage-knowledge、async-queue-design、error-model-design、security-boundary-design、consistency-transaction-design、integration-boundary-design、observability-design、migration-rollout-design）
+- **可交付技能**：5 個（generate_mermaid_diagram、design_database_schema、generate_openapi_spec、write_adr、evaluate_tech_stack）
+
+## 防範佔位符規則
+範例僅供說明用途。請勿重複使用範例中的佔位符元件、欄位、端點或結構，否則會與 PRD 要求不符。
+
+## 不應做的事
+- 不改變 PRD 範圍或需求
+- 不建立任務拆分或里程碑
+- 不寫測試案例
+- 不寫實作程式碼
+- 不選擇特定函式庫或框架
+- 不產生 `docs/architecture/{feature}.md` 以外的檔案

skills/design_database_schema/README.zh-TW.md

@@ -0,0 +1,32 @@
+# 設計資料庫結構 (Design Database Schema) 技能指南
+
+## 概述
+`design_database_schema` 是可交付技能，用來產生資料庫結構定義，包含資料表、集合、分區鍵、索引、關係、反正規化策略與遷移策略。支援 PostgreSQL、Cassandra、MongoDB、Redis、Surrealdb。供 `design-architecture` 在產生 Database Schema 章節時參考。
+
+## 核心原則
+此技能提供具體的格式要求與完整性檢查清單。Schema 定義必須具體到足以供實作使用。
+
+## 支援的資料庫
+| 資料庫 | 適用場景 | 不適用場景 |
+|--------|---------|-----------|
+| PostgreSQL | 關聯資料、ACID 交易、複雜查詢 | 大量寫入吞吐量、寬列存取模式 |
+| Cassandra | 高寫入吞吐量、時間序列、寬列存取 | 複雜 JOIN、ACID 交易、隨機查詢 |
+| MongoDB | 文件資料、彈性結構、快速迭代 | 複雜 JOIN、嚴格 ACID、關聯資料 |
+| Redis | 快取、工作階段、速率限制、即時排行榜 | 持久化主資料、複雜查詢 |
+| SurrealDB | 多模型資料、即時、圖形關係 | 生態系不成熟 |
+
+## 必備元素
+- **資料表/集合**：每個實體的完整定義（含欄位名稱、類型、限制式）
+- **索引**：每個索引必須有查詢模式支撐
+- **分區鍵**：Cassandra、DynamoDB 等分散式資料庫
+- **關係**：外鍵、參考完整性、 cascade 行為
+- **反正規化策略**：理由與一致性影響
+- **遷移策略**：向後相容的遷移方法
+
+## 防範佔位符規則
+範例僅供說明用途。不要重複使用範例中的佔位符資料表名稱、欄位名稱、類型、索引或關係。
+
+## 不應做的事
+- 不替非 PRD 要求的實體建立資料表
+- 不產生與實際需求無關的欄位或索引
+- 不產生獨立 Schema 檔案（所有內容必須嵌入 `docs/architecture/{feature}.md`）

skills/distributed-system-basics/README.zh-TW.md

@@ -0,0 +1,26 @@
+# 分散式系統基礎 (Distributed System Basics) 知識合約指南
+
+## 概述
+`distributed-system-basics` 是知識合約，用來理解與設計分散式系統的相關考量：At-least-once vs Exactly-once、Retry 行為、Duplicates、Idempotency、Timeout vs Failure、Partial Failure、Eventual Consistency 與 Ordering Guarantees。供 `design-architecture` 在處理分散式系統相關問題時參考。
+
+## 核心原則
+分散式系統中，網路呼叫會失敗、請求會重複、資料可能過時。設計時必須假設這些問題會發生，並系統性地處理它們。
+
+## 設計重點
+- **交付保證**：At-Most-Once、At-Least-Once、Exactly-Once 的選擇框架
+- **Retry 行為**：何時重試、何時不重試、退避策略
+- **Duplicates**：如何產生、如何處理（Idempotency keys、Deduplication）
+- **Timeout vs Failure**：Timeout 表示未知狀態，不是失敗狀態
+- **Partial Failure**：多步驟操作失敗時的處理策略
+- **Eventual Consistency**：使用時機與一致性窗口
+- **Ordering Guarantees**：Per-Partition vs Global vs None
+
+## 知識合約職責
+- 提供分散式系統設計的理論指引
+- 說明各種模式的 Trade-offs 與適用場景
+- 不直接產生實作程式碼或配置
+
+## 不應做的事
+- 不替系統選擇特定實現方式
+- 不假設網路呼叫永遠成功
+- 不忽略分散式帶來的複雜性

skills/error-model-design/README.zh-TW.md

@@ -0,0 +1,25 @@
+# 錯誤模型設計 (Error Model Design) 知識合約指南
+
+## 概述
+`error-model-design` 是知識合約，用來設計錯誤分類、傳播策略、可重試 vs 不可重試錯誤、Partial Failure 行為與回退策略。供 `design-architecture` 在定義錯誤處理時參考。
+
+## 核心原則
+錯誤處理必須系統性設計，不能事後才追加。每個錯誤分類必須可追溯到 PRD edge case 或 NFR。錯誤模型必須在整個系統中保持一致。
+
+## 設計重點
+- **錯誤分類**：Client Errors (4xx)、Server Errors (5xx)、Business Rule Violations、Timeout Errors、Cascading Failures
+- **錯誤傳播策略**：Fail-Fast、Graceful Degradation、Circuit Breaker
+- **錯誤回應格式**：一致的錯誤碼、機器可讀與人類可讀的訊息
+- **Retryable vs Non-Retryable**：何時可重試、何時不可重試
+- **Partial Failure 行為**：All-or-nothing、Best-effort、Saga/Compensation
+- **回退策略**：每個外部依賴的回退行為
+
+## 知識合約職責
+- 提供錯誤處理的理論指引
+- 說明各種模式的 Trade-offs 與適用場景
+- 不直接產生錯誤代碼定義或實作程式碼
+
+## 不應做的事
+- 不替系統定義具體的錯誤碼
+- 不假設所有錯誤都是同樣處理方式
+- 不忽略 Partial Failure 場景

skills/evaluate_tech_stack/README.zh-TW.md

@@ -0,0 +1,27 @@
+# 評估技術棧 (Evaluate Tech Stack) 技能指南
+
+## 概述
+`evaluate_tech_stack` 是可交付技能，用來評估與建議技術棧，包含語言、框架、資料庫、佇列、快取與基礎設施。記錄每個選擇的優缺點與理由。供 `design-architecture` 在產生 Technology Stack 子章節時參考。
+
+## 核心原則
+技術選擇必須基於 PRD 需求、現有系統、團隊專業知識與營運限制。每個技術選擇都必須有優缺點與理由。
+
+## 評估層次
+- **Language**：程式語言（以生態系、效能、團隊專業、函式庫支援評估）
+- **Framework**：應用框架（以成熟度、社群、效能、開發者體驗評估）
+- **Database**：資料庫（以資料模型契合度、查詢模式、一致性需求評估）
+- **Queue / Message Broker**：訊息佇列或事件串流平台
+- **Cache**：快取層
+- **Infrastructure**：部署基礎設施
+
+## 防範佔位符規則
+範例僅供說明用途。不要重複使用範例中的佔位符技術名稱、理由或替代方案。
+
+## 知識合約職責
+- 與 `storage-knowledge` 和 `architecture-patterns` 知識合約搭配使用
+- 前者提供儲存技術比較，後者提供模式選擇指引
+
+## 不應做的事
+- 不替 PRD 沒有要求的場景選擇技術
+- 不基於時尚或流行選擇技術
+- 不產生獨立評估文件（所有內容必須嵌入 `docs/architecture/{feature}.md`）

skills/finalize-architecture/README.zh-TW.md

@@ -0,0 +1,38 @@
+# 完成架構 (Finalize Architecture) 技能指南
+
+## 概述
+`finalize-architecture` 是 Architect Pipeline 的最後一個步驟，在挑戰審查與修訂完成後，對架構文件進行最終完整性檢查與格式驗證。
+
+## 輸入與輸出
+### 輸入
+- `docs/architecture/{feature}.md`
+
+### 輸出
+- 最終 `docs/architecture/{feature}.md`
+
+## 驗證步驟
+1. **章節完整性檢查**：18 個必備章節是否都存在與實質內容
+2. **Mermaid 圖表驗證**：至少 3 張圖表（System、Sequence、Data Flow）、語法正確、無孤兒元件
+3. **資料庫 Schema 驗證**：所有表格含欄位、類型與限制式、索引有理由
+4. **API 合約驗證**：所有端點含方法、路徑、請求/回應結構
+5. **ADR 驗證**：至少 1 個 ADR，含 Context、Decision、Consequences、Alternatives
+6. **可追溯性驗證**：每個元素是否可追溯到 PRD 需求
+7. **格式驗證**：章節順序、Markdown 語法、無外部檔案參照
+8. **架構審查閘道**：確認挑戰審查的 Gate Decision 是否為 PASS 或 CONDITIONAL PASS
+
+## 完成檢查清單
+- [ ] 18 個必備章節存在且實質（或是 N/A with reason）
+- [ ] 至少 3 張 Mermaid 圖表
+- [ ] Database Schema 有完整表格定義
+- [ ] API Contract 有完整端點規格
+- [ ] 至少 1 個 ADR 且格式完整
+- [ ] 所有元素可追溯到 PRD 需求
+- [ ] 架構審查閘道為 PASS 或 CONDITIONAL PASS
+- [ ] Risks 區段已填寫
+- [ ] Open Questions 區段已填寫（或明確寫 None）
+
+## 不應做的事
+- 不設計新架構
+- 不改變架構決策
+- 不新增未在挑戰審查中驗證的重大內容
+- 不產生 `docs/architecture/{feature}.md` 以外的檔案

skills/generate_mermaid_diagram/README.zh-TW.md

@@ -0,0 +1,28 @@
+# 產生 Mermaid 圖表 (Generate Mermaid Diagram) 技能指南
+
+## 概述
+`generate_mermaid_diagram` 是可交付技能，用來產生系統架構圖、序列圖、資料流圖、事件流圖與狀態機圖。供 `design-architecture` 在產生 Mermaid Diagrams 章節時參考。
+
+## 核心原則
+圖表必須可視化系統架構，且所有圖表中的元件都必須在架構文件文字中描述。不得有無法對應到實際元件的孤兒元件。
+
+## 必備圖表（至少 3 張）
+1. **System Architecture Diagram**：所有服務、資料庫、佇列、快取與外部整合及其連接方式
+2. **Sequence Diagram**：主要快樂路徑的互動流程
+3. **Data Flow Diagram**：資料如何流經系統，含轉換與儲存點
+
+## 選用圖表
+- **Event Flow Diagram**：事件如何傳播
+- **State Machine Diagram**：實體生命週期與狀態轉換
+
+## 圖表指南
+- **命名慣例**：Services 用 PascalCase，Databases 用 DB suffix，Queues/Topics 用描述性名稱
+- **關係標籤**：同步用 `-->`，非同步用 `-.->`
+- **元件命名**：有意義的標籤，非縮寫（除非文件中已定義縮寫）
+
+## 防範佔位符規則
+範例僅供說明用途。不要重複使用範例中的佔位符元件、服務、資料庫或關係。
+
+## 不應做的事
+- 不產生與架構文件內容無關的圖表
+- 不產生獨立圖表檔案（所有圖表必須嵌入 `docs/architecture/{feature}.md`）

skills/generate_openapi_spec/README.zh-TW.md

@@ -0,0 +1,29 @@
+# 產生 OpenAPI 規格 (Generate OpenAPI Spec) 技能指南
+
+## 概述
+`generate_openapi_spec` 是可交付技能，用來產生 OpenAPI 或 gRPC API 合約定義，包含端點、請求/回應結構、錯誤碼、Idempotency、分頁與過濾。供 `design-architecture` 在產生 API Contract 章節時參考。
+
+## 核心原則
+API 合約定義必須具體到足以供實作使用。每個端點必須服務至少一個 PRD 功能需求。
+
+## REST API 必備元素
+- **端點定義**：方法、路徑、請求結構、回應結構
+- **錯誤碼**：一致的錯誤碼與錯誤回應格式
+- **Idempotency**：哪些端點需要、機制是什麼
+- **分頁**：列表端點的分頁機制與回應格式
+- **過濾**：支援哪些過濾欄位與運算子
+
+## gRPC API 必備元素
+- **Service 定義**：Package、Service name、Methods
+- **Message 定義**：Request / Response 訊息結構
+- **錯誤碼**：gRPC status codes
+
+## 防範佔位符規則
+範例僅供說明用途。不要重複使用範例中的佔位符端點、欄位名稱、回應結構或錯誤碼。
+
+## 知識合約職責
+- 與 `api-contract-design` 知識合約搭配使用：前者提供理論原則，後者提供格式
+
+## 不應做的事
+- 不替非 PRD 要求的端點定義結構
+- 不產生獨立 OpenAPI YAML 或 gRPC proto 檔案（所有內容必須嵌入 `docs/architecture/{feature}.md`）

skills/integration-boundary-design/README.zh-TW.md

@@ -0,0 +1,36 @@
+# 整合邊界設計 (Integration Boundary Design) 知識合約指南
+
+## 概述
+`integration-boundary-design` 是知識合約，用來提供整合邊界設計的原則與模式。涵蓋外部 API 整合、Webhook 處理、Polling、重試策略、速率限制與失敗模式處理。供 `design-architecture` 在定義 Integration Boundaries 時參考。
+
+## 核心原則
+### 整合隔離
+- 外部系統失敗不得級聯到系統失敗
+- Circuit Breaker 必須保護內部服務
+- 整合程式碼必須與商業邏輯隔離（Anti-Corruption Layer）
+
+### 明確合約
+- 每個外部整合必須有明確定義的合約
+- 合約必須包含請求/回應結構、錯誤碼與 SLA
+- 變更必須版本化並盡可能向後相容
+
+### 假設失敗
+- 外部系統會失敗、逾時、返回非預期資料
+- 必須為每個整合定義逾時、重試與回退
+
+## 設計重點
+- **外部 API 整合**：同步呼叫、非同步呼叫、Batch 呼叫、串流
+- **Webhook 處理**：Inbound Webhooks（接收）與 Outbound Webhooks（發送）
+- **Polling**：增量 Polling、輪詢間隔與資料差距處理
+- **重試策略**：退避策略、重試預算、最大總重試時間
+- **速率限制**：Token Bucket、Leaky Bucket、Fixed Window、Sliding Window
+- **失敗模式處理**：Transient、Permanent、Partial、Cascading Failure
+
+## 知識合約職責
+- 提供整合邊界設計的理論指引
+- 不直接產生整合合約或實作程式碼
+
+## 不應做的事
+- 不替特定外部系統選擇整合方式
+- 不定義具體的逾時值或重試次數
+- 不產生實作程式碼

skills/migration-rollout-design/README.zh-TW.md

@@ -0,0 +1,35 @@
+# 遷移與上線設計 (Migration Rollout Design) 知識合約指南
+
+## 概述
+`migration-rollout-design` 是知識合約，用來提供遷移與上線設計的原則與模式。涵蓋向後相容、上線策略、Canary Deployment、Feature Flags、Schema Evolution 與 Rollback。供 `design-architecture` 在定義 Migration & Rollout Strategy 時參考。
+
+## 核心原則
+### 向後相容優先
+- 新版本必須與舊版本共存於遷移期間
+- API 必須向後相容直到所有消費者都遷移完成
+- 資料庫結構必須同時支援舊版和新版程式碼
+
+### 增量勝過 Big-Bang
+- 增量遷移，一步一步來
+- 每步必須可獨立部署與逆轉
+- Big-Bang 遷移風險高，逆轉困難
+
+### 預設 Rollback
+- 每個遷移步驟必須有明確的 rollback 計畫
+- Feature Flags 可實現即時 rollback，無需重新部署
+
+## 設計重點
+- **上線策略**：Blue-Green Deployment、Canary Deployment、Rolling Deployment、Feature Flag Deployment
+- **Feature Flags**：Release flags、Operational flags、Experiment flags、Permission flags
+- **Schema Evolution**：Additive Changes（安全）vs Destructive Changes（需遷移）
+- **Migration Strategy**：Expand → Migrate → Contract 三階段
+- **Rollback**：Application Rollback、Database Rollback 與決策矩陣
+
+## 知識合約職責
+- 提供遷移與上線設計的理論指引
+- 不直接產生遷移腳本或上線腳本
+
+## 不應做的事
+- 不替系統選擇特定部署策略
+- 不定義具體的 Feature Flag 名稱或值
+- 不產生遷移或部署腳本

skills/observability-design/README.zh-TW.md

@@ -0,0 +1,31 @@
+# 可觀測性設計 (Observability Design) 知識合約指南
+
+## 概述
+`observability-design` 是知識合約，用來提供可觀測性設計的原則與模式。涵蓋 Logs、Metrics、Traces、Correlation IDs、Alerts 與 SLOs。供 `design-architecture` 在定義 Observability Strategy 時參考。
+
+## 核心原則
+### 可觀測性三支柱
+- **Logs**：離散事件，含上下文（誰、什麼、何時、何地）
+- **Metrics**：時間聚合的數值測量（速率、長條圖、Guage）
+- **Traces**：跨服務端到端請求流
+
+### 可觀測性不是監控
+- 監控告訴你什麼時候壞了（已知未知）
+- 可觀測性讓你能問為什麼壞了（未知未知）
+- 必須從一開始就內建可觀測性，不能事後追加
+
+## 設計重點
+- **Logs**：Log 等級、結構化 Log（JSON）、集中式 Log 聚合
+- **Metrics**：Counter、Gauge、Histogram、Summary；命名慣例
+- **Traces**：分散式追蹤、Correlation ID 傳播、Span 設計
+- **Alerts**：症狀警報、非操作警報；閾值與升遷路徑
+- **SLOs**：可用性、延遲、正確性；Error Budget 與 Burn Rate Alerting
+
+## 知識合約職責
+- 提供可觀測性設計的理論指引
+- 不直接產生監控設定或警報配置
+
+## 不應做的事
+- 不替系統選擇特定可觀測性工具
+- 不定義具體的指標名稱或警報閾值
+- 不產生監控設定檔案

skills/security-boundary-design/README.zh-TW.md

@@ -0,0 +1,38 @@
+# 安全邊界設計 (Security Boundary Design) 知識合約指南
+
+## 概述
+`security-boundary-design` 是知識合約，用來提供安全邊界設計的原則與模式。涵蓋 Authentication、Authorization、Service Identity、Token Propagation、Tenant Isolation、Secret Management 與 Audit Logging。供 `design-architecture` 在定義 Security Boundaries 時參考。
+
+## 核心原則
+### Defense in Depth
+- 不要依賴單一安全邊界
+- 在每一層套用安全：網路、服務、資料、應用
+- 假設已被入侵：設計時讓單層被破壞不會導致全盤被破壞
+
+### Least Privilege
+- 服務與使用者應該只有最小必要權限
+- 預設拒絕：從無權限開始，明確授予
+- 定期輪換與過期憑證
+
+### Zero Trust
+- 不要預設信任內部網路流量
+- 每次服務對服務呼叫都要認證與授權
+- 傳輸中資料必須加密，即使在內部網路也是
+
+## 設計重點
+- **Authentication**：Token-based、API Key、Certificate-based、Session-based
+- **Authorization**：RBAC、ABAC、ACL、ReBAC 的選擇與粒度
+- **Service Identity**：Service Accounts、Workload Identity、Service Mesh Identity
+- **Token Propagation**：Pass-through、Token Exchange、Token Relay、Impersonation
+- **Tenant Isolation**：Database-level、Schema-level、Row-level、Application-level
+- **Secret Management**：Environment Variables、Secret Management Service、Platform-native、Configuration Service
+- **Audit Logging**：認證/授權事件、日誌修改操作、行政動作
+
+## 知識合約職責
+- 提供安全邊界設計的理論指引
+- 不直接產生安全配置或憑證管理設定
+
+## 不應做的事
+- 不替系統選擇特定安全技術
+- 不定義具體的 RBAC 角色或權限
+- 不產生安全設定檔案

skills/storage-knowledge/README.zh-TW.md

@@ -0,0 +1,31 @@
+# 儲存知識 (Storage Knowledge) 知識合約指南
+
+## 概述
+`storage-knowledge` 是知識合約，用來提供儲存技術選擇的原則與框架。涵蓋關聯式、寬列式、文件式與鍵值式儲存，並提供 Use-When 與 Avoid-When 判斷標準。供 `design-architecture` 在做儲存決策時參考。
+
+## 核心原則
+儲存選擇必須由 PRD 中識別的查詢模式、寫入模式、一致性需求與規模預期驅動。不要因為熟悉、時尚或覺得可能需要就選擇儲存技術。
+
+## 儲存選擇標準
+選擇儲存前，必須先回答：
+1. 主要查詢模式是什麼？（按鍵、按範圍、按複雜過濾、全文搜索）
+2. 寫入模式是什麼？（寫入為主、更新為主、僅附加）
+3. 需要什麼一致性？（Strong、Eventual、Tunable）
+4. 預期規模是多少？（每天列數、總列數、生長率）
+5. 存取延遲需求是什麼？（毫秒、秒、最終一致）
+6. 與其他實體的關係是什麼？（外鍵、嵌套文件、圖形遍歷）
+
+## 儲存類型
+- **Relational (PostgreSQL)**：強一致性、複雜 JOIN、交易完整性
+- **Wide-Column (Cassandra)**：高寫入吞吐量、查詢優先建模、線性水平擴展
+- **Document (MongoDB)**：文件中心資料、Schema 彈性、豐富查詢能力
+- **Key-Value (Redis)**：快取、速率限制、Idempotency Keys、工作階段
+
+## 知識合約職責
+- 提供各儲存技術的比較與選擇框架
+- 不替 PRD 做最終儲存選擇
+
+## 不應做的事
+- 不替系統選擇特定儲存技術
+- 不基於時尚或流行選擇儲存
+- 不假設某種儲存適合所有場景

skills/system-decomposition/README.zh-TW.md

@@ -0,0 +1,43 @@
+# 系統分解 (System Decomposition) 知識合約指南
+
+## 概述
+`system-decomposition` 是知識合約，用來提供將系統拆分為服務或模組的原則。包含邊界定義、資料所有權與依賴方向。供 `design-architecture` 在設計 Service Boundaries 時參考。
+
+## 核心原則
+- 每個服務或模組必須有單一、明確的職責
+- 資料所有權必須明確：每筆資料只屬於一個服務
+- 依賴必須單向流動；嚴禁循環依賴
+- 邊界必須環繞領域職責繪製，而非技術分層
+
+## 設計重點
+### Modular Monolith vs Microservices
+- 選擇 Modular Monolith：團隊小、邊界仍在演化、部署簡單優先
+- 選擇 Microservices：個別服務有不同擴展需求、團隊擁有對齊、獨立部署是需求
+
+### 領域邊界
+- 一起變化的實體
+- 內聚的業務規則
+- 一起存取的資料
+- 橫跨一致上下文的使用者工作流
+
+好的邊界：高內聚、低外部耦合、可獨立理解、可獨立部署。
+
+### 耦合 vs 內聚
+- 偏好邊界內高內聚
+- 最小化邊界間耦合
+- 透過明確合約（API、事件）溝通
+- 避免共享資料庫表
+
+### 狀態所有權
+- 每筆狀態只有一個擁有者
+- 其他服務透過擁有者的 API 或事件存取
+- 嚴禁服務直接讀取另一服務的資料庫
+
+## 知識合約職責
+- 提供系統分解的理論指引
+- 不替 PRD 做最終邊界決策
+
+## 不應做的事
+- 不替系統定義特定服務邊界
+- 不假設 Microservices 適合所有場景
+- 不忽略領域邊界而以技術分層

skills/write_adr/README.zh-TW.md

@@ -0,0 +1,32 @@
+# 寫作 ADR (Write ADR) 技能指南
+
+## 概述
+`write_adr` 是可交付技能，用來產生架構決策記錄（ADR），包含 Context、Decision、Consequences 與 Alternatives。供 `design-architecture` 在產生 ADR 章節時參考。
+
+## 核心原則
+ADR 為每個重要架構決策提供永久記錄。包含決策背後的理由、考慮的替代方案與權衡取捨。
+
+## 何時寫 ADR
+為以下任何決策寫 ADR：
+- 影響系統結構或服務邊界
+- 涉及技術選擇（語言、框架、資料庫、佇列、快取、基礎設施）
+- 涉及一致性模型選擇
+- 涉及安全架構決策
+- 涉及重大取捨（效能 vs 一致性、複雜度 vs 簡單性）
+- 難以或昂貴逆轉的決策
+- 其他工程師會質疑「為什麼這樣選？」的決策
+
+## ADR 格式
+每個 ADR 必須包含：
+- **Context**：為什麼需要這個決策，什麼問題或情境需要決定，什麼 PRD 需求驅動了這個決策
+- **Decision**：決定了什麼，清楚且具體地陳述，包含選擇的特定技術、模式或方法
+- **Consequences**：這個決策帶來的取捨，正面與負面都要
+- **Alternatives**：考慮過什麼其他選項，每個選項的描述與不被選中的理由
+
+## 防範佔位符規則
+範例僅供說明用途。不要重複使用範例中的佔位符 ADR 標題、Context、Decision 或 Alternatives。
+
+## 不應做的事
+- 不替非實際架構決策寫 ADR
+- 不複製範例的內容當作自己的決策
+- 不產生獨立 ADR 檔案（所有 ADR 必須嵌入 `docs/architecture/{feature}.md`）