superpowers-mcp 6.3.6 → 6.3.8

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.6-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將 Superpowers 技能庫與自主 Agent 工作流架構打包成獨立、高效能且安全加固的 **Model Context Protocol (MCP)** 伺服器之相關資訊與使用說明。
@@ -23,11 +23,11 @@
 | :--- | :--- | :--- |
 | **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 協議標準資源直讀） |
+| **Resources (資源)** | 14 項技能 URI + 1 項指南 | `skill://superpowers/<skill-name>`，以及 `guide://superpowers/skill-compositions` |
 
 ### 與 AI Agent 對話（基礎操作）
 
-安裝或配置完成後，您的 AI Agent 將能夠自動識別並調用 `Superpowers Skills` 與 `Prompts`。
+安裝或配置完成後，MCP 客戶端即可發現 Superpowers 的 tools、prompts 與 resources。MCP prompt 必須由使用者選取；之後是否載入技能，取決於 Agent 是否遵循 prompt 並呼叫 `read_skill`。
 
 **基礎互動範例：**
 - **初始化工程規範**：「套用 `session-start` prompt」（注入 Superpowers 技能體系與工程紀律）
@@ -125,24 +125,24 @@
 
 ## 🔄 技能編排與工作流流水線 (Skill Compositions & Pipelines)
 
-當執行多步驟的複雜任務時，請直接使用以下**一鍵端到端工作流**，AI 會自動按標準工程步驟引導（詳見完整指南：[`docs/skill-compositions.zh-TW.md`](docs/skill-compositions.zh-TW.md)）：
+當執行多步驟的複雜任務時，請使用以下**互動式工作流啟動器**。它會啟動 Agent 引導的流程，並在設計、計畫審閱與分支收尾時等待使用者決定；它不是伺服器端無人值守自動化。詳見 [`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`，幫我開發 [新功能名稱]」
+- **啟動方式：**從客戶端的 MCP Prompts 選單選取 `feature-pipeline`，提供必要的 `feature_name` 與選填的 `requirements`。
 - **流程特色：** 需求確認 (Spec) ➔ 任務拆解 (Plan) ➔ Worktree 隔離 ➔ 獨立 Subagent + TDD 實作 ➔ 全套測試驗證 ➔ 專家代碼審查 ➔ 分支收尾。
 
 ### 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`，幫我排查這個報錯：[貼上錯誤訊息]」
+- **啟動方式：**從 MCP Prompts 選單選取 `structured-debug`，提供錯誤描述或失敗測試。
 - **流程特色：** 根因分析拆解假說 ➔ Worktree 隔離平行排查 ➔ 多 Agent 驗證 ➔ 編寫失敗測試並修復 ➔ 全套迴歸驗證 ➔ 審查結果解決 ➔ 分支合併收尾。
 
 ### 3. 動態技能導引 (Dynamic Workflow Guide)
-- **一鍵指令：**「請套用 `skill-composition`，我目前的情境是 [重構/遷移/接手舊專案]」
+- **啟動方式：**選取 `skill-composition` 取得重構、遷移或舊系統的流程建議；這些情境目前沒有各自獨立的啟動 prompt。
 - **流程特色：** 針對大型重構、舊代碼防護網建立或團隊新人上手，動態推薦最佳步驟：
   - **大型重構與遷移 (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`
@@ -171,11 +171,57 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 | 13 | **🤖 進階調度** | **`using-superpowers`** | **Superpowers 基礎紀律**：MCP 入口技能，引導 Agent 在任何任務前主動搜尋並載入對應技能規範。 | 開啟對話時自動載入，規範 AI 的行為準則。 |
 | 14 | **🤖 進階調度** | **`writing-skills`** | **技能撰寫與維護**：規範如何為團隊建立、測試與封裝新的 Superpowers 技能。 | 需要擴充專屬新技能或更新既有技能時。 |
 
----
-
 ## 🆕 最近更新
 
-### v6.3.6 (最新版)
+### v6.3.8 (最新版)
+
+- **可執行的互動式工作流啟動器**：
+  - `feature-pipeline` 與 `structured-debug` 會逐階段給出明確的 `read_skill` 呼叫，保留必要的使用者核准關卡，並清楚說明流程由客戶端 Agent 執行，不是 MCP 伺服器內部自動執行。
+  - 支援多 Agent 的 Host 可使用 Subagent；其他 Host 會退回會話內或序列執行，不會聲稱使用不存在的能力。
+  - `read_skill` 同時接受純技能名稱與文件所載的 `superpowers:` 前綴。
+  - Skill Compositions 指南已納入 npm 套件，並可透過 `guide://superpowers/skill-compositions` 讀取。
+- **全域安裝引擎並行安全、Inode 防禦與符號連結跳脫隔離**：
+  - **Allowed Roots 邊界隔離**：強制限制目的地路徑必須在使用者允許目錄（`homeDir`、`appData`、`localAppData`），杜絕父層符號連結跳脫攻擊。
+  - **樂觀並行衝突檢測**：在原子 `fs.renameSync` 前比對磁碟檔案與 `expectedContent`，防止多行程競態覆寫較新的設定檔。
+  - **目錄 Inode & Dev TOCTOU 防禦**：比對暫存檔案目錄之真實裝置與 inode 識別碼，防止目錄置換攻擊。
+  - **Fail-Closed 嚴格解析防護**：JSON 根目錄或伺服器欄位非 Plain Object 時即刻拒絕，阻斷原型污染與畸形設定。
+- **核心技能引擎確定性排序與動態快取驗證**：
+  - **目錄確定性排序與別名衝突防禦**：目錄按字母確定性排序並即時阻擋衝突鍵名，杜絕隨機覆寫與快取錯位。
+  - **自動快取驗證 (`CACHE_REVALIDATE_MS = 1000`)**：磁碟變更在 1 秒內自動同步，無需重啟 MCP 伺服器即可反映檔案編輯。
+  - **大小寫折疊與真實路徑防禦**：`src/server.ts` 在 darwin/win32 進行大小寫折疊與 `fs.realpathSync` 驗證，徹底攔截系統保護目錄（`/private/etc`、`/private/var`、`C:\Windows`）。
+- **RFC 6455 WebSocket 協議加固與日誌彈性壓縮**：
+  - 完整支援 `CONTINUATION` (0x00) 分段訊息重組，並嚴格驗證控制幀不得分段 (`opcode >= 0x8 && !fin`)，阻絕非標準 RSV 擴展。
+  - 尾部彈性日誌壓縮：日誌達 1 MB 上限時保留最新換行對齊記錄，避免整檔抹除遺失事件上下文。
+  - 私有檔案描述元以 `O_RDWR | O_APPEND | O_CREAT | O_NOFOLLOW` 安全開啟。
+- **Shell 與 PowerShell 腳本指令注入防禦**：
+  - `find-polluter.sh` 與 `find-polluter.ps1`：指令參數陣列化展開 (`"${TEST_COMMAND[@]}"`、`& $testCommand @testCommandArgs`) 搭配含空白檔名安全讀取迴圈，杜絕 Shell 注入。
+  - `sdd-workspace`：執行 `cd` 前重設 `CDPATH=''`，阻絕環境變數目錄劫持。
+  - `sdd-workspace.ps1`：以 UTF-8 without BOM (`[System.Text.UTF8Encoding]::new($false)`) 寫入計畫標記，確保無損 Unicode 路徑往返。
+- **全自動化回歸測試底線**：
+  - 擴展測試套件至 **274 項自動化斷言全數通過**（Node.js: 145 項、Bash: 35 項、PowerShell: 94 項），維持 100% 通過率。
+
+### v6.3.7
+
+- **上游同步 — 第 1–3 批（obra/superpowers）**：
+  - **技能自動路由**：`systematic-debugging` 與 `test-driven-development` 的 description 新增觸發詞（`"tdd"`、`"systematic debug"` 等）與兄弟技能交叉導引，提升 MCP 客戶端的技能選擇準確度。
+  - **無測試指令的證據律**：`verification-before-completion` 新增「When There Is No Test Command」章節：報告、研究、稽核與書信類工作必須重新開啟成品、逐項證明並誠實列出未完成項，只能宣稱「完整」而非「正確」。
+  - **Brainstorming 意圖閘門**：新增「Establish Shared Understanding」（探索意圖 → 回寫理解 → 帶入設計），並重寫 HARD-GATE 明列各路徑前置條件，禁止把單次核准當成跳過後續階段的許可。
+  - **規劃交接審查（Planning-Handoff Review）**：brainstorming 的規格自我審查升級為 0.0–9.9 評分 + burden ledger + 單次有界改進 + 唯讀複評，並具備失敗時還原初稿的保底規則。
+  - **已存計畫審閱與情境化交接**：`writing-plans` 要求人類先審閱存檔計畫才可執行；未指定執行方式時必須給出針對本計畫的推薦，而非固定預設。
+  - **計畫勾選簿記**：`executing-plans` 與 `subagent-driven-development` 在完成訊息中同步勾選計畫檔步驟。
+  - **遠端安全邊界**：`using-git-worktrees` 要求從共享 ref 開分支時必須加 `--no-track`，並以 `git branch -vv` 檢查追蹤狀態（首次 commit 前先 `--unset-upstream`）；`executing-plans` 要求 commit 保持本地、禁止改寫共享分支；implementer 遇到任何 push 需求一律回報 BLOCKED，不得自行推送。
+  - **Discoveries 帳本**：SDD 進度帳本新增 `## Discoveries` 區段，跨任務發現可穿越 compaction，並成為下一次派工介面條款的來源。
+  - **延後發現匯出**：刪除計畫工作區前，`Ruling:`／`minor (deferred)`／`parked` 行必須匯出到 PR 的「Deferred items」清單，或提交至 `docs/superpowers/follow-ups/<plan>.md`。
+  - **Greenfield SDD Scripts**：repo 尚未建立時 `sdd-workspace` 退回當前目錄（`.ps1` 同步支援），`review-package` 則在非 repo 環境下給出可行動的錯誤。
+  - **TDD 特徵化守門**：行為保持型重構的五步程序（先變異、確認失敗、由 VCS 還原、維持綠燈），並從邊界與變異檢查章節交叉引用。
+- **上游內容同步 — 第 4 批**：brainstorm 啟動腳本改由 `BRAINSTORM_HOST`/`BRAINSTORM_URL_HOST` 決定 host（`--host`/`--url-host` 仍優先）、`writing-skills` 新增搬移內容時的連結重解指引，SDD 審查者改為把完整報告寫入 `…/task-N-review.md` 並只回傳少於 15 行摘要 — MCP 端新增 `review_file` 參數（若要求的路徑正規化後等於報告或 brief 檔，改用推導出的 `-review.md`），以及讓 `[FIX_BASE_SHA]` 真正被代入的 `fix_base_sha` 別名。
+- **上游 drift 報告**：`npm run drift` 以已提交的上游基線比對 `obra/superpowers`，列出已採納檔案的變動、本地缺漏的引進檔案與 fork 專屬新增；`npm run drift:record -- --ignore <skill>` 於審閱同步後更新基線，且會在寫入前拒絕遭截斷的 API tree。
+- **MCP 表面覆蓋率測試**：磁碟上的每個 skill 都必須是對外曝露、且讀出內容屬於該 skill 的 MCP resource，prompt 清單必須與 4 個 README 完全一致。
+- **MCP 描述保真**：上游的跳脫引號格式改為未加引號的 YAML plain scalar，確保 `SkillsManager` 經 MCP 輸出時不會出現多餘反斜線。
+- **回歸防護**：`tests/upstream_sync_test.js` 增至 22 項標記檢查（涵蓋第 1–4 批）；全測試套件通過（8 個 npm 套件共 139 項檢查、PowerShell 90 項斷言、SDD 16 + host 預設 11 + render-graph 8 項 bash 斷言）。
+- **發佈前強化**：Bash 與 PowerShell 的 brainstorm host 測試明確強制 background 模式，讓完整 264 項驗證在 `CODEX_CI=1` 下也能正常結束；`package-lock.json` 已同步至 v6.3.7 與 Node `>=18`；npm repository 與 CLI `bin` metadata 已正規化，並經 `npm publish --dry-run` 與打包安裝 smoke test 驗證。
+
+### v6.3.6
 
 - **極致效能躍升優化 (2x~8.1x 加速)**：
   - **並行技能索引與快取前置**：`SkillsManager.listSkills` 升級為非同步並行目錄遍歷 (`Promise.all`) 搭配根目錄預解析快取，冷啟動技能索引延遲由 4.79ms 銳減至 2.35ms（**2.04x 速度提升**）。
@@ -195,60 +241,6 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 - **多語系文檔全面對齊**：
   - 4 語系 README（[`README.md`](README.md)、[`README.zh-TW.md`](README.zh-TW.md)、[`README.ja.md`](README.ja.md)、[`README.ko.md`](README.ko.md)）同步支援環境清單、效能指標與一鍵指令表格。
 
-### v6.3.5
-
-- **新增 7 款主流 AI 開發環境一鍵安裝 (`src/setup-runner.ts`, `scripts/install.sh`)**：
-  - 全域配置引擎支援擴充至 15 款 AI Agent 與 IDE 環境：
-    - **GitHub Copilot (VS Code Insiders)**：`Code - Insiders/User/mcp.json`（具備實體路徑完全隔離，避免與正式版 VS Code 互相覆寫，別名 `copilot-insiders`, `vscode-insiders`, `code-insiders`, `insiders`, `insider`）
-    - **QwenPaw (個人 AI 助理工作站)**：`~/.qwenpaw/config.json`（相容舊版 `~/.copaw/config.json`，別名 `qwenpaw`, `copaw`）
-    - **Cline (VS Code / CLI)**：`.../saoudrizwan.claude-dev/settings/cline_mcp_settings.json`（別名 `cline`, `claude-dev`）
-    - **Kilo Code**：`~/.config/kilo/kilo.jsonc`（自適應 `"mcp"` root 與陣列 command 規格，別名 `kilo`, `kilocode`）
-    - **Qoder**：`~/.qoder/settings.json`（別名 `qoder`）
-    - **Kiro**：`~/.kiro/settings/mcp.json`（別名 `kiro`, `kiro-code`）
-    - **Trae**：`.../Trae/User/mcp.json`（跨平台支援 macOS、Windows、Linux 與 Trae CN）
-  - 新增 `"json-mcp"` 設定格式型別，精確相容 Kilo Code 特有字典規格。
-  - 落實 Single Source of Truth (SSOT)，全面由 `runSetup` 透過 `harness.defaultConfig` 動態注入設定範本。
-- **雙子 Subagent 架構與安全品質審查 (Code Review)**：
-  - 派出專職「架構與安全性審查員」與「代碼品質與邊界審查員」雙代理審查。
-  - 全數驗證原子置換（`crypto.randomBytes(8)` + `flag: "wx"`）、Symlink 邊界防禦、最小目錄權限 `0o700` / 檔案權限 `0o600`，以及全環境預設零磁碟污染原則。
-  - 完成專案全面安全掃描與審計，更新 [`SECURITY.md`](SECURITY.md)（173 項自動化回歸斷言 100% 通過）。
-- **自動化測試套件擴充 (`tests/setup_test.js`)**：
-  - 單元測試由 21 項大幅擴增至 32 項（100% 通過），補齊 Claude Desktop、Kimi Work 與 Hermes Desktop 的端到端沙盒測試與別名驗證。
-
-### 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)。*
 
 ---

package/docs/maintainers/upstream-sync.md

@@ -0,0 +1,42 @@
+# Upstream Synchronization
+
+This guide is for maintainers who review and import skill content from [`obra/superpowers`](https://github.com/obra/superpowers).
+
+The upstream blob SHAs captured at the last sync are stored in [`tests/upstream-sync-baseline.json`](../../tests/upstream-sync-baseline.json).
+
+## Commands
+
+```bash
+npm run drift                    # compare the baseline against upstream and list what moved
+npm run drift:record             # refresh the baseline after a reviewed sync
+node scripts/upstream-drift.js   # offline: baseline integrity + local coverage
+```
+
+The drift report separates:
+
+- files changed upstream;
+- upstream additions and removals;
+- tracked files missing from this fork; and
+- fork-only additions.
+
+An upstream skill that this fork deliberately does not adopt is reported as a decision rather than drift. Record that decision after review with:
+
+```bash
+npm run drift:record -- --ignore <skill>
+```
+
+## Synchronization Workflow
+
+1. Run `npm run drift` to identify upstream changes.
+2. Review the changes and import only the content appropriate for this fork.
+3. Run the test suite with `npm test`.
+4. After the reviewed sync is complete, run `npm run drift:record` to update the baseline.
+5. Commit the imported changes and updated baseline together.
+
+Do not refresh the baseline before reviewing and importing the changes. Doing so would mark unseen upstream changes as handled.
+
+## Safety Checks
+
+`npm test` fails when an imported upstream file is deleted or when a shipped skill loses its upstream lineage.
+
+Report mode marks a truncated GitHub tree as partial and suppresses `--fail-on-drift`. Record mode refuses a truncated response entirely so an incomplete listing cannot overwrite the last complete baseline.

package/docs/skill-compositions.ja.md

@@ -0,0 +1,194 @@
+# Superpowers MCP: スキル構成 & ワークフローパイプライン (Skill Compositions & Workflow Pipelines)
+
+[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+
+> **重要:** これらの MCP prompts は対話型ワークフローランチャーであり、サーバー側の自動化ではありません。クライアントの MCP Prompts メニューから選択してください。slash command の構文はクライアントごとに異なります。エージェントにはファイル、ターミナル、Git へのアクセスが必要で、各段階で `read_skill` を呼び出します。設計承認、計画レビュー、ブランチ完了時にはユーザーの判断を待ちます。完全なガイドは `guide://superpowers/skill-compositions` でも取得できます。
+
+> **正典（Source of Truth）：** 本英語版が原本です。スキルの振る舞いが変わったら英語版を先に更新し、翻訳を同期してください。
+
+## 1. スキル構成が重要な理由 (Why Skill Compositions Matter)
+
+`superpowers-mcp` に含まれる 14 のコアスキルは、要件の明確化、アーキテクチャ設計、分離されたワークスペースの構築、テスト駆動開発 (TDD)、体系的なデバッグから、完全検証、コードレビュー、ブランチ統合に至るまで、ソフトウェア開発ライフサイクル (SDLC) 全体を網羅しています。
+
+各スキルは単体でも高精度なエンジニアリングツールですが、実践的な開発には「ワークフローのオーケストレーション（編排）」が不可欠です。スキル構成（Skill Composition）によって、アドホックな AI 操作を、規律ある再現可能で安全保護されたエンジニアリングパイプラインへと昇華させます。
+
+---
+
+## 2. コアアーキテクチャ原則 (Core Architectural Principles)
+
+スキルを組み合わせる際は、常に以下の 5 つの安全防御メカニズムを適用してください。
+
+1. **物理的分離を最優先 (Isolation First via Git Worktrees)**：マルチエージェント協調や複数仮説の並行デバッグを行う際は、必ず `superpowers:using-git-worktrees` を使用して独立したディレクトリを作成し、ファイル競合 (Race Condition) や環境汚染を防止します。
+2. **デフォルトでテスト駆動 (TDD by Default)**：回帰安全性を担保するため、失敗するテスト（Red ➔ Green ➔ Refactor）を事前に作成せずにコードを変更してはなりません。
+3. **2 層レビューゲート (Dual-layer Review)**：タスク単位の仕様準拠チェックおよびフィーチャー全体のブランチレビュー（`requesting-code-review` / `receiving-code-review`）を省略してはなりません。
+4. **完了前の完全検証 (Verification Before Completion)**：完了を宣言したりブランチをマージする前に、必ずリポジトリ全体のテストスイート、Linter、型チェック（`verification-before-completion`）を実行します。
+5. **リモート安全境界（Local Commits Only）**：コミットはローカルに留め、計画または人間のパートナーの指示がない限り push/pull/fetch を行いません。共有 ref から分岐する際は `--no-track`（または初回コミット前の `--unset-upstream`）で、機能ブランチが共有ブランチを追跡しないようにし、共有ブランチの書き換えは禁止です（自己適用できるのは `git revert` のみ）。
+
+---
+
+## 3. 4つの標準スキル構成パイプライン (Four Standard Workflow Pipelines)
+
+### パイプライン 1: エンドツーエンド新機能開発 (Feature Development Pipeline)
+**推奨用途：** 新機能のスクラッチ開発、主要モジュールの追加、コアプロセスのリファクタリング。
+
+```mermaid
+flowchart LR
+    F1[brainstorming] --> F2[writing-plans]
+    F2 --> F3[using-git-worktrees]
+    F3 --> F4[subagent-driven-development / executing-plans]
+    F4 --> F5[test-driven-development]
+    F5 --> F6[verification-before-completion]
+    F6 --> F7[requesting-code-review]
+    F7 --> F8[finishing-a-development-branch]
+```
+
+| ステップ | スキル (Skill) | 責務と成果物 |
+| :--- | :--- | :--- |
+| **1. 要件と設計** | `brainstorming` | 要件、制約、アーキテクチャ上の決定事項を整理し、共通理解の確認とプランニング・ハンドオフ・レビューを経て仕様書 (Spec) を出力。 |
+| **2. 計画策定** | `writing-plans` | 仕様書を独立して検証可能なタスクリストに分解し、Recommended Skill を明記。 |
+| **3. 環境分離** | `using-git-worktrees` | 独立した Git Worktree を作成し、メインブランチと作業環境を保護。 |
+| **4. タスク実行** | `subagent-driven-development` | 独立したサブエージェントを順次起動し、クリーンなコンテキストでタスクを実行。 |
+| **5. ロジック実装** | `test-driven-development` | 各タスクのビジネスロジックに対して Red ➔ Green ➔ Refactor を厳格に適用。 |
+| **6. フルテスト検証** | `verification-before-completion` | フルテストスイート、Linter、型チェックを実行し、回帰がないことを確認。テストコマンドが無い場合は成果物を再度開き、要求事項を漏れなく確認。 |
+| **7. コードレビュー** | `requesting-code-review` | レビューパッケージを生成し、多角的なコード＆アーキテクチャレビューを実施。 |
+| **8. ブランチ完了** | `finishing-a-development-branch` | 保留所見をエクスポート（PR チェックリストまたは follow-ups ファイル）してから、マージ/PR、Worktree の整理、一時ブランチの削除を実施。 |
+
+---
+
+### パイプライン 2: 構造化トラブルシューティング (Structured Troubleshooting Pipeline)
+**推奨用途：** 複数テストの失敗、再現困難なバグ、本番障害の調査。
+
+```mermaid
+flowchart LR
+    D1[systematic-debugging] --> D2[using-git-worktrees]
+    D2 --> D3[dispatching-parallel-agents]
+    D3 --> D4[test-driven-development]
+    D4 --> D5[verification-before-completion]
+    D5 --> D6[requesting-code-review]
+    D6 --> D7[finishing-a-development-branch]
+```
+
+1. **`systematic-debugging`**：根本原因を分析し、独立して検証可能な仮説に分解。
+2. **`using-git-worktrees`**：並行調査用に分離された Worktree を準備し、テストやファイル競合を防止。
+3. **`dispatching-parallel-agents`**：サブエージェントを並行ディスパッチして各仮説を検証。
+4. **`test-driven-development`**：バグを再現する最小限の失敗テストを作成した上で修正を実施。
+5. **`verification-before-completion`**：全テストが正常に通過することを検証。
+6. **`requesting-code-review`**（および `receiving-code-review`）：修正差分と回帰テストの網羅性をレビューし、指摘事項を解消。
+7. **`finishing-a-development-branch`**：バグ修正ブランチをマージ/PRし、一時 Worktree を安全にクリーンアップ。
+
+---
+
+### パイプライン 3: 大規模リファクタリング & システム移行 (Large Refactoring & Migration Pipeline)
+**推奨用途：** コアアーキテクチャの再構築、フレームワーク移行、サービス分離。
+
+```mermaid
+flowchart LR
+    R1[brainstorming] --> R2["writing-plans (skeleton-first)"]
+    R2 --> R3[using-git-worktrees]
+    R3 --> R4[subagent-driven-development]
+    R4 --> R5[verification-before-completion]
+    R5 --> R6[requesting-code-review]
+    R6 --> R7[finishing-a-development-branch]
+```
+
+1. **`brainstorming`**：インターフェース互換性、移行手順、同等性検証基準を定義。
+2. **`writing-plans` (Skeleton-First モード)**：全サブシステムを貫通する最小限のエンドツーエンド骨格を設計。
+3. **`using-git-worktrees`**：移行作業専用の長期 Worktree を構築。
+4. **`subagent-driven-development`**：段階的にリファクタリングを実行し、タスクごとにレビューを実施。
+5. **`verification-before-completion`** + **`requesting-code-review`**：完全な回帰検証と専門家によるレビュー。
+6. **`finishing-a-development-branch`**：移行ブランチをマージし、Worktree を整理して完了。
+
+---
+
+### パイプライン 4: レガシーコードベース安全網の構築 (Legacy Codebase Safety Net)
+**推奨用途：** 単体テストが不足している、または構造が乱雑なレガシーコードベース。
+
+```mermaid
+flowchart LR
+    L1[brainstorming] --> L2[writing-plans]
+    L2 --> L3["test-driven-development (characterization)"]
+    L3 --> L4[systematic-debugging]
+    L4 --> L5[verification-before-completion]
+```
+
+1. **`brainstorming`**：システムの境界、既存動作の仕様化目標を特定。
+2. **`writing-plans`**：仕様化テスト（Characterization Tests）作成計画を策定。
+3. **`test-driven-development`**：TDD 特性化ガード（変異→失敗確認→VCS 復元→グリーン維持）を用いて、既存の振る舞いを保護するテストを作成。
+4. **`systematic-debugging`**：保護テストで発見された潜在的欠陥を特定・修正。
+5. **`verification-before-completion`**：安全網の完全性を検証。
+
+---
+
+## 4. スキル作成とメタデータ標準 (Skill Authoring & Metadata Standards)
+
+`writing-plans` で作成する実装計画において、各タスクに推奨スキルを指定できます：
+
+```markdown
+### Task 1: トークン認証ミドルウェアの実装
+- **Goal**: JWT トークンの検証とクレーム抽出
+- **Target Files**: `src/auth/jwt.ts`, `tests/auth/jwt.test.ts`
+- **Recommended Skill**: `superpowers:test-driven-development`
+- **Task Brief**:
+  1. 期限切れおよび無効な署名の失敗テストを作成 (FAIL)
+  2. 最小限の検証ロジックを実装してパスさせる (PASS)
+  3. 厳格な型安全性を確保してリファクタリング
+```
+
+### コントローラーとサブエージェントのディスパッチプロトコル
+コントローラーエージェントがタスクサブエージェントを起動する際：
+1. コントローラーは計画タスクに指定された `Recommended Skill` を読み取ります。
+2. コントローラーは `read_skill(skill_name)` を介してそのスキルを読み込むようサブエージェントに指示します。
+3. サブエージェントはそのスキルの厳格な手法（Red-Green-Refactor など）に従って実装を実行します。
+
+---
+
+## 5. ネイティブ MCP Prompts 一覧
+
+`superpowers-mcp` は主要な MCP クライアント（Cursor、Antigravity、VS Code、Devin Desktop など）で利用可能な標準 Prompts を提供します：
+
+| MCP Prompt 名 | 引数 | 用途 |
+| :--- | :--- | :--- |
+| **`feature-pipeline`** | 必須 `feature_name`、任意 `requirements` | 対話型の新機能開発ワークフローランチャー。 |
+| **`structured-debug`** | `issue_description`, `failing_tests` | 対話型の体系的デバッグランチャー。ホスト対応時は並行調査も可能。 |
+| **`skill-composition`** | `scenario` | 開発シナリオに応じた動的スキル構成ガイド。 |
+| **`session-start`** | - | Superpowers の基本環境とスキル利用ルールを注入。 |
+| **`sdd-implementer`** | `brief_file`, `task_name`, ... | SDD タスク実装サブエージェント用プロンプト。 |
+| **`sdd-task-reviewer`** | `brief_file`, `report_file`, `review_file`, ... | SDD 単一タスクレビュー用プロンプト。 |
+| **`sdd-re-review`** | `brief_file`, `review_file`, `previous_findings`, ... | SDD 修正ラウンド差分レビュー用プロンプト。 |
+| **`spec-reviewer`** | `spec_file` | 設計仕様書レビュー用プロンプト。 |
+| **`plan-reviewer`** | `plan_file`, `spec_file` | 実装計画書レビュー用プロンプト。 |
+
+---
+
+## 6. IDE での実際の操作方法 (How to Use in Practice)
+
+`superpowers-mcp` を設定すれば、**14 個の個別スキル名を覚える必要は一切ありません**。以下の 2 つの方法で簡単に利用できます：
+
+### 方法 A: クライアントの MCP Prompts メニューを使用（推奨）
+Cursor、Antigravity、VS Code、Devin Desktop などのチャット入力欄で：
+1. **新機能開発**：Prompts 一覧から `feature-pipeline` を選び、必須の `feature_name` と任意の `requirements` を入力します。slash command の実際の名前はクライアントによって異なり、MCP server namespace を含む場合があります。
+2. **バグ修正・テスト失敗**：`structured-debug` を選択し、エラーログやテスト名を貼り付けます。
+3. **ワークフローに迷った時**：`skill-composition` を選択すると、現在の状況に応じた最適なパイプラインが自動提案されます。
+
+### 方法 B: 自然言語で直接指示
+通常のチャットでも次のように依頼できますが、ネイティブ MCP prompt が取得される保証はありません。確実に使用するには MCP Prompts メニューを選択してください：
+- *「`feature-pipeline` の手順に従って、[機能名] の開発を進めてください」*
+- *「`structured-debug` を使用して、次のエラーを調査・修正してください：[エラー貼り付け]」*
+- *「`docs/skill-compositions.ja.md` のリファクタリングパイプラインを適用して [モジュール名] を再構築してください」*
+
+### 💬 実際の対話フロー例（新機能開発の場合）：
+```text
+【ユーザー】:（MCP Prompts メニューから `feature-pipeline` を選択し、クーポン機能を入力）
+  ↓
+【AI】:（`read_skill` で brainstorming を読み込み）「クーポンの有効期限や他の割引との重複適用の可否について確認させてください」
+  ↓
+【ユーザー】:「有効期限あり、重複適用は不可でお願いします」
+  ↓
+【AI】:（設計承認後に writing-plans を読み込み）「docs/superpowers/plans/... に実装計画を作成しました。ご確認ください」
+  ↓
+【ユーザー】:「計画に問題ありません。進めてください」
+  ↓
+【AI】: (Worktree 分離 ➔ SDD 起動 ➔ 各タスクを TDD で実装 ➔ フルテスト検証 ➔ コードレビュー ➔ ブランチ完了)
+  ↓
+【AI】: 「全タスクの実装およびリポジトリ全体のテストが 100% 成功しました。レビューも完了し、ブランチが整いました！」
+```

package/docs/skill-compositions.ko.md

@@ -0,0 +1,194 @@
+# Superpowers MCP: 스킬 조합 및 워크플로우 파이프라인 (Skill Compositions & Workflow Pipelines)
+
+[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+
+> **중요:** 이 MCP prompts는 대화형 워크플로 런처이며 서버 측 자동화가 아닙니다. 클라이언트의 MCP Prompts 메뉴에서 선택하세요. slash command 문법은 클라이언트마다 다릅니다. 에이전트는 파일, 터미널, Git에 접근할 수 있어야 하며 각 단계에서 `read_skill`을 호출합니다. 설계 승인, 계획 검토, 브랜치 마무리 단계에서는 사용자 결정을 기다립니다. 전체 가이드는 `guide://superpowers/skill-compositions`에서도 읽을 수 있습니다.
+
+> **단일 소스(Source of Truth):** 이 영어 문서가 정본입니다. 스킬 동작이 바뀌면 영어 문서를 먼저 갱신하고 번역을 동기화하세요.
+
+## 1. 스킬 조합이 중요한 이유 (Why Skill Compositions Matter)
+
+`superpowers-mcp`의 14개 핵심 스킬은 요구사항 명확화, 아키텍처 설계, 격리된 작업 환경 구축, 테스트 주도 개발(TDD), 체계적 디버깅부터 전체 검증, 코드 리뷰, 브랜치 통합에 이르기까지 소프트웨어 개발 라이프사이클(SDLC) 전반을 다룹니다.
+
+각 스킬은 단독으로도 정밀한 엔지니어링 도구 역할을 하지만, 실제 프로덕션 개발에는 **워크플로우 오케스트레이션(편성)**이 필수적입니다. 스킬 조합(Skill Composition)을 통해 임의적인 AI 상호작용을 체계적이고 재현 가능하며 안전하게 보호되는 엔지니어링 파이프라인으로 전환합니다.
+
+---
+
+## 2. 핵심 아키텍처 원칙 (Core Architectural Principles)
+
+스킬을 조합할 때는 항상 다음 5가지 안전 보호 메커니즘을 준수해야 합니다:
+
+1. **물리적 격리 최우선 (Isolation First via Git Worktrees)**: 다중 에이전트 협업이나 여러 가설의 병렬 디버깅 시 항상 `superpowers:using-git-worktrees`를 사용하여 독립된 디렉토리를 생성하고 파일 충돌(Race Condition)과 작업 환경 오염을 방지합니다.
+2. **기본적인 테스트 주도 개발 (TDD by Default)**: 회귀 안전성을 보장하기 위해 실패하는 테스트(Red ➔ Green ➔ Refactor)를 먼저 작성하지 않고 코드를 수정해서는 안 됩니다.
+3. **이중 검토 게이트 (Dual-layer Review)**: 태스크 단위의 스펙 준수 검사와 피처 전체의 브랜치 리뷰(`requesting-code-review` / `receiving-code-review`)를 생략해서는 안 됩니다.
+4. **완료 전 전체 검증 (Verification Before Completion)**: 완료를 선언하거나 브랜치를 병합하기 전에 반드시 전체 테스트 스위트, Linter, 타입 검사(`verification-before-completion`)를 실행합니다.
+5. **원격 안전 경계(Local Commits Only)**: 커밋은 로컬에 유지하고, 계획이나 사람 파트너의 지시 없이는 push/pull/fetch하지 않습니다. 공유 ref에서 분기할 때는 `--no-track`(또는 첫 커밋 전 `--unset-upstream`)으로 기능 브랜치가 공유 브랜치를 추적하지 않게 하고, 공유 브랜치 재작성은 금지합니다(스스로 적용할 수 있는 것은 `git revert`뿐).
+
+---
+
+## 3. 4대 표준 스킬 조합 파이프라인 (Four Standard Workflow Pipelines)
+
+### 파이프라인 1: 엔드투엔드 새 기능 개발 (Feature Development Pipeline)
+**권장 시나리오:** 새 기능 초기 개발, 주요 모듈 추가, 핵심 프로세스 리팩토링.
+
+```mermaid
+flowchart LR
+    F1[brainstorming] --> F2[writing-plans]
+    F2 --> F3[using-git-worktrees]
+    F3 --> F4[subagent-driven-development / executing-plans]
+    F4 --> F5[test-driven-development]
+    F5 --> F6[verification-before-completion]
+    F6 --> F7[requesting-code-review]
+    F7 --> F8[finishing-a-development-branch]
+```
+
+| 단계 | 스킬 (Skill) | 역할 및 산출물 |
+| :--- | :--- | :--- |
+| **1. 요구사항 및 설계** | `brainstorming` | 요구사항, 제약사항, 아키텍처 결정을 명확히 하고 공유 이해 확인과 플래닝 핸드오프 리뷰를 거쳐 설계 스펙(Spec) 산출. |
+| **2. 계획 수립** | `writing-plans` | 스펙을 독립 검증 가능한 태스크 목록으로 분해하고 Recommended Skill 명시. |
+| **3. 환경 격리** | `using-git-worktrees` | 격리된 Git Worktree를 생성하여 메인 브랜치와 작업 환경 보호. |
+| **4. 태스크 실행** | `subagent-driven-development` | 독립된 서브에이전트를 순차 실행하여 깨끗한 컨텍스트 유지. |
+| **5. 로직 구현** | `test-driven-development` | 각 태스크의 비즈니스 로직에 대해 Red ➔ Green ➔ Refactor 주기 엄격 준수. |
+| **6. 전체 검증** | `verification-before-completion` | 전체 테스트 스위트, Linter, 타입 검사를 실행하여 회귀가 없음을 확인. 테스트 명령이 없으면 산출물을 다시 열어 요청 사항을 빠짐없이 점검. |
+| **7. 코드 리뷰** | `requesting-code-review` | 리뷰 패키지를 생성하고 다각적인 코드 및 아키텍처 리뷰 수행. |
+| **8. 브랜치 마무리** | `finishing-a-development-branch` | 보류 발견을 내보낸 뒤(PR 체크리스트 또는 follow-ups 파일) 병합/PR, Worktree 정리, 임시 브랜치 삭제를 수행. |
+
+---
+
+### 파이프라인 2: 구조화된 문제 해결 (Structured Troubleshooting Pipeline)
+**권장 시나리오:** 다중 테스트 실패, 재현하기 어려운 버그, 프로덕션 장애 조사.
+
+```mermaid
+flowchart LR
+    D1[systematic-debugging] --> D2[using-git-worktrees]
+    D2 --> D3[dispatching-parallel-agents]
+    D3 --> D4[test-driven-development]
+    D4 --> D5[verification-before-completion]
+    D5 --> D6[requesting-code-review]
+    D6 --> D7[finishing-a-development-branch]
+```
+
+1. **`systematic-debugging`**: 근본 원인을 분석하고 독립적으로 검증 가능한 가설로 분해.
+2. **`using-git-worktrees`**: 병렬 조사를 위한 격리된 Worktree를 준비하여 테스트 및 파일 간섭 방지.
+3. **`dispatching-parallel-agents`**: 서브에이전트를 병렬 디스패치하여 각 가설 검증.
+4. **`test-driven-development`**: 버그를 재현하는 최소한의 실패 테스트를 작성한 후 수정 적용.
+5. **`verification-before-completion`**: 모든 테스트가 성공적으로 통과하는지 검증.
+6. **`requesting-code-review`** (및 `receiving-code-review`): 수정 사항과 회귀 테스트 적용 범위 검토 및 지적 사항 해결.
+7. **`finishing-a-development-branch`**: 버그 수정 브랜치를 병합/PR하고 임시 Worktree를 안전하게 정리.
+
+---
+
+### 파이프라인 3: 대규모 리팩토링 및 시스템 마이그레이션 (Large Refactoring & Migration Pipeline)
+**권장 시나리오:** 핵심 아키텍처 재구축, 프레임워크 업그레이드, 서비스 분리.
+
+```mermaid
+flowchart LR
+    R1[brainstorming] --> R2["writing-plans (skeleton-first)"]
+    R2 --> R3[using-git-worktrees]
+    R3 --> R4[subagent-driven-development]
+    R4 --> R5[verification-before-completion]
+    R5 --> R6[requesting-code-review]
+    R6 --> R7[finishing-a-development-branch]
+```
+
+1. **`brainstorming`**: 인터페이스 호환성, 전환 전략, 동등성 검증 기준 정의.
+2. **`writing-plans` (Skeleton-First 모드)**: 모든 서브시스템을 관통하는 최소 엔드투엔드 뼈대 설계.
+3. **`using-git-worktrees`**: 마이그레이션 전용 장기 Worktree 구성.
+4. **`subagent-driven-development`**: 단계별 리팩토링을 수행하고 태스크별 검토 게이트 유지.
+5. **`verification-before-completion`** + **`requesting-code-review`**: 완전한 회귀 검증 및 전문가 아키텍처 검토.
+6. **`finishing-a-development-branch`**: 마이그레이션 브랜치를 병합하고 Worktree를 정리하여 완료.
+
+---
+
+### 파이프라인 4: 레거시 코드베이스 안전망 구축 (Legacy Codebase Safety Net)
+**권장 시나리오:** 단위 테스트가 부족하거나 구조가 복잡한 레거시 코드베이스.
+
+```mermaid
+flowchart LR
+    L1[brainstorming] --> L2[writing-plans]
+    L2 --> L3["test-driven-development (characterization)"]
+    L3 --> L4[systematic-debugging]
+    L4 --> L5[verification-before-completion]
+```
+
+1. **`brainstorming`**: 핵심 비즈니스 경로와 고위험 모듈 식별.
+2. **`writing-plans`**: 특성화 테스트(Characterization Tests) 추가 로드맵 수립.
+3. **`test-driven-development`**: TDD 특성화 가드(변이 → 실패 확인 → VCS 복원 → 그린 유지)로 기존 동작에 대한 골든 마스터 및 회귀 테스트 작성.
+4. **`systematic-debugging`**: 테스트 추가 과정에서 발견된 잠재 결함 해결.
+5. **`verification-before-completion`**: 자동화된 CI 테스트 장벽 구축.
+
+---
+
+## 4. 계획 기반 스킬 구성 스키마 (Plan-Driven Skill Metadata Schema)
+
+`writing-plans`로 생성된 구현 계획에서 각 태스크별 권장 스킬을 지정할 수 있습니다:
+
+```markdown
+### Task 1: 토큰 인증 미들웨어 구현
+- **Goal**: JWT 토큰 검증 및 클레임 추출
+- **Target Files**: `src/auth/jwt.ts`, `tests/auth/jwt.test.ts`
+- **Recommended Skill**: `superpowers:test-driven-development`
+- **Task Brief**:
+  1. 만료 및 유효하지 않은 서명에 대한 실패 테스트 작성 (FAIL)
+  2. 최소한의 검증 로직을 구현하여 테스트 통과 (PASS)
+  3. 엄격한 타입 안전성을 확보하며 리팩토링
+```
+
+### 컨트롤러와 서브에이전트 디스패치 프로토콜
+컨트롤러 에이전트가 태스크 서브에이전트를 생성할 때:
+1. 컨트롤러는 계획 작업에 명시된 `Recommended Skill`을 읽습니다.
+2. 컨트롤러는 `read_skill(skill_name)`을 통해 해당 스킬을 로드하도록 서브에이전트에 지시합니다.
+3. 서브에이전트는 해당 스킬의 엄격한 방법론(Red-Green-Refactor 등)을 준수하여 구현을 진행합니다.
+
+---
+
+## 5. 네이티브 MCP Prompts 레퍼런스
+
+`superpowers-mcp`는 주요 IDE(Cursor, Antigravity, VS Code, Devin Desktop 등)에서 즉시 사용할 수 있는 표준 Prompts를 제공합니다:
+
+| MCP Prompt 명 | 매개변수 | 용도 |
+| :--- | :--- | :--- |
+| **`feature-pipeline`** | 필수 `feature_name`, 선택 `requirements` | 대화형 새 기능 개발 워크플로 런처. |
+| **`structured-debug`** | `issue_description`, `failing_tests` | 대화형 체계적 디버깅 런처이며 호스트 지원 시 병렬 조사도 수행합니다. |
+| **`skill-composition`** | `scenario` | 개발 시나리오에 맞춘 동적 스킬 조합 가이드. |
+| **`session-start`** | - | Superpowers 기본 환경 및 스킬 호출 규칙 주입. |
+| **`sdd-implementer`** | `brief_file`, `task_name`, ... | SDD 태스크 구현 서브에이전트 프롬프트. |
+| **`sdd-task-reviewer`** | `brief_file`, `report_file`, `review_file`, ... | SDD 단일 태스크 검토 서브에이전트 프롬프트. |
+| **`sdd-re-review`** | `brief_file`, `review_file`, `previous_findings`, ... | SDD 수정 라운드 차분 검토 프롬프트. |
+| **`spec-reviewer`** | `spec_file` | 설계 스펙 검토 프롬프트. |
+| **`plan-reviewer`** | `plan_file`, `spec_file` | 구현 계획 검토 프롬프트. |
+
+---
+
+## 6. IDE에서 실제로 사용하는 방법 (How to Use in Practice)
+
+`superpowers-mcp`를 설정하면 **14개의 개별 스킬 이름을 일일이 기억할 필요가 없습니다**. 아래의 두 가지 간단한 방법으로 시작할 수 있습니다:
+
+### 방법 A: 클라이언트의 MCP Prompts 메뉴 사용 (권장)
+Cursor, Antigravity, VS Code, Devin Desktop 등의 대화창에서:
+1. **새 기능 개발**: Prompts 메뉴에서 `feature-pipeline`을 선택하고 필수 `feature_name`과 선택적 `requirements`를 입력합니다. 실제 slash command 이름은 클라이언트에 따라 다르며 MCP server namespace가 포함될 수 있습니다.
+2. **버그 해결 / 테스트 실패**: `structured-debug`를 선택하고 오류 로그 또는 실패한 테스트를 붙여넣습니다.
+3. **적절한 흐름을 모를 때**: `skill-composition`을 선택하여 현재 상황에 맞는 맞춤형 파이프라인을 추천받습니다.
+
+### 방법 B: 자연어로 직접 지시하기
+일반 대화에서도 아래처럼 요청할 수 있지만 네이티브 MCP prompt가 조회된다는 보장은 없습니다. 확실하게 사용하려면 MCP Prompts 메뉴를 선택하세요:
+- *"`feature-pipeline` 흐름에 따라 [기능 이름] 개발을 진행해줘."*
+- *"`structured-debug` 프로세스를 사용하여 다음 오류를 분석하고 수정해줘: [오류 로그]"*
+- *"`docs/skill-compositions.ko.md`의 리팩토링 파이프라인에 따라 [모듈 이름]을 리팩토링해줘."*
+
+### 💬 실제 상호작용 예시 (새 기능 개발 기준):
+```text
+[사용자]: (MCP Prompts 메뉴에서 `feature-pipeline`을 선택하고 쿠폰 기능 입력)
+  ↓
+[AI]: (`read_skill`로 brainstorming 로드) "쿠폰의 유효기간이 있는지, 다른 할인과 중복 적용이 가능한지 확인 부탁드립니다."
+  ↓
+[사용자]: "유효기간이 있고, 중복 적용은 불가능합니다."
+  ↓
+[AI]: (설계 승인 후 writing-plans 로드) "docs/superpowers/plans/...에 구현 계획을 작성했습니다. 검토해 주세요."
+  ↓
+[사용자]: "계획 좋습니다. 진행해 주세요."
+  ↓
+[AI]: (Worktree 격리 ➔ SDD 시작 ➔ 각 태스크를 TDD로 구현 ➔ 전체 테스트 검증 ➔ 코드 리뷰 ➔ 브랜치 마무리)
+  ↓
+[AI]: "모든 태스크와 전체 테스트 스위트가 100% 통과했습니다. 리뷰 완료 및 브랜치가 준비되었습니다!"
+```