superpowers-mcp 6.3.3 → 6.3.4

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![版本](https://img.shields.io/badge/version-6.3.3-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.3.4-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將 Superpowers 技能庫與自主 Agent 工作流架構打包成獨立、高效能且安全加固的 **Model Context Protocol (MCP)** 伺服器之相關資訊與使用說明。
@@ -13,33 +13,82 @@
 
 ### 支援的環境與 Agent 平台
 
-- **MCP 原生 AI 編輯器與 IDE**：**Antigravity (AGY)**、**Cursor**、**VSCode**、**Windsurf**、**Claude Desktop / Claude Code**。
-- **CLI 工具與自主代理環境**：**Devin CLI**、**Hermes Agent**、**OpenCode**、**Kimi CLI**、**Pi CLI**、**Gemini CLI**。
+- **AI 程式碼編輯器與 IDE**：**Antigravity (AGY)**、**Cursor**、**VSCode**（GitHub Copilot）、**Devin Desktop**、**MiniMax Code Desktop**、**Codex**。
+- **AI 桌面應用與 Agent 工具**：**Hermes Desktop**、**Kimi Work**。
+- **開源與私有化 AI 平台**：**AnythingLLM**、**LibreChat**。
 
 ### 提供之 MCP 協議功能
 
-| 協議功能 | 包含項目 | 說明 |
+| 協議功能 | 包含項目 / 數量 | 說明 |
 | :--- | :--- | :--- |
-| **Tools (工具)** | `list_skills`, `read_skill` | 依需求隨時探索並載入 14 項 Superpowers 技能完整內容。 |
-| **Prompts (提示詞)** | `session-start`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` | 可在 IDE Prompts 列表直接選用之對抗式審查與子代理協調 Prompt 模板。 |
-| **Resources (資源)** | `skill://superpowers/<skill-name>` | 提供符合 MCP 標準的 Direct URI 技能讀取協議。 |
+| **Tools (工具)** | `list_skills`, `read_skill` | 依需求隨時探索、搜尋並載入技能完整內容與操作規範。 |
+| **Prompts (提示詞)** | 9 個原生 Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
+| **Resources (資源)** | 14 項技能 Direct URI | `skill://superpowers/<skill-name>`（支援 MCP 協議標準資源直讀） |
 
-### 與 AI Agent 對話
+### 與 AI Agent 對話（基礎操作）
 
 安裝或配置完成後，您的 AI Agent 將能夠自動識別並調用 `Superpowers Skills` 與 `Prompts`。
 
-**您可以這樣提問：**
+**基礎互動範例：**
+- **初始化工程規範**：「套用 `session-start` prompt」（注入 Superpowers 技能體系與工程紀律）
+- **查詢所有可用技能**：「列出所有 superpowers 技能」
+- **載入單一技能**：「使用 `read_skill` 讀取 `brainstorming` 技能並幫我分析需求」
 
-- "列出所有 superpowers 技能"
-- "使用 read_skill 讀取 brainstorming 技能，然後幫我分析這個功能的實作"
-- "套用 session-start prompt"（初始化完整的 Superpowers 工作流上下文）
-- "使用 subagent-driven-development 執行 docs/plans/feature-plan.md 的開發計畫"
+---
+
+## ⚡ 快速全域一鍵設定 (Targeted One-Click Setup)
+
+為了讓您在最短時間內啟用 Superpowers，我們提供了**精確指定、尊重環境隱私、杜絕批量侵入**的跨平台一鍵安裝工具。
+
+> [!NOTE]
+> **可在系統任何目錄下直接執行**：您不需要預先切換到特定專案目錄，也無須 clone 本儲存庫。在終端機的**任意目錄**皆可直接執行以下指令！安裝程式會自動鎖定您系統中的全域設定檔（以使用者家目錄為基準），一次設定、全域與所有專案皆可自動生效。
+
+> [!TIP]
+> **透明與零污染保護原則**：Superpowers 絕不會像惡意軟體般擅自全域掃描或批量改寫您未指定的其他編輯器。您使用哪一款 AI 工具，就執行該工具的專屬一鍵指令，完全透明、可控且安全無損（採用**原子寫入技術**，保證斷電不壞檔，且**預設零磁碟垃圾殘留**，不隨意產生 `.bak`，亦絕不影響原有其他 MCP 伺服器）。
+
+### 1. 選擇您的 AI Agent / 編輯器（一鍵精準設定）
+
+請依據您使用的客戶端，在終端機複製並執行對應指令：
+
+| Harness / 客戶端 | 支援 OS | 專屬一鍵設定指令 | 全域設定檔路徑 |
+| :--- | :--- | :--- | :--- |
+| **Antigravity (Google DeepMind)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target antigravity` | `~/.gemini/config/mcp_config.json` |
+| **Pi Desktop / Pi Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target pi-desktop` | `~/.pi/agent/mcp.json` |
+| **Cursor** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target cursor` | `~/.cursor/mcp.json` |
+| **GitHub Copilot (VS Code)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target copilot` | `Code/User/mcp.json` *(VS Code `servers` 格式)* |
+| **Hermes Desktop / Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target hermes` | `~/.hermes/config.yaml` *(Win: `%LOCALAPPDATA%\hermes`)* |
+| **Kimi Work / Kimi Code** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target kimi` | `~/.kimi-code/mcp.json` |
+| **Claude Desktop** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target claude` | `Claude/claude_desktop_config.json` |
+| **Devin Desktop (原 Windsurf)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target devin` | `~/.config/devin/mcp_config.json` *(或 `windsurf`)* |
+
+*(若偏好使用 Bun，指令可加上 `--bun`，例如 `npx -y superpowers-mcp setup --target cursor --bun`)*
+
+---
+
+### 2. 透過 Curl / PowerShell 一鍵設定
+
+- **macOS / Linux（透過 Curl 指定目標）：**
+  ```bash
+  curl -fsSL https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.sh | bash -s -- --target cursor
+  ```
+
+- **Windows（透過 PowerShell 指定目標）：**
+  ```powershell
+  & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.ps1))) -Target cursor
+  ```
+
+#### 常用進階參數：
+- `--dry-run`：預覽即將修改的檔案與配置內容，不實際寫入磁碟。
+- `--remove`：從指定目標 Harness 安全移除 Superpowers 配置。
+- `--backup`：修改前建立時間戳記 `.bak` 備份檔（預設為關閉，維持系統純淨零殘留）。
+- `--bun`：在產生的設定中改用 `bunx` 啟動，享受極速啟動效能。
+- `--target <name>`：指定目標名稱（支援常用別名，如 `code`、`vscode`、`kimi-code` 等）。
 
 ---
 
-## 🛠️ MCP 配置
+## 🛠️ 手動 MCP 配置 (Manual Configuration)
 
-將以下設定加入您的 IDE（例如 Cursor, Antigravity, 或 VSCode 的 MCP 設定）。
+若您偏好手動設定，可將以下設定加入您的 IDE 或 MCP 客戶端（例如 Cursor、Antigravity、VSCode、AnythingLLM 等）。
 
 ### 方法：NPX / BUNX（推薦）
 
@@ -67,232 +116,96 @@
 
 ---
 
-## 💡 常用技能與情境
+## 🔄 技能編排與工作流流水線 (Skill Compositions & Pipelines)
 
-| 技能名稱 | 社群推薦使用情境 | 核心價值 |
-| :--- | :--- | :--- |
-| `brainstorming` | 啟動新功能前，探索需求與設計。 | 防止 AI 直接衝進去寫 code。 |
-| `writing-plans` | 進行多檔案重構或複雜遷移前。 | 建立明確的執行藍圖。 |
-| `systematic-debugging` | 遇到任何報錯或行為異常時。 | 強制執行「根因分析」而非亂猜。 |
-| `test-driven-development` | 實作具邏輯挑戰的功能時。 | 確保代碼隨附測試，實現 Red-Green-Refactor。 |
-| `verification-before-completion` | 聲稱「修好了」或「做完了」之前。 | 證據導向的完工確認。 |
+當執行多步驟的複雜任務時，請直接使用以下**一鍵端到端工作流**，AI 會自動按標準工程步驟引導（詳見完整指南：[`docs/skill-compositions.zh-TW.md`](docs/skill-compositions.zh-TW.md)）：
 
----
+### 1. 端到端新功能開發管線 (Feature Development Pipeline)
+```
+brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
+```
+- **一鍵指令：**「請套用 `feature-pipeline`，幫我開發 [新功能名稱]」
+- **流程特色：** 需求確認 (Spec) ➔ 任務拆解 (Plan) ➔ Worktree 隔離 ➔ 獨立 Subagent + TDD 實作 ➔ 全套測試驗證 ➔ 專家代碼審查 ➔ 分支收尾。
 
-## 🔄 推薦的指令 (Command Sequences)
+### 2. 結構化多點除錯管線 (Structured Troubleshooting Pipeline)
+```
+systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
+```
+- **一鍵指令：**「請套用 `structured-debug`，幫我排查這個報錯：[貼上錯誤訊息]」
+- **流程特色：** 根因分析拆解假說 ➔ Worktree 隔離平行排查 ➔ 多 Agent 驗證 ➔ 編寫失敗測試並修復 ➔ 全套迴歸驗證 ➔ 審查結果解決 ➔ 分支合併收尾。
 
-### 1. 新功能開發
-1. 「用 read_skill 讀取 brainstorming 技能，確認需求與架構。」
-2. 「用 read_skill 讀取 writing-plans 技能，建立具體的實作步驟。」
-3. 「用 read_skill 讀取 test-driven-development 技能，以 TDD 方式實作功能。」
-4. 「用 read_skill 讀取 verification-before-completion 技能，跑測試確認一切正常。」
+### 3. 動態技能導引 (Dynamic Workflow Guide)
+- **一鍵指令：**「請套用 `skill-composition`，我目前的情境是 [重構/遷移/接手舊專案]」
+- **流程特色：** 針對大型重構、舊代碼防護網建立或團隊新人上手，動態推薦最佳步驟：
+  - **大型重構與遷移 (Pipeline 3)：** `brainstorming` ➔ `writing-plans (skeleton-first)` ➔ `using-git-worktrees` ➔ `subagent-driven-development` ➔ `verification-before-completion` ➔ `requesting-code-review` ➔ `finishing-a-development-branch`
+  - **舊專案工程防護網 (Pipeline 4)：** `brainstorming` ➔ `writing-plans` ➔ `test-driven-development (characterization)` ➔ `systematic-debugging` ➔ `verification-before-completion`
 
-### 2. 緊急修復 (Hotfix)
-1. 「用 read_skill 讀取 systematic-debugging 技能，定位目前問題的根因。」
-2. 「用 read_skill 讀取 test-driven-development 技能，寫一個失敗測試再修復它。」
-3. 「用 read_skill 讀取 verification-before-completion 技能，驗證修復結果。」
 
 ---
 
-## 📋 支援技能總覽 (共 14 個)
-
-為了解決技能太多難以選擇的問題，我們將這 14 個技能依照軟體開發的 6 個階段進行了分類：
-
-### 🚀 1. 規劃與設計 (Planning & Design)
-- `brainstorming`: 軟體設計與需求分析流程
-  - Visual Companion 瀏覽器視覺化設計審查工具（just-in-time 觸發）
-- `writing-plans`: 建立詳細的實作計畫
-
-### 💻 2. 開發與除錯 (Implementation & Debugging)
-- `executing-plans`: 執行已建立的實作計畫
-- `test-driven-development`: TDD（測試驅動開發）工作流
-- `systematic-debugging`: 系統性除錯與根因分析
-
-### 🛡️ 3. 品質驗證與審查 (Quality & Review)
-- `verification-before-completion`: 完工前的證據導向驗證
-- `requesting-code-review`: 發起程式碼審查的預先檢查
-- `receiving-code-review`: 接收與處理程式碼審查回饋
-- `finishing-a-development-branch`: 收尾開發分支與整合
-
-### 🌿 4. 版本控制 (Version Control)
-- `using-git-worktrees`: 使用 Git Worktrees 管理多重分支
-
-### 🤖 5. 代理進階控制 (Advanced Agent Controls)
-
-這是特別針對在支援多重代理 (Multi-Agent) 協作或具備強大推論能力的 IDE（如 Antigravity 或 Cursor）中所設計的高階操作技巧。
-
-- **`subagent-driven-development`**: 驅動子代理執行複雜任務
-  - **具體用法**：適用於「執行已規劃好的詳細計畫」。針對每一個小任務，AI 會派發全新的「實作代理」去寫 Code，完成後啟動合併的 **task reviewer**（規格 + 品質一次審查），並在最後執行 **whole-branch final review**（全分支最終審查）。在執行前還會進行 **Pre-Flight Plan Review**，掃描任務之間的潛在衝突。計畫在 plan-scoped 工作區（`.superpowers/sdd/<plan>/`）執行；控制器對衝突直接裁決並記錄於 ledger（rulings），不再停擺等待；相同形狀的小任務會批次合併為單次派發。
-  - **模型選擇**：根據任務複雜度選擇子代理模型 — 機械性工作用低成本模型，架構設計與細微併發變更需要強大模型。
-  - **指令範例**：「用 read_skill 讀取 subagent-driven-development 技能，然後依照 docs/plans/feature-plan.md 的內容逐一派發子代理實作。」
-- **`dispatching-parallel-agents`**: 派發平行代理同步執行任務
-  - **具體用法**：適用於「同時處理多個互不干擾的獨立問題」（例如 3 個無關聯的 Bug，或 3 個獨立的網路查詢需求）。AI 會切換為平行處理的思維模型，將各個問題視為獨立專案同時處理，避免記憶混亂（Context 污染）並加速多任務產出。
-  - **偵錯範例**：「用 read_skill 讀取 dispatching-parallel-agents 技能，然後派發 3 個平行代理去分別排查 A、B、C 三個獨立測試報錯。」
-  - **查詢範例**：「用 read_skill 讀取 dispatching-parallel-agents 技能，然後平行查詢 React 19 新特性、Vue 3.5 更新重點、Svelte 5 的 Runes 系統，各自獨立摘要。」
-
-### ⚙️ 6. 系統與自定義 (Meta & Customization)
-- `using-superpowers`: Superpowers 核心操作指南與自我檢查
-- `writing-skills`: 撰寫與擴充新的自訂技能
+## 📋 支援技能總覽 (14 項核心技能與適用情境)
+
+為了讓您能快速選用合適的技能，我們將 14 個技能依照軟體開發生命週期 (SDLC) 進行分類，並整合其核心用途與社群推薦使用情境：
+
+| # | 開發階段 (Phase) | 技能名稱 (Skill Name) | 它是幹嘛用的？ (Purpose & Core Value) | 推薦使用情境 (Recommended Scenario) |
+| :-: | :--- | :--- | :--- | :--- |
+| 1 | **🚀 規劃與設計** | **`brainstorming`** | **需求澄清與設計探索**：在寫代碼前探索架構方案、釐清邊界，產出 Spec。內建 Visual Companion 瀏覽器即時設計審查。 | 啟動任何新功能或大改版前，防止 AI 直接衝進去寫 code。 |
+| 2 | **🚀 規劃與設計** | **`writing-plans`** | **實作計畫拆解**：將設計規格分解為獨立可測試的原子任務清單，標註檔案契約與 Recommended Skill。 | 進行多檔案重構、複雜遷移或大型開發前，建立清晰藍圖。 |
+| 3 | **💻 開發與實作** | **`executing-plans`** | **會話內計畫執行**：在當前會話中依據計畫逐步批次執行任務，並於關鍵節點進行檢查點審查。 | 不需要開多個 Subagent 時的連續計畫執行。 |
+| 4 | **💻 開發與實作** | **`subagent-driven-development`** | **子代理驅動開發 (SDD)**：為各任務派發乾淨上下文的獨立 Subagent 實作，並在任務間發起雙層對抗式代碼審查。 | 推薦的複雜計畫執行方式，防止上下文污染並提高精確度。 |
+| 5 | **💻 開發與實作** | **`test-driven-development`** | **測試驅動開發 (TDD)**：嚴格執行「紅燈（寫失敗測試）➔ 綠燈（最小實作）➔ 重構」循環。 | 實作邏輯複雜功能時，確保代碼隨附測試且具備回歸防護。 |
+| 6 | **🔍 除錯與排查** | **`systematic-debugging`** | **系統性除錯與根因分析**：將問題拆解為可測試的假說並設計驗證實驗，徹底杜絕盲猜式亂改。 | 遇到任何報錯、異常行為或難以重現的 Bug 時。 |
+| 7 | **🛡️ 品質與驗證** | **`verification-before-completion`** | **完工前證據驗證**：強制執行全專案完整測試套件、型別檢查與 Linter，確認零迴歸。 | 聲稱「修好了」或「做完了」之前，提供完工鐵證。 |
+| 8 | **🛡️ 品質與驗證** | **`requesting-code-review`** | **發起代碼審查**：產生 Review Package（差異與報告），主動從架構與代碼品質等多維度進行嚴格審查。 | 完成任務或提交 PR 前，主動尋求多維度架構與品質檢查。 |
+| 9 | **🛡️ 品質與驗證** | **`receiving-code-review`** | **處理審查反饋**：系統性評估審查意見、修復問題並記錄裁決理由，確保每一條 Finding 均被妥善處理。 | 收到代碼審查反饋時，進行結構化修復與記錄。 |
+| 10 | **🛡️ 品質與驗證** | **`finishing-a-development-branch`** | **分支整合與收尾**：驗證通過後進行分支合併/PR、清理 Git Worktree 與刪除暫存分支，完成乾淨交付。 | 功能開發完成後，乾淨整合至主分支並清理工作區。 |
+| 11 | **🌿 版本控制** | **`using-git-worktrees`** | **Git Worktree 物理隔離**：為功能開發或平行調查建立獨立工作目錄，防止檔案衝突與環境污染。 | 同時進行多個任務或多 Agent 平行除錯時。 |
+| 12 | **🤖 進階調度** | **`dispatching-parallel-agents`** | **並行代理調度**：在隔離環境中同時派發多個 Subagent 平行驗證獨立假說或處理多個子任務。 | 多個測試同時失敗，需要加速並行排查根因時。 |
+| 13 | **🤖 進階調度** | **`using-superpowers`** | **Superpowers 基礎紀律**：MCP 入口技能，引導 Agent 在任何任務前主動搜尋並載入對應技能規範。 | 開啟對話時自動載入，規範 AI 的行為準則。 |
+| 14 | **🤖 進階調度** | **`writing-skills`** | **技能撰寫與維護**：規範如何為團隊建立、測試與封裝新的 Superpowers 技能。 | 需要擴充專屬新技能或更新既有技能時。 |
 
 ---
 
 ## 🆕 最近更新
 
-### v6.3.2 (最新版)
-
-- **writing-plans — 雙計畫形態（Two Plan Shapes）與骨架優先（Skeleton-First）**：
-  - `skills/writing-plans/SKILL.md` 加入 **Two Plan Shapes** 路由機制（`task-by-task` 預設模式 vs `skeleton-first` 骨架優先），在撰寫計畫前提早決定架構模型。
-  - 新增 [`skills/writing-plans/skeleton-first-plans.md`](skills/writing-plans/skeleton-first-plans.md) 定義 Walking Skeleton（Task 1 先完成貫穿所有子系統的真實薄切片）、契約式任務（Task Contracts，嚴格定義 Consumes/Produces 接口與可觀測驗收標準，不預寫代碼腳本）與 `Tier: mechanical | judgment` 標記。
-- **subagent-driven-development (SDD) — 波次派發（Wave Dispatch）與並行工作樹協議**：
-  - 控制器在衝突掃描階段針對 skeleton-first 計畫生成 **DISPATCH PLAN**，將檔案互斥且無未完成介面依賴的任務組成波次並行派發。
-  - **並行工作樹協議（Parallel Worktree Protocol）**：並行任務各於專屬 `.worktrees/task-<N>` 執行，按計畫順序依次合併；若遇衝突或驗證失敗，自動 rebase 並喚醒 implementer 自行修復。
-  - Step 5 增加完工後的 `Plan holds` / `Amendment:` 檢查行，確保並行在途任務順利收斂，並將介面變動直接傳遞給後續任務。
-- **SDD — Tier 驅動模型分派**：
-  - SDD 控制器與 `implementer-prompt.md` 嚴格遵循計畫中的 `Tier:` 標記（`mechanical` → 快速經濟型模型；`judgment` → 標準中階模型），大幅節省 token 且不再重複審議。
-- **writing-skills — 二進位安全加固（`render-graphs.js`）**：
-  - 改用 `execFileSync('dot', ['-Tsvg'], ...)` 徹底杜絕 shell 注入，設置 10MB 緩衝上限，支援 Windows CRLF（`\r?\n`）換行匹配與 `winget` 安裝提示。
-- **測試與驗證**：MCP 協定、邊界安全、SDD Bash（11 項斷言）、PowerShell（70 項斷言）及 Graphviz 渲染測試全數 100% 通過。
-
-### v6.3.1
-
-- **SDD 工作區歸屬標記與實體路徑正規化**：`sdd-workspace`（Bash）與 `sdd-workspace.ps1`（PowerShell）改用 `plan-path` 歸屬標記與標準化實體路徑（`pwd -P` 與動態 `pwd` 偵測）。同名 plan（如 `docs/alpha/plan.md` 與 `docs/beta/plan.md`）會自動解析為獨立的 `.superpowers/sdd/` 工作區，杜絕產物與進度覆蓋。
-- **SDD 審查包範圍機械守衛**：`review-package` 與 `review-package.ps1` 強制校驗 `git merge-base --is-ancestor BASE HEAD` 與 commit 數量大於 0（錯誤時 exit 3），防止空範圍或倒置範圍造成審查假綠燈。
-- **執行權限剝離韌性**：`task-brief` 與 `review-package` 改以 `"${BASH:-bash}"` 調用，在解壓縮或跨系統搬移丟失 `+x` 權限時依然能穩定執行。
-- **TDD 全套件驗證下限**：`skills/test-driven-development/SKILL.md` 明確規定任務完成前必須跑過全專案測試指令（如 `npm test`、`pytest`、`cargo test`）。
-- **Code Review 防幽靈變更**：`skills/requesting-code-review/SKILL.md` 將多 commit 審查起點錨定為 `git merge-base origin/main HEAD`，消除 main 推進引發的幽靈刪除。
-- **Brainstorming 工具鏈決策門禁**：`skills/brainstorming/SKILL.md` 在設計展示階段主動詢問工具鏈配置並記錄於 `Global Constraints`。
-- **測試擴充**：新增 `tests/sdd/test-sdd-workspace.sh`（11 項斷言）並擴充 PowerShell 套件（70 項斷言）。
-
-### v6.3.0
-
-- **對齊上游 obra/superpowers v6.3.0** — 採用所有適用改進，保留本 fork 的安全強化與 PowerShell 支援。
-  - **brainstorming — 三路分類流程（three-path router）**：每個請求先分類為 `spike` / `bounded` / `architectural`；流程深度隨任務規模調整，但審批門檻永遠不變。隱藏複雜度會在執行途中升級路徑——絕不降級。
-  - **subagent-driven-development — 裁決而非停擺（rulings, not stalls）**：衝突、歧義與計畫缺陷由控制器直接裁決並記錄於 ledger（`Ruling: ...`），不再等待人類；僅四種明列情況會停止執行。Pre-flight 衝突掃描產出 ledger 表格，相同形狀的小任務批次合併為單次派發，子代理等待改用有界區間，三個 prompt 都帶有 no-subagents 契約。
-  - **Hermes Agent 支援**：新增 `hermes-tools.md` 參考檔，將技能動作對應到 Hermes 工具（`delegate_task`、`skill_view` 等）。
-  - **Codex**：V1/V2 多代理差異、`followup_task` 修復輪恢復、事件訂閱式 `wait_agent` 指引。
-  - **writing-plans**：計畫範本新增 `Spec:` 欄位。
-  - **finishing-a-development-branch**：worktree 移除被拒時的處理程序——絕不擅自 `--force`。
-- **雙代理 code review 修復**：merged path 下「Commit them to \<branch\>」不再讓檔案遺留在 base branch 之外（finishing-a-development-branch）；`sdd-workspace.ps1` 的 slug 推導在所有平台與 `basename` 一致（`PLAN.MD` 維持 `PLAN.MD`）。
-- **刻意未採用**：上游 v6.3.0 的 server 簡化（移除 loopback-only 綁定、`O_NOFOLLOW` 讀取、nonce CSP、本地品牌 SVG）——本套件保留加固版 server；上游刪除 `.ps1` 及轉為 plugin-only 架構亦不適用於本 MCP server 佈局。
-- **測試**：MCP 流程、render-graphs（8 斷言）、完整 PowerShell 套件（64 斷言）全部通過。
-
-### v6.2.4
-
-- **對齊上游 — brainstorm 持久化 session**：搭配 `--project-dir` 時，companion 現在會把 session 金鑰持久化到 `.superpowers/brainstorm/.last-token`（僅擁有者可讀、已列入 .gitignore），與 `.last-port` 並存並在重啟後重用——已開啟的瀏覽器分頁在重啟後依然保持連線，無需重新分享 URL。暫存 `/tmp` session 仍維持每次啟動輪換金鑰；明確設定的 `BRAINSTORM_TOKEN` env 依然優先且永不寫入檔案。若要強制輪換，請在停止伺服器後刪除 `.last-token`。
-- **Token 檔讀取路徑加固**（`readPrivateFile`）：symlink 或多重連結的 `.last-token` 現在會被拒絕，不再被採納為 session 金鑰；讀取透過 `O_NOFOLLOW` fd 進行，身份複查並收緊為 0600——補上與已加固寫入路徑之間的不對稱（由獨立資安審查發現）。
-- **可診斷性**：token 檔寫入失敗現在會記錄 `Failed to write private token file:`，不再靜默退化為每次啟動輪換金鑰。
-- **start-server.ps1 環境衛生**：無 `--project-dir` 的暫存啟動不再繼承呼叫端 pwsh session 中殘留的專案金鑰/埠號。
-- **測試**：companion 套件現為 31 個斷言——重啟後金鑰持久化、預置檔原樣採用、symlink token 檔被拒絕、無 token 檔時仍輪換；測試清理具失敗安全性（try/finally）。PowerShell 套件斷言 `.last-token` 與伺服器提供之金鑰一致。
-
-### v6.2.3 (最新版)
-
-- **Brainstorm Visual Companion 強化 (`server.cjs`)**：本機 loopback 限定的 HTTP+WebSocket 伺服器可安全處理檔案系統競態（content 目錄被刪除或畫面檔消失時降級為等待頁 / 404）；watcher 在目錄刪除重建後自動自癒（Linux inotify + macOS FSEvents）。WebSocket handshake 依 RFC 6455 驗證，控制訊框上限 125 bytes，並加入 idle/partial-frame deadline，滿額時淘汰最舊連線。套用 nonce CSP、每次啟動輪換金鑰、畫面/技能/事件大小上限與私有 state 檔案。
-- **`/files/` double-`writeHead` 崩潰修復**（subagent review 發現）：改為先讀檔再送 headers，並以 `O_NOFOLLOW` + fd 級 `fstat` + 大小上限關閉 check-then-read 的 TOCTOU。
-- **程序生命週期安全**：`start-server.sh/.ps1` 在送出訊號前先驗證 PID 確實是本 session 的 brainstorm server（server-instance-id + cmdline 檢查，與 stop-server 一致）；`stop-server.sh` 刪除暫存 session 前先做路徑正規化，`/tmp/../` 手法無法逃出暫存根目錄；相對 `--project-dir` 預先解析為絕對路徑；`server-instance-id` 改以無 BOM 寫入，Windows PowerShell 5.1 跨 shell 身份檢查不再失效。
-- **SkillsManager 強化**：POSIX 上以 `O_NOFOLLOW` 讀取技能檔（關閉 symlink 置換的 TOCTOU）；重新掃描失敗時回傳最後良好快取而非污染為空；名稱含連續句點（如 `a..b`）的技能現在可被查詢——查詢純走 Map、永不觸碰檔案系統。
-- **MCP 協定完善**：資源 URI 的畸形百分比跳脫回傳 `InvalidRequest` (-32600)，不再洩漏內部錯誤。
-- **依賴**：以已驗證的 exact override 固定 `hono` 4.13.0、`@hono/node-server` 2.0.11、`fast-uri` 4.1.2（解決相關公告）。`npm audit`：**0 漏洞**。
-- **測試套件**：`npm test` 會先建置，再執行 JavaScript 邊界/安全、MCP 流程與 companion 回歸測試。63 個斷言的 PowerShell 套件改由 `tests/powershell/run-tests.sh` 分開執行；沒有 `pwsh` 時會跳過。
-- **獨立審查**：已以每次啟動輪換認證金鑰、僅限 loopback 的 HTTP、nonce CSP、有界讀取、私有 state 寫入與跨平台確定性測試，處理安全與正確性審查發現。
-
-### v6.2.2
-
-- **Symlink 遍歷防護**：`SkillsManager.readSkillContent()` 現在會先使用 `fs.realpath` 將路徑正規化再檢查邊界，防止透過 symlink 任意讀取檔案；`getSafeSkillsPath` 也會阻擋危險的系統目錄前綴。
-- **相容性與協定**：新增 frontmatter 與技能內容的 UTF-8 BOM 支援，並依 RFC 3986 對包含空格或特殊字元的 resource URI 強制進行編碼與解碼。
-- **正確性與測試**：強制重新載入現在會清除內容快取；併發重新載入的鎖定更安全；多行 YAML 描述同時接受 tab 與空格縮排；新增 `tests/edge_cases_test.js` 覆蓋這些安全性與快取行為。
-
-### v6.2.1
-
-- **PowerShell 腳本測試套件**：新增 `tests/powershell/`，橫跨 `sdd-workspace.ps1`、`task-brief.ps1`、`review-package.ps1`、`find-polluter.ps1` 與 brainstorm `start-server.ps1`/`stop-server.ps1` 生命週期，共 63 個 assertion。使用 `tests/powershell/run-tests.sh` 執行；未安裝 `pwsh` 時會自動跳過。
-- **`stop-server.ps1` 跨平台修正**：`Get-CimInstance Win32_Process` 僅 Windows 可用，腳本現在在 Unix 上改用 `ps` 以正確檢查 server-id，macOS/Linux 不再出錯。
-- **清理**：移除已無用的 `skills/using-superpowers/references/copilot-tools.md`（上游已在 v6.2.0 中刪除，本地也沒有任何引用）。
-
-### v6.2.0
-- **上游同步 obra/superpowers v6.2.0**：同步上游所有技能的改進，同時保留本地的安全性強化與 PowerShell 輔助腳本。
-  - **subagent-driven-development 重構**：採用計畫範圍工作區（`.superpowers/sdd/<plan>/`），並行計畫之間的產物再也不會互相讀寫。改為可續接的 review-fix 迴圈，內建五輪熔斷機制，並新增修復後複審專用的 `re-review-prompt.md`。
-  - **test-driven-development**：`testing-anti-patterns.md` 由上游的 `writing-good-tests.md` 取代。
-  - **finishing-a-development-branch**：採用上游重寫版（包含與本地先前修補相同的 worktree 路徑捕獲修復；分支丟棄現在需要明確要求才會執行）。
-  - **技能全面精簡**：移除多個 `SKILL.md` 中的回顧與說服性段落，降低 prompt token 佔用。
-  - **gemini-tools.md**：還原為上游更新版；`visual-companion.md` 新增 Gemini CLI 啟動章節。
-- **PowerShell 一致性修復**：
-  - 所有 SDD `.ps1` 腳本移植到新的計畫範圍 `PLAN_FILE` 介面；`find-polluter.ps1` 移植了 bash 版的 `./` 前綴與 `**/` 收縮修復。
-  - **Exit code 一致性**：修復 `$ErrorActionPreference = "Stop"` 下 `Write-Error` 變成終止錯誤、導致預期 exit code 被吞掉的問題 — 驗證失敗現正確回傳 2、找不到任務回傳 3，與 bash 腳本一致。
-  - **`sdd-workspace.ps1` slug 推導**：只剝除尾端的 `.md`（與 bash `basename` 一致），不再剝除任意副檔名。
-- **版本對齊**：`package.json`、`package-lock.json` 與 MCP server 握手版本現統一為 6.2.0。
-
-### v6.0.3
-- **命令注入修復**：將 brainstorming Visual Companion 伺服器 (`server.cjs`) 中 `BRAINSTORM_OPEN_CMD` 的啟動方式從 `cp.exec()` 改為 `cp.execFile()`。舊版程式會將環境變數與 URL 透過 shell 串接執行；新版改以 argv 陣列傳遞參數，徹底消除 shell metacharacter 注入風險。
-- **依賴安全性 (overrides)**：在 `package.json` 中新增 `overrides` 區塊，強制設定間接依賴的最低版本：
-  - `@hono/node-server`: 1.19.14 → **2.0.11** — 修復 Windows 上 serve-static 經由編碼反斜線的路徑遍歷漏洞 ([GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9))
-  - `fast-uri`: 3.1.2 → **4.1.1** — 修復 IDN 正規化的主機混淆 ([GHSA-4c8g-83qw-93j6](https://github.com/advisories/GHSA-4c8g-83qw-93j6)) 與反斜線權限定界符 ([GHSA-v2hh-gcrm-f6hx](https://github.com/advisories/GHSA-v2hh-gcrm-f6hx))
-  - `body-parser`: 2.2.2 → **2.3.0** — 修復無效 limit 值導致大小限制被靜默停用的 DoS 漏洞 ([GHSA-v422-hmwv-36x6](https://github.com/advisories/GHSA-v422-hmwv-36x6))
-- **上游錯誤修正**：
-  - `find-polluter.sh`：現在支援 `./` 前綴路徑（不只是裸路徑），並透過收縮 `**/` 模式支援頂層測試檔案
-  - `finishing-a-development-branch/SKILL.md`：在 Step 5 切換目錄前預先捕獲 `WORKTREE_PATH`，修復清理階段的回歸錯誤。新增 Option 2 的 detached HEAD 推送變體
-
-### v6.0.2
-- **模組化拆分與效能提升**：
-  - **職責解耦**：將檔案存取、YAML 解析與快取邏輯抽離至獨立模組 [`src/skills-manager.ts`](src/skills-manager.ts)，主程式 [`src/server.ts`](src/server.ts) 專注於 MCP 路由註冊。
-  - **O(1) 雙向快取**：引入大小寫不敏感的 Map 雙向鍵值快取（以技能名與目錄名為 Key），將原本 $O(N)$ 的陣列雙重遍歷優化為 $O(1)$ 的直接讀取。
-  - **非同步 I/O 管線**：全面以 `fs/promises` 代替同步磁碟操作，搭配 `Promise.all` 併發枚舉，釋放 Node.js 事件循環阻塞。
-  - **Markdown 內容快取**：快取已剝離 YAML frontmatter 的技能文檔，避免工具頻繁調用時對硬碟的重複讀寫損耗。
-- **安全性深度防禦**：
-  - **防範 ReDoS 攻擊**：棄用非貪婪正則，重構為「逐行 Frontmatter 解析器」，規避了惡意/損壞 Markdown 導致的 CPU 回溯鎖死風險，且支援了 YAML 多行 `description` 欄位。
-  - **路徑遍歷（Path Traversal）防禦**：對 `skill_name` 輸入參數使用英數白名單篩選（`/^[a-zA-Z0-9-_]+$/`）。
-  - **絕對路徑防洩露**：安全捕獲原生 I/O 錯誤，隱蔽主機真實實體路徑與帳號名稱，回傳通用 `McpError`。
-  - **環境路徑與指令碼加固**：檢測 `SKILLS_PATH` 防範根目錄惡意注入；修復 `esbuild.js` 在 Windows 上的 `chmodSync` 崩潰問題，並在 `copy-skills.js` 中跳過符號連結 (Symlink) 杜絕遞迴拷貝死循環。
-
-- **上游安全更新同步**：套用來自 obra/superpowers v6.1.1 的安全加固：
-  - **WebSocket 影格長度限制**：在 `decodeFrame()` 中新增 `MAX_FRAME_PAYLOAD_BYTES (10 MB)` 檢測，防止超大型影格攻擊（CWE-789）。
-  - **硬連結限制**：在 `isRegularFileInsideContentDir()` 中加入 `stat.nlink !== 1` 檢測，防止透過硬連結 (Hardlink) 繞過路徑遍歷。
-  - **提取 `escapeHtmlText()`**：將行內的 `escHtml` 閉包提取為可重複使用的具名函數，以確保 HTML 逸出的一致性。
-  - **URL 解析重構**：抽離出 `pathnameOf()` and `queryKey()` 輔助函數，減少 `handleRequest()` 中的重複 URL 解析。
-- **`review-package` 路徑解析修正**：修復 `sdd-workspace` 呼叫，改用絕對路徑解析 (`$(cd "$(dirname "$0")" && pwd)`) 以防止與工作路徑 (CWD) 依賴相關的調用失敗。
-- **Windows 原生輔助腳本**：新增 Visual Companion 啟動/關閉、SDD review/task helper，以及 systematic-debugging polluter detection 的 PowerShell wrapper。
-- **技能文檔改進**：
-  - `subagent-driven-development`：新增 `plan-mandated` 審查指引，以處理計畫之間的衝突。
-  - `writing-skills`：結合字詞測試的實證，強化「禁止撰寫步驟清單 (recipes) 技能」的指引。
-  - `test-driven-development`：修正表格格式以提升清晰度。
-  - `writing-skills/anthropic-best-practices`：更新圖片的 CDN 網址。
-- **`helper.js` 註解對齊**：新增 4 個說明的行內註解以對齊上游文檔。保留 DOM 安全的 `showTombstone()` 實作（無 `innerHTML` 退化）。
-- **清理**：移除了已廢棄的 `walkthrough.md` (v5.1.0 升級指南)。
-
-### v6.0.1
-- **安全性修復 — Reflected XSS (#2)**: 修復 `skills/brainstorming/scripts/server.cjs` 中的伺服器端反射型跨站腳本漏洞。原本 `bootstrapPage()` 使用使用者提供的 `keyFromQuery` 參數（雖已通過 `timingSafeEqualStr` 驗證），現改為使用伺服器端 `TOKEN` 常數，徹底消除使用者可控資料進入 HTML 回應的風險。行為完全不變（驗證後的值相同）。
-
-### v6.0.0
-- **同步上游 obra/superpowers v6.1.1**: 大規模同步，引入上游對所有技能的改進。
-- **subagent-driven-development 流程改造**: 將原本的兩階段審查（規格 → 程式碼品質）合併為單一 **task reviewer** 子代理，並在最後增加 **whole-branch final review**。新增 **Pre-Flight Plan Review** 在執行前掃描任務衝突。新增 **Model Selection Guidance** 以最佳化成本與回合數。
-- **using-superpowers 簡化**: 移除平台特定說明與 Graphviz 圖表，改為 **各平台獨立參考檔案**（新增 `antigravity-tools.md`、`pi-tools.md`，更新 `codex-tools.md`），更乾淨地支援多種 AI 環境。
-- **brainstorming Visual Companion**: 改為 **just-in-time 觸發** — 不再預先詢問，只在真正需要視覺呈現時才提議。
-- **型別安全與程式碼品質**: 修正 `server.ts` 中的 `Record<string,string>` 型別強轉為正確的 `typeof` 守衛。以安全的 DOM 方法取代殘餘的 `innerHTML`。移除冗餘檢查與囉嗦註解。
-
-### v5.1.2
-- **安全性強化**: 移除 `skills/brainstorming/scripts/helper.js` 中最後一個 `innerHTML` 用法，以安全的 DOM 創建方法取代 — 現在整個程式庫 zero `innerHTML`。
-- **依賴安全性**: 升級 `hono` 從 `4.12.23` 至 `4.12.26`，修補 5 個安全公告，包括 CORS origin reflection、Lambda body-limit bypass 和 Set-Cookie header merging。
-- **乾淨狀態**: 所有 37 個 Dependabot 安全公告與 npm audit 警告全部解決 — 零未修補漏洞。
-
-### v5.1.1
-- **資安檢測與加固**: 進行了專案發布前的全方位安全性審查，並更新 `.gitignore` 設定以防未來潛在的金鑰與敏感環境變數檔案外洩。
-- **漏洞修補 (Patches)**: 修復了 brainstorming 技能中 Visual Companion (`helper.js`) 的 DOM XSS 漏洞，將不安全的 `innerHTML` 替換為安全的 DOM 操作 API；同時將 `path-to-regexp` 套件安全升級至 `8.4.2` 以解決高風險的 ReDoS 漏洞。
-- **開發依賴升級**: 將 `esbuild` 套件版本升級至 `0.28.1`。
-
-### v5.1.0
-- **輕量化行內自我審查 (Inline Self-Review)**: 在 `brainstorming` 和 `writing-plans` 中，將開銷巨大（約 25 分鐘）的子代理審查循環（Spec Review 與 Plan Review）替換為更高效的行內自我審查清單，消除子代理帶來的額外資源消耗與等待時間。
-- **Git Worktree 機制重構**: 重寫了 `using-git-worktrees` 與 `finishing-a-development-branch` 技能，引入 `detect-and-defer`（檢測與委派）機制，優先委派給 AI 編輯器（如 Claude Code）的原生 worktree 工具，並能安全地 fallback 到 git 指令。
-- **Token 消耗最佳化**: 移除了所有技能檔案中的 `Integration` 區塊，減少載入時的 Token 佔用，提高執行效率。
-- **程式碼審查角色合併**: 將獨立的 `code-reviewer` 代理角色直接合併至 `requesting-code-review` 技能中。
-
-### v4.3.2
-- **安全性**: 修復 brainstorming Visual Companion 中的 XSS 漏洞
-- **文件**: 更新 README 和 SECURITY，修正版本資訊
-
-### v4.3.0
-- 初始 MCP 伺服器實作
-- 從原始 Superpowers 遷移 14 個核心技能
+### v6.3.4 (最新版)
+
+- **Universal One-Click 全域安裝引擎 (`src/setup-runner.ts`, `scripts/`)**：
+  - 支援 8 大主流 AI 開發環境的一鍵零依賴配置：Antigravity、Pi Desktop / Pi Agent、Cursor、GitHub Copilot (VS Code)、Hermes Desktop / Agent、Kimi Work / Kimi Code、Claude Desktop 與 Devin Desktop。
+  - 提供 CLI 執行指令 `superpowers-setup` 與 `superpowers-mcp setup`，並提供跨平台一鍵安裝腳本（[`install.sh`](scripts/install.sh) 與 [`install.ps1`](scripts/install.ps1)）。
+  - **明確同意與反病毒架構 (Explicit Consent & Anti-Virus Design)**：嚴格要求 `--target <client>`，徹底廢除無授權的磁碟盲目掃描與全盤修改（移除 `--all`）。
+  - **原子寫入防護 (`safeWriteConfig`)**：採用隨機 8-byte nonce 暫存檔、`flag: "wx"` 獨占建立與 `renameSync` 原子更名，消除並發競爭與半寫入檔案損毀。
+  - **符號連結保護與最小權限**：`realpathSync` 解析目標真實路徑，新目錄嚴格限制 `0o700`、檔案設為 `0o600`，備份檔繼承原始權限。
+  - **注入防護與 JSONC 解析**：所有參數經 `JSON.stringify` 轉譯，JSONC 支援註解/尾隨逗號容錯，並以 `isPlainObject` 防禦 Prototype Pollution 原型鏈攻擊。
+  - **CLI 傳輸隔離**：於 `src/server.ts` 入口前置分流 setup 參數，避免與 MCP Stdio 通訊協定衝突造成輸出污染。
+  - **完整測試套件**：新增 [`tests/setup_test.js`](tests/setup_test.js)（21 項測試 100% 通過）。
+- **Skill Compositions 技能組合與端到端 Pipeline (`src/server.ts`, `docs/`)**：
+  - 新增 3 組全新 MCP 工作流 Prompts：`feature-pipeline`、`structured-debug` 與 `skill-composition`。
+  - 建立 4 語系在地化完整指南（[`docs/skill-compositions.zh-TW.md`](docs/skill-compositions.zh-TW.md)），納入橫向 Mermaid 流程圖與 ASCII 流程指引。
+  - 強化 [`skills/using-superpowers/SKILL.md`](skills/using-superpowers/SKILL.md) 與 [`skills/writing-plans/SKILL.md`](skills/writing-plans/SKILL.md) 之 `Recommended Skill` 標籤與控制器調度協議。
+  - 新增 [`tests/prompts_compositions_test.js`](tests/prompts_compositions_test.js)（7 項測試 100% 通過）。
+- **Prompts 安全加固與生命週期修復 (`src/server.ts`)**：
+  - 升級 `interpolateTemplate` 為單趟統一正則替換，消除二級模板階層展開注入漏洞。
+  - 全面普及 `getStringArg` 32 KB 長度截斷與 `hasOwnProperty` 安全檢查。
+  - `structured-debug` 補齊 Stage 6（審查意見修復）與 Stage 7（分支清理與收尾）。
+- **全面安全性審計與驗證**：
+  - `npm audit` 報告 0 漏洞，精確鎖定 `hono`、`@hono/node-server`、`fast-uri` 與 `qs`；全專案 5 大測試套件（100+ 項斷言）100% 通過；同步更新 [`SECURITY.md`](SECURITY.md)。
+
+### v6.3.3
+
+- **MCP 標準 Prompts 支援 (`src/server.ts`)**：
+  - 實作標準 Prompt 處理常式，註冊 6 組常用 Prompts（`session-start`、`sdd-implementer`、`sdd-task-reviewer`、`sdd-re-review`、`spec-reviewer`、`plan-reviewer`），可直接於 IDE Prompt Picker 中選用。
+- **多 Harness 參考對應表**：
+  - 新增 Devin CLI（[`references/devin-tools.md`](skills/using-superpowers/references/devin-tools.md)）與 OpenCode（[`references/opencode-tools.md`](skills/using-superpowers/references/opencode-tools.md)）之原生工具對應。
+- **多語言文檔對齊**：
+  - 統一各語言 README 中的 MCP 功能支援表（Tools / Prompts / Resources）與多 Harness 支援矩陣。
+- **測試套件擴充**：
+  - 新增 `prompts/list` 與 `prompts/get` 參數注入的自動化測試斷言。
+
+👉 *更多歷史版本更新紀錄，請參閱完整的 [CHANGELOG.md](CHANGELOG.md)。*
 
 ---
 
 ## 🙏 致謝
 
-本專案是透過 fork 與改編自 [obra](https://github.com/obra) 的原始 [Superpowers](https://github.com/obra/superpowers) 專案。我們非常感謝他們在定義 Agentic 技能框架與軟體開發方法論上的貢獻，這些成為了這個 MCP Server 的基石。
+本專案是透過 fork 與改編自 [obra](https://github.com/obra) 的原始 [Superpowers](https://github.com/obra/superpowers) 專案。我們非常感謝他們在定義 Agentic 技能框架與軟體工程工作流上的開創性貢獻，這些構成了本 MCP Server 的基石。