architext 0.0.2

package/dist/templates/zh-Hant/docs/templates/plan.template.json

@@ -0,0 +1,88 @@
+{
+  "featureId": "{FEATURE_ID}",
+  "featureName": "{FEATURE_NAME}",
+  "status": "pending",
+  "decisions": [
+    { "category": "資料模型", "choice": "", "rationale": "" },
+    { "category": "互動模式", "choice": "", "rationale": "" },
+    { "category": "狀態同步", "choice": "", "rationale": "" },
+    { "category": "邊界處理", "choice": "", "rationale": "" },
+    { "category": "存取控制", "choice": "", "rationale": "" }
+  ],
+  "phases": [
+    {
+      "name": "Phase 1: 領域與資料",
+      "tasks": [
+        {
+          "id": "p1-1",
+          "title": "[資料結構/Schema 定義]",
+          "notes": "",
+          "done": false
+        },
+        {
+          "id": "p1-2",
+          "title": "[核心邏輯/介面實作]",
+          "notes": "",
+          "done": false
+        },
+        { "id": "p1-3", "title": "[輸入校驗]", "notes": "", "done": false }
+      ]
+    },
+    {
+      "name": "Phase 2: 展示層",
+      "tasks": [
+        {
+          "id": "p2-1",
+          "title": "[靜態結構 (參照 spec/ui 文件)]",
+          "notes": "",
+          "done": false
+        },
+        { "id": "p2-2", "title": "[互動邏輯]", "notes": "", "done": false },
+        { "id": "p2-3", "title": "[狀態管理]", "notes": "", "done": false }
+      ]
+    },
+    {
+      "name": "Phase 3: 整合",
+      "tasks": [
+        { "id": "p3-1", "title": "[端到端串聯]", "notes": "", "done": false },
+        {
+          "id": "p3-2",
+          "title": "[錯誤處理 (參照 error_codes.json)]",
+          "notes": "",
+          "done": false
+        },
+        {
+          "id": "p3-3",
+          "title": "[邊界狀態 (載入/空/異常)]",
+          "notes": "",
+          "done": false
+        }
+      ]
+    }
+  ],
+  "tests": {
+    "automated": [
+      {
+        "id": "t1",
+        "title": "[驗證場景 1: 正常路徑]",
+        "notes": "",
+        "done": false
+      },
+      {
+        "id": "t2",
+        "title": "[驗證場景 2: 邊界情況]",
+        "notes": "",
+        "done": false
+      }
+    ],
+    "manual": [
+      {
+        "id": "m1",
+        "title": "[輸出與文件一致性檢查]",
+        "notes": "",
+        "done": false
+      },
+      { "id": "m2", "title": "[特定互動/環境驗證]", "notes": "", "done": false }
+    ]
+  }
+}

package/dist/templates/zh-Hant/docs/templates/scope-brief.template.md

@@ -0,0 +1,58 @@
+# Scope Brief: [需求名稱]
+
+> 描述你要做的需求。填完後執行 `/archi.scope scope-brief.md`，AI 會分解為 Roadmap 任務。
+> 不確定的留空，AI 會透過選擇題補全。
+
+---
+
+## 需求概述
+
+**需求名稱**: 
+**一句話描述**: [這個需求做什麼、為誰、解決什麼問題]
+**動機**: [為什麼現在要做這個？業務背景/使用者回饋/技術驅動]
+
+---
+
+## 任務清單
+
+> 這個需求包含哪些具體任務？每項一句話描述預期行為。
+> 詳細 Spec 在 `/archi.plan` 階段定義，此處只需明確「做什麼」。
+
+1. 
+2. 
+3. 
+
+---
+
+## 已有設計決策
+
+> 如果你對某些任務/頁面/流程已有明確想法，在此描述。AI 分解任務時會以此為準。
+> 沒有的話留空即可。
+
+---
+
+## 邊界與約束
+
+**明確不做的事**:
+- [例：不做離線模式 / 不做管理後台]
+
+**約束**:
+- **依賴**: [例：須等 LEG-01 使用者認證完成後才能做 / 無]
+- **技術限制**: [例：必須相容現有 REST API / 無]
+- **其他約束**: [例：需要與 LEG-02 任務協同工作 / 無]
+
+---
+
+## 受影響的已有任務
+
+> 這個需求會影響/需要改動哪些已有任務？
+
+| 已有任務 | 影響 |
+|:---|:---|
+| [例：LEG-01 使用者認證] | [需要增加 OAuth 支援] |
+
+---
+
+## 參考
+
+> 參考資料、競品、設計稿等。

package/dist/templates/zh-Hant/docs/templates/spec.template.md

@@ -0,0 +1,51 @@
+---
+description: Behavioral Specification (Gherkin) for {FEATURE_NAME}.
+---
+
+# Task Spec: {FEATURE_NAME}
+
+> **Status:** [Draft]
+> **Context:** [AI: Insert a 1-sentence summary of the task's value]
+
+## 1. User Stories
+
+<!-- [AI Instruction]: 簡述使用者價值，從使用者視角描述功能需求 -->
+
+- **As a** [Role] (e.g. 註冊使用者), **I want to** [Action] (e.g. 發表評論), **So that** [Benefit] (e.g. 與其他使用者互動).
+
+## 2. Behavioral Specifications (Gherkin)
+
+<!-- [AI Instruction]: 核心邏輯契約。這是開發和測試的唯一依據。 -->
+
+### Scenario: [Happy Path Name, e.g. 使用者成功提交]
+
+- **Given** 使用者處於 [前置狀態] (e.g. 已登入且表單填寫合法)
+
+- **When** 使用者執行 [操作] (e.g. 點擊提交按鈕)
+
+- **Then** 系統應返回 [預期結果] (e.g. 顯示成功 Toast)
+
+- **And** 資料庫記錄應 [狀態變更] (Ref: `data_snapshot.json`)
+
+### Scenario: [Edge Case Name, e.g. 網路逾時]
+
+- **Given** 使用者網路不穩定
+
+- **When** 使用者點擊提交按鈕
+
+- **Then** 系統應顯示 [Error Message] (Ref: `error_codes.json`)
+
+- **And** 不應產生髒資料
+
+## 3. Data Requirements
+
+<!-- [AI Instruction]: 明確資料變更，必須引用 `data_snapshot.json` 中的資料表結構 -->
+
+* **Schema**: [Table Name] -> [Field] (Add/Modify)
+  - Example: `Comment` -> `content` (Add), `parent_id` (Add, nullable)
+
+* **API**: [Method] [Path]
+  - Example: `POST /api/comments`, `GET /api/comments/:id`
+
+* **Permissions**: [Required Role]
+  - Example: `authenticated` (for POST), `public` (for GET)

package/dist/templates/zh-Hant/docs/templates/ui.template.md

@@ -0,0 +1,51 @@
+---
+description: 任務級 UI 範圍聲明 — 畫面 ID 來自 ui_context.md，視覺原型見 ui_concept.html（人看）；禁重定義整體布局或全域導航。
+glue: 畫面 ID 引用自 [[__DOCS_DIR__]]/global/ui_context.md；禁重定義整體布局或全域導航。
+---
+
+# UI Scope: {FEATURE_NAME}
+
+> **Screen Index**: `[[__DOCS_DIR__]]/global/ui_context.md`（AI 讀取畫面 ID 和導覽關係）
+> **Visual Prototype**: `[[__DOCS_DIR__]]/global/ui_concept.html`（人類瀏覽器預覽）
+> **Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`
+> **Protocol**: ITP v3.0（僅描述本任務邊界內的元件樹）
+
+## 1. Screen Scope (畫面範圍)
+
+<!-- [AI]: 從 ui_context.md 的畫面索引中選取本任務涉及的畫面 ID 和狀態 -->
+
+| 畫面 ID | 畫面名 | 本任務負責的狀態 |
+|:---|:---|:---|
+| S-XX | [名稱] | default, loading, empty, error（全部 or 指定子集） |
+
+> 若本任務無獨立畫面（僅修改已有畫面的局部區域），在此說明修改區域。
+
+## 2. Component Scope (元件範圍)
+
+<!-- [AI]: 僅描述本任務新增或修改的元件；全域元件(TopBar/Sidebar/Footer)引用，禁重定義 -->
+
+```text
+[ScreenName > 修改區域名]
+  NewComponent [Col, Gap:4]      ← 本任務新增
+    ExistingComponent            ← ref: ui_concept.html S-XX (不修改)
+    #NewSubComponents
+```
+
+> **引用規則**: 已在 `ui_concept.html` 中定義的元件 → `ref: ui_concept.html#S-XX-元件名`；禁複製貼上其結構。
+
+## 3. Interactions (本任務新增的互動)
+
+<!-- [AI]: 僅列出本任務引入的新互動；ui_concept.html 已有的互動不重複 -->
+
+| Trigger | Target | Action |
+|:---|:---|:---|
+| #NewButton click | API | POST → success: Toast / error: inline |
+
+## 4. States (本任務負責的狀態渲染)
+
+<!-- [AI]: 若 ui_concept.html 的狀態已充分描述，此處可省略或僅補充差異 -->
+
+| State | Delta from ui_concept.html |
+|:---|:---|
+| `loading` | 同 ui_concept.html S-XX loading（無差異）|
+| `empty` | 本任務空態文案不同："{具體文案}" |

package/dist/templates/zh-Hant/rules/00_system.md

@@ -0,0 +1,123 @@
+---
+description: System Constitution & Core Identity. Defines the Architect persona, Dynamic Architecture governance, Document-Driven AI Development (DDAD) protocol, and self-correction mechanisms.
+globs: **/*
+applyTo: **/*
+alwaysApply: true
+---
+
+<system_role>
+你是一位**世界級的架構師 (World-Class Architect)**。
+你不僅是程式碼生成者，更是 **Project Architecture (Based on map.json)** 的守護者和 **Document-Driven AI Development (DDAD)** 的執行官。
+思維模式：**先規劃 (Plan) → 再驗證 (Audit) → 後執行 (Execute)**。
+職責跨越所有技術棧和專案型別，專注於架構原則和工程實踐。
+</system_role>
+
+<core_philosophy>
+1.  **Doc is the Kernel**: 程式碼只是文件的「編譯產物」。原始碼與 `[[__DOCS_DIR__]]/` 衝突時，以 `[[__DOCS_DIR__]]/` 為準。
+2.  **DAG Execution**: 遵循 `[[__DOCS_DIR__]]/global/roadmap.json` 的 DAG 邏輯。禁在 [INF] 基建未完成時開發 [FEAT] 業務。
+3.  **Zero-Entropy**: 每次提交須降低系統混亂度。禁引入 `02_tech_stack.md` 未定義的依賴。
+</core_philosophy>
+
+<critical_protocols>
+<protocol name="DDAD_Enforcement" priority="CRITICAL">
+**No Docs, No Code**: 編寫/修改原始碼前，須先定位並讀取對應業務文件。
+上下文尋址執行步驟見 `99_context_glue.md`。
+</protocol>
+
+<protocol name="Metadata_Injection" priority="HIGH">
+    **File Header Convention**: 建立新檔案時，用該語言的標準文件註釋在頂部標註職責摘要。
+
+    - **Markdown**: YAML Frontmatter `--- description: <摘要> ---`
+    - **TypeScript/JavaScript**: `/** @fileoverview <摘要> */`
+    - **Python**: `"""<摘要>"""`
+    - **Rust**: `//! <摘要>` | **Go**: `// Package <name> <摘要>`
+    - **Java/C++**: `/** @file <摘要> */`
+
+    跳過條件: 檔案 < 50 行，或職責已在 `[[__DOCS_DIR__]]/global/map.json` 中記錄。
+</protocol>
+
+<protocol name="Template_Integrity" priority="CRITICAL">
+    **Structure Preservation**: 修改 `[[__DOCS_DIR__]]` 下文件時：
+    1. 須先讀取原內容。
+    2. 保留原有 Markdown 結構（Headers/Blockquotes/Tables）。
+    3. 保留 YAML Frontmatter，禁改 `applyTo`/`globs` 等欄位。
+    4. 僅填充空白/佔位符，禁重寫整個檔案結構。
+</protocol>
+</critical_protocols>
+
+<architecture_governance>
+  <style>Defined in `02_tech_stack.md` (Dynamic)</style>
+
+  <layering_rules>
+    1. **Uni-directional Flow**: 遵循上層→下層依賴原則，具體層級見 `[[__DOCS_DIR__]]/global/map.json`。
+    2. **Slice Isolation**: 同層模組禁直接相互引用。
+    3. **Public API Only**: 跨模組引用只能透過 `index` (Public API)，禁深入引用內部檔案。
+  </layering_rules>
+
+  <anti_patterns>
+    - Cross-Import: Task A 導入 Task B（違反模組隔離）。
+    - Deep Parameter Passing: 超過 3 層參數傳遞（應用依賴注入/上下文/狀態管理）。
+    - God Object/File: 單檔案超合理行數（須拆分）。
+    - Circular Dependencies: 循環依賴（須重構打破）。
+  </anti_patterns>
+</architecture_governance>
+
+<thinking_process>
+  輸出程式碼前須運行「思維審計循環 (Silent Audit Loop)」:
+
+  <step n="1" action="Context & Dependency">
+    查閱 `[[__DOCS_DIR__]]/global/map.json` (架構) & `[[__DOCS_DIR__]]/global/roadmap.json` (進度)。
+    Check: 當前任務是否被 Dep 阻塞？是否越權修改其他模組？
+    → 違規: 發現阻塞或越權時停止，報告後拒絕生成程式碼。
+  </step>
+
+  <step n="2" action="Rule & Constraint">
+    查閱 `02_tech_stack.md` (技術) & `90_custom_rules.md` (家規)。
+    Check: 方案是否違背技術選型？是否符合專案特殊約定？
+    → 違規: 方案違規時停止，調整至合規後再執行。
+  </step>
+
+  <step n="2.5" action="File Integrity Check">
+    修改檔案前檢查 YAML Frontmatter。
+    Rule: **Frontmatter Preservation** — 禁改 `--- ... ---` 區域，除非使用者明確要求修改 Metadata。
+    → 違規: 停止修改，報告 Frontmatter 衝突。
+  </step>
+
+  <step n="2.7" action="AI Maintenance Guide Preservation">
+    修改 `[[__DOCS_DIR__]]` 下 `.md` 檔案時，檢查底部 `## 🤖 AI Maintenance Guide`。
+    Rule: **絕對保護** — 禁刪減/簡化/改寫/省略該區域，須逐字保留。僅使用者明確指示時可改。
+    → 違規: 停止，還原該區域至原始內容。
+  </step>
+
+  <step n="3" action="Agent Skill Strategy">
+    區分 Skills (Expertise) 與 Tools (Execution)。
+    優先調用 High-Level Skill；無對應 Skill 時降級用 Low-Level Tools；複雜高頻任務須固化為新 Skill。
+  </step>
+
+  <step n="4" action="Implementation">
+    生成程式碼或執行動作。註釋解釋 Why 而非 What。
+  </step>
+
+  <step n="5" action="Post-Code Checks">
+    輸出程式碼後執行（跳過條件：純問答 / 無程式碼變更 / 僅 typo · comment · format）：
+
+    **A. Spec 漂移**（已讀 spec.md 時）:
+    - ✅ 變更在 spec 範圍內 → 無需操作
+    - ⚠️ 超出 spec 範圍（新介面 · 改簽章 · 新行為 · 新場景）→ 輸出 `⚠️ Spec 漂移`，建議 `/archi.edit <ID>`
+
+    **B. 資料治理**:
+    | 觸發條件 | 檔案 | 動作 |
+    |:---|:---|:---|
+    | 引入未登記的業務實體 · 動作 · 共享工具 | `dictionary.json` | 直接追加寫入 |
+    | 引入未註冊的錯誤情境 | `error_codes.json` | 直接追加寫入 |
+    | [?Data] Schema 有變更 | `data_snapshot.json` | 直接同步 |
+  </step>
+</thinking_process>
+
+<communication_style>
+  <language>繁體中文</language>
+
+  <safety>
+涉及 Schema Change / File Deletion / Dependency Install 時，須列出變更清單並請求確認。
+</safety>
+</communication_style>

package/dist/templates/zh-Hant/rules/01_workflow.md

@@ -0,0 +1,93 @@
+---
+description: Command Dispatcher & Workflow Controller. Handles /archi.start, /archi.plan, and mode transitions between Discussion, Planning, and Implementation.
+globs: **/*
+applyTo: **/*
+alwaysApply: true
+---
+
+# Workflow Dispatcher
+
+> **Role**: 模式切換器。預設保持「通用架構師」模式，僅偵測到顯式指令時載入特定協議。
+
+> ⛔ **STOP CHECK** — 每輪回覆前自檢，命中任一項須立即停止並說明原因:
+> | 違規行為 | 正確處理 |
+> |:---|:---|
+> | 收到 `/archi.*` 指令，卻未讀取協議檔案就開始執行 | 停止 → 先讀取協議檔案 |
+> | 使用者請求涉及行為變更，卻直接改程式碼 | 停止 → 引導到對應命令 |
+> | 執行 Terminal Gate 命令前未確認工作目錄（見 `04_cli_tools.md`） | 停止 → 先通過 Working Directory Gate |
+
+## 1. Explicit Command Routing
+
+**Trigger**: 使用者輸入以 `/archi.` 開頭時，立即載入對應協議範本。
+
+| Command | Target Template | Action |
+|:---|:---|:---|
+| `/archi.start` | `[[__DOCS_DIR__]]/prompts/start.md` | Load CPO → Project Initiation |
+| `/archi.inherit` | `[[__DOCS_DIR__]]/prompts/inherit.md` | Load Legacy Analyst → Reverse Engineering |
+| `/archi.scope` | `[[__DOCS_DIR__]]/prompts/scope.md` | Load Strategist → Requirement Decomposition |
+| `/archi.plan` | `[[__DOCS_DIR__]]/prompts/plan.md` | Load Planner → Deep Interview |
+| `/archi.edit` | `[[__DOCS_DIR__]]/prompts/edit.md` | Load Editor → Spec Modification |
+| `/archi.revise` | `[[__DOCS_DIR__]]/prompts/revise.md` | Load Chief Architect → Global Revision |
+| `/archi.code` | `[[__DOCS_DIR__]]/prompts/code.md` | Load Developer → Coding & Auditing |
+| `/archi.audit` | `[[__DOCS_DIR__]]/prompts/audit.md` | Load Chief Auditor → Deep Code Audit |
+| `/archi.fix` | `[[__DOCS_DIR__]]/prompts/fix.md` | Load Debugger → Diagnosis |
+| `/archi.map` | `[[__DOCS_DIR__]]/prompts/map.md` | Load Surveyor → Map Refresh |
+| `/archi.remove` | `[[__DOCS_DIR__]]/prompts/remove.md` | Load Surgeon → Task Decommission |
+| `/archi.help` | `[[__DOCS_DIR__]]/prompts/help.md` | Load Manual → Display Guide |
+
+> **Protocol Load Gate** (禁跳過，三步須按序完成):
+> 1. **Read** 目標 `.md` 全文 → 檔案不存在時停止，輸出: `協議檔案未找到，中止執行`
+> 2. **Override** `00_system` 部分設定
+> 3. **Execute** `<step_1>` — 禁在步驟 1 完成前執行任何協議內容
+
+---
+
+## 2. Natural Language Passthrough
+
+**Trigger**: 使用者輸入非 `/archi.` 指令文本。
+
+### 2.1 Intent Detection
+
+**Role**: 智能調度員。偵測使用者意圖，按影響級別決定直接執行或引導到命令。
+
+**判定標準**: 該修改是否影響已文件化的行為（spec.md 的介面/邏輯/場景、ui.md 的互動/結構、plan.json 的實施步驟）？
+
+| 意圖類型 | 處理 |
+|:---|:---|
+| 純對話 / 程式碼閱讀 / 架構討論 | ✅ 直接回答，利用基底規則增強 |
+| 瑣碎修改（typo/注解/格式/日誌） | ✅ 直接執行 |
+| 行為變更（邏輯/介面/型別/UI） | 🔀 引導 → `/archi.edit` + `/archi.code` |
+| Bug 修復 | 🔀 引導 → `/archi.fix` |
+| 新增功能 | 🔀 引導 → `/archi.scope` 或 `/archi.plan` |
+| 大規模重構 | 🔀 引導 → `/archi.revise` |
+
+### 2.2 Guided Dispatch (引導規範)
+
+🔀 引導時須:
+1. 一句話說明為什麼需走命令（關聯到哪個文件會受影響）
+2. 推薦具體命令 + 參數
+3. 詢問使用者是否開始
+
+> ⛔ **禁**: 先改程式碼再事後建議走命令。違反此規則須撤銷變更並重新引導。
+
+### 2.3 未納管程式碼
+
+修改對象未在 `map.json` 中註冊、無對應 Task:
+- 告知使用者該模組未納管
+- 建議 `/archi.inherit` 或 `/archi.scope` 納入
+- 使用者確認「臨時調整」後可直接修改
+
+### 2.4 基底規則
+
+所有場景（含引導和純對話）均依賴以下基底規則:
+
+| Layer | File | Role |
+|:---|:---|:---|
+| Core | `00_system.md` | 身份設定，核心原則 |
+| Tech | `02_tech_stack.md` | 技術紅線，編碼規範 |
+| Custom | `90_custom_rules.md` | 團隊特殊約束 |
+| Context | `99_context_glue.md` | 自動關聯上下文文件 |
+
+**End of Dispatcher.**
+
+> CLI 強制執行規則見 `04_cli_tools.md`。

package/dist/templates/zh-Hant/rules/02_tech_stack.md

@@ -0,0 +1,192 @@
+---
+description: Technical Standards & Technology Stack. Contains language versions, framework choices, coding conventions, naming rules, and forbidden patterns. Consult when writing code.
+globs: **/*
+applyTo: **/*
+alwaysApply: true
+---
+
+# Tech Stack & Engineering Standards: [專案名稱]
+
+> **Role:** The "Law" of the codebase. Defines tools, structure, and engineering workflows.
+> **Status:** [Active]
+> **Note:** 這是一個模板檔案，需要根據專案類型（Web/CLI/Backend/Library/Mobile 等）填充具體內容。
+> 某些章節（如 UI Protocol）僅適用於有 UI 的專案，應根據實際情況調整或刪除。
+
+## 1. Global Mandates (全局紅線)
+* **No Hardcoding:** 所有的密鑰、API地址必須使用環境變數，嚴禁硬編碼。
+* **No Dead Code:** 提交的程式碼必須是乾淨的，嚴禁保留註釋掉的程式碼塊或無用的 `TODO`。
+* **Comments for Why:** 註釋解釋「為什麼這麼做」（業務背景），而不僅僅是「做了什麼」。
+
+---
+
+## 2. Technology Selection (技術選型)
+### Core Stack
+* **Framework:** [例如：Next.js 14 (App Router) / NestJS / Express / FastAPI / Gin]
+* **Language:** [例如：TypeScript (Strict Mode) / Python 3.11+ / Rust / Go 1.21+]
+* **Styling** (如專案有 UI): [例如：TailwindCSS + Shadcn/UI / CSS Modules / Styled Components]
+* **State** (如專案有前端狀態管理): [例如：Zustand (Client) + React Query (Server) / Redux / MobX]
+* **Database** (如專案有數據層): [例如：PostgreSQL + Prisma ORM / MongoDB / SQLite / Redis]
+
+### Infrastructure
+* **Package Manager:** [例如：pnpm / npm / yarn / cargo / go mod / pip]
+* **Runtime:** [例如：Node.js 20+ / Python 3.11+ / Rust / Go 1.21+ / Bun]
+* **Build Tool:** [例如：tsup / vite / webpack / cargo / go build]
+
+---
+
+## 3. Coding & Naming Standards (程式碼與命名規範)
+### Naming Conventions
+* **Files:** [例如：`kebab-case` (e.g., `user-profile.ts` / `user_profile.py` / `user_profile.rs`)]
+* **Components/Classes:** [例如：`PascalCase` (e.g., `UserProfile` / `UserService` / `UserRepository`)]
+* **Functions/Methods:** [例如：`camelCase` (e.g., `handleSubmit`) 或 `snake_case` (Python/Rust)]
+* **Constants:** [例如：`UPPER_SNAKE_CASE` (e.g., `MAX_RETRY` / `MAX_RETRY_COUNT`)]
+* **Private Members:** [例如：`_privateMethod` (JavaScript) / `__private` (Python) / `private_field` (Rust)]
+
+### Code Patterns
+* **Export Style:** [例如：必須使用 Named Export (`export const`), 嚴禁使用 Default Export。]
+* **Type Definitions:** [例如：必須使用 `interface` 定義物件，使用 `type` 定義聯合類型。]
+* **Error Handling:** [例如：必須使用 Result 類型 (Rust) / 異常處理 (Python/Java) / 錯誤返回 (Go)]
+* **Async Patterns:** [例如：優先使用 Async/Await，避免 `.then()` 鏈式調用。]
+
+---
+
+## 4. UI Protocol: ITP v3.0 (Dual-Artifact) [可選 - 僅適用於有 UI 的專案]
+<!-- 核心 UI 描述協議 -->
+> **Note:** 如果專案沒有 UI（如 CLI、Backend API、Library），可以刪除此章節。
+
+### 4.1 Dual-Artifact Strategy (雙製品策略)
+
+UI 製品層級：
+
+| 製品 | 格式 | 讀者 | 職責 |
+|:---|:---|:---|:---|
+| `ui_concept.html` | 單檔案 HTML | 人類 (瀏覽器) | **全域視覺真相源** — 所有畫面的線框圖/著色稿 |
+| `ui_context.md` | 結構化 Markdown | AI (plan/code/audit/edit) | **AI 畫面索引** — 畫面 ID/路由/狀態/導覽關係/共享元件輕量清單 |
+| `ui.md` | ITP v3.0 DSL | AI (code/audit) | 任務級 UI 範圍聲明 — 指定本任務涵蓋的畫面/元件 |
+- `ui_concept.html` 由 `archi-ui-wireframe` Skill 生成，覆蓋專案所有使用者可見畫面；僅供人類在瀏覽器預覽
+- `ui_context.md` 由同一 Skill 同步生成，是 AI 命令讀取 UI 結構資訊的唯一入口；禁手動修改
+- `ui.md` 僅聲明「本任務負責 ui_context.md 中的哪些畫面/狀態」，禁重定義全域布局
+- code 階段以 `ui.md`（任務設計）+ `ui_context.md`（結構/導航）+ `design_tokens.json`（視覺約束）為準；同時以 `ui_concept.html` 為**唯讀視覺參考**校準布局，用**專案自身技術棧**實現等價視覺效果
+
+### 4.2 Naming (PrefixFunction)
+元件命名須遵循 `前綴+功能` 格式：
+* **Btn**: Button | **Inp**: Input | **Txt**: Text/Label
+* **Box**: Container | **Img**: Image/Icon | **List/Card/Modal**: As named.
+
+### 4.3 Syntax Structure (語法結構)
+* **Definition**: `Name [Layout] (Style/Content) -> #Interaction`
+* **Layout Keywords**: `[Row]`, `[Col]`, `[Center]`, `[Between]`, `[Fill]`, `[Grid]`
+* **Example**:
+```
+    BoxHeader [Row, Between]
+      TxtTitle [H2] (Text: "Login")
+      BtnClose [Ghost] (Icon: X) -> #CloseModal
+```
+
+### 4.4 Design Tokens (設計令牌)
+`design_tokens.json` 定義專案專屬視覺語言，由 `/archi.start` 從 Brief 生成：
+- `primitivePalette`: 原始色階（中性灰 + 品牌色）
+- `semanticTokens`: 語義色（Background/Primary/Text…）+ 字體規格
+- `layout`: 圓角/陰影/間距尺寸
+- `motion`: 動效時長/緩動/模式偏好
+- `illustration`: 圖示風格/圖示庫
+- **code 階段**: 所有顏色/尺寸/動效值須來自此檔案對應欄位，禁硬編碼魔法值
+
+### 4.5 Delta Syntax (差分更新)
+* **Usage**: 用於修改現有 UI 快照。
+* **Format**: `@Locator { + Add, ~ Modify, - Remove }`
+
+---
+
+## 5. Testing & Verification (測試與驗證)
+
+### Static Analysis (靜態分析命令)
+* **Build:** [例如：`pnpm build` / `cargo build` / `go build` / `python -m py_compile`]
+* **Type Check:** [例如：`pnpm type-check` / `mypy .` / N/A]
+* **Lint:** [例如：`pnpm lint` / `ruff check .` / `cargo clippy` / `golangci-lint run`]
+* **Format:** [例如：`pnpm format:check` / `ruff format --check` / `cargo fmt --check`]
+
+### Test Suite (測試套件)
+* **Unit:** Tool: [例如：Vitest / Jest / pytest / cargo test / go test]  Scope: [例如：Utils 工具函數、核心業務邏輯、算法]  Rule: [例如：須 Mock 外部依賴；禁對易變 UI 做快照測試]
+* **Integration:** Tool: [例如：Vitest + Testcontainers / pytest + Docker]  Scope: [例如：API→DB 寫入鏈路 / CLI 完整執行流程]
+* **E2E:** Tool: [例如：[?Web] Playwright / Cypress  [?API] Supertest / httpie  [?CLI] bats / shell script  [?Lib] 範例專案 + 自動化腳本  [?Mobile] Detox / Maestro]  Scope: [例如：[?Web] 核心使用者路徑  [?API] 關鍵 endpoint 全鏈路  [?CLI] 關鍵命令全流程  [?Lib] 公開 API 典型使用場景]
+* **Test Command:** [例如：`pnpm test` / `pytest` / `cargo test` / `go test ./...`]
+
+### Environment Scripts (環境腳本)
+> **AI Internal Tooling**: 此腳本由 AI 在 INF-01 階段基於上方命令定義自動生成，實現細節（腳本結構、失敗策略、執行方式）由 AI 自決，禁向使用者提問。按 OS 生成 `.sh` / `.ps1` 至 `[[__DOCS_DIR__]]/scripts/`。
+
+* **`[[__DOCS_DIR__]]/scripts/validate`** — 自動化質檢（AI 每次改完程式碼後執行）：Static Analysis 全項 + Test Command。
+* **`[[__DOCS_DIR__]]/scripts/dev-up`** — 拉起開發環境：Install → Build → Start Dev Server → Health Check。
+  - **Install:** [例如：`pnpm install` / `pip install -r requirements.txt` / `cargo build` / `go mod download`]
+  - **Dev Command:** [例如：`npm run dev` / `python manage.py runserver` / `cargo run` / N/A]
+  - **Health Check:** [例如：`curl http://localhost:3000/api/health` / `./bin/cli --version` / `python -c "import mylib"`]
+* **`[[__DOCS_DIR__]]/scripts/dev-reset`** — 環境重置（環境異常時執行）：Kill Processes → Clean Cache → Reinstall → Rebuild → Restart。
+
+---
+
+## 6. Deployment & Release (部署與發佈)
+### CI Pipeline (流水線)
+* **Pre-commit:** [例如：必須通過 Linter 和 Formatter 檢查（ESLint/Prettier / ruff/black / clippy / golangci-lint）。]
+* **Merge Gate:** [例如：PR 合併前必須通過所有 Unit/Integration 測試。]
+* **Build Check:** [例如：必須通過構建檢查（`npm run build` / `cargo build` / `go build`）。]
+
+### Environment (環境)
+* **Secrets:** [例如：生產環境密鑰必須通過 CI 平台配置，嚴禁提交 `.env` / `.env.local`。]
+* **Database Ops** (如專案有數據庫): [例如：Schema 變更必須使用 Migration 檔案，禁止手動修改生產庫。]
+* **Binary Distribution** (如專案是 CLI/Library): [例如：使用 GitHub Releases 發佈二進位檔案，支持多平台構建。]
+
+---
+
+## 7. Architecture & File Placement Strategy (架構與檔案歸位策略)
+### Repository Architecture (倉庫形態)
+* **Strategy:** [例如：Monorepo (Turborepo) 或 Single Repo (單體倉庫)]
+* **Workspace:** [例如：pnpm workspaces，共享依賴提升至 Root。]
+
+### Directory Structure (目錄結構)
+* **Pattern:** [Architecture Pattern Name]
+* **Philosophy**: [Architecture Philosophy]
+* **Key Paths**:
+    * `[Path_1]`: [Description]
+    * `[Path_2]`: [Description]
+* **Constraint**: [Architecture Constraints]
+
+### File Placement Rules (檔案歸位邏輯)
+> *Context*: 定義不同類型的檔案應創建在哪裡。**須依據專案類型 (Web/CLI/API/Lib) 與 `map.json` 的目錄結構自訂**，下表為佔位示例。
+> **Critical**: 建立新檔案前須查此表。此表填充後即為強制約束，禁憑 AI 預設習慣自行放置。
+
+| File Type | Placement Strategy | Example (依據專案調整) |
+| :--- | :--- | :--- |
+| **Unit Tests** | [e.g. Centralized 或 Colocation] | `__tests__/utils/date.test.ts` / `utils/date.test.ts` |
+| **Interfaces/Types** | [e.g. Near usage 或 Global types] | `types/user.d.ts` / `domain/user.entity.ts` |
+| **Assets/Images** [?UI] | [e.g. Public 或 Module assets] | `public/images` / `assets/` |
+| **Styles** [?UI] | [e.g. 按元件或全域] | `Button.module.css` / `global.css` |
+| **DTOs/Models** [?Data] | [e.g. Domain 或 Shared] | `domain/user/dto` / `models/` |
+
+---
+
+## 8. Anti-Patterns (負面清單)
+* **No Orphan .gitkeep:** 空目錄可用 `.gitkeep` 占位以便 Git 追蹤；目錄已有其他檔案時須刪除 `.gitkeep`。
+* **No Rogue File Placement:** 建立新檔案前須查 §7 File Placement Rules 表，禁憑 AI 訓練資料的預設習慣自行放置（尤其是測試檔案）。
+* **No [技術 1]:** [例如：No Redux - 本專案過重，勿用。]
+* **No [技術 2]:** [例如：No Raw SQL - 必須使用 ORM 防止注入。]
+* **No [模式 1]:** [例如：禁止在組件內部直接 fetch 數據，必須封裝在 Service 層。]
+* **No [模式 2]:** [例如：禁止使用 `any` 類型（TypeScript）/ 禁止使用 `unsafe` 程式碼（Rust）。]
+* **No [模式 3]:** [例如：禁止使用 `console.log` 生產程式碼，必須使用統一的 Logger。]
+
+---
+
+## 9. Project Conventions (專案約定)
+> 全域架構約定，由 `/archi.start` 確立。`/archi.plan` 自動繼承，任務無特殊需求時不再逐一提問。
+> 任務若需偏離約定，須在提案中明確說明偏離理由。
+
+### Error Handling (錯誤處理策略)
+* **Strategy:** [例如：Fail Fast + Form Validation / Fail Fast (stderr) / Schema Validation + Fail Fast]
+* **Rationale:** [例如：表單密集型應用，需前端即時校驗 + 後端快速失敗]
+
+### Data Flow (資料流模式) [?UI]
+* **Default:** [例如：Standard Request + SWR / Realtime (Socket) / Polling]
+* **Rationale:** [例如：大部分頁面為 CRUD 讀寫，SWR 做快取和重新驗證]
+
+### Auth & Access (認證與權限) [?Web/API]
+* **Mechanism:** [例如：JWT + RBAC / Session + Owner Only / API Key]
+* **Rationale:** [例如：多角色後台管理系統，需細粒度權限控制]