superpowers-mcp 6.4.2 → 6.4.4

package/README.zh-TW.md

@@ -1,8 +1,8 @@
 # Superpowers MCP Toolpack 使用指南
 
-[English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
+[English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Español](README.es.md) | [Português (BR)](README.pt-BR.md) | [हिन्दी](README.hi.md)
 
-[![版本](https://img.shields.io/badge/version-6.4.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.4.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,8 +13,8 @@
 
 ### 支援的環境與 Agent 平台
 
-- **AI 程式碼編輯器與 IDE**：**Antigravity (AGY)**、**Cursor**、**VSCode**（GitHub Copilot）、**VSCode Insiders**（GitHub Copilot）、**Devin Desktop**、**Trae**、**Cline**、**Kilo Code**、**Qoder**、**Kiro**、**MiniMax Code Desktop**、**Codex**。
-- **AI 桌面應用與 Agent 工具**：**Claude Desktop**、**Pi Desktop**、**QwenPaw**、**Hermes Desktop**、**Kimi Work**。
+- **AI 程式碼編輯器與 IDE**：**Antigravity (AGY)**、**Cursor**、**VSCode**（GitHub Copilot）、**VSCode Insiders**（GitHub Copilot）、**Devin Desktop**、**Trae**、**Cline**、**Kilo Code**、**Qoder**、**Kiro**、**MiniMax Code Desktop**（需手動配置）、**Codex**。
+- **AI 桌面應用與 Agent 工具**：**Claude Desktop**、**Pi Desktop**、**QwenPaw**、**Hermes Desktop**、**Kimi Work**、**Goose**、**OpenClaw**。
 - **開源與私有化 AI 平台**：**AnythingLLM**、**LibreChat**。
 
 ### 提供之 MCP 協議功能
@@ -43,10 +43,7 @@
 > [!NOTE]
 > **可在系統任何目錄下直接執行**：您不需要預先切換到特定專案目錄，也無須 clone 本儲存庫。在終端機的**任意目錄**皆可直接執行以下指令！安裝程式會自動鎖定您系統中的全域設定檔（以使用者家目錄為基準），一次設定、全域與所有專案皆可自動生效。
 
-桌面版快速安裝：[LM Studio、Roo Code、ChatWise 與 Cherry Studio](docs/desktop-setup.md)。以下新增的 CLI 選項尚未發布至 npm；發布前請使用指南中的本機指令。
-
-> [!TIP]
-> **透明與零污染保護原則**：Superpowers 絕不會像惡意軟體般擅自全域掃描或批量改寫您未指定的其他編輯器。您使用哪一款 AI 工具，就執行該工具的專屬一鍵指令，完全透明、可控且安全無損（採用**原子寫入技術**，保證斷電不壞檔，且**預設零磁碟垃圾殘留**，不隨意產生 `.bak`，亦絕不影響原有其他 MCP 伺服器）。
+ChatWise 與 Cherry Studio 需手動匯入，請見[桌面版匯入指南](docs/desktop-setup.md)。
 
 ### 1. 選擇您的 AI Agent / 編輯器（一鍵精準設定）
 
@@ -71,6 +68,9 @@
 | **Qoder** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target qoder` | `~/.qoder/settings.json` |
 | **Kiro** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target kiro` | `~/.kiro/settings/mcp.json` |
 | **Trae** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target trae` | `.../Trae/User/mcp.json` *(支援 Trae CN)* |
+| **Codex** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target codex` | `~/.codex/config.toml` *(TOML `[mcp_servers]`)* |
+| **OpenClaw** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target openclaw` | `~/.openclaw/openclaw.json` *(JSON5 `mcp.servers`)* |
+| **Goose** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target goose` | `~/.config/goose/config.yaml` *(Win: `%APPDATA%\Block\goose\config\config.yaml`)* |
 
 *(若偏好使用 Bun，指令可加上 `--bun`，例如 `npx -y superpowers-mcp setup --target cursor --bun`)*
 
@@ -135,18 +135,18 @@
 ```
 brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **啟動方式：**從客戶端的 MCP Prompts 選單選取 `feature-pipeline`，提供必要的 `feature_name` 與選填的 `requirements`。
+- **啟動方式**：從客戶端的 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
 ```
-- **啟動方式：**從 MCP Prompts 選單選取 `structured-debug`，提供錯誤描述或失敗測試。
+- **啟動方式**：從 MCP Prompts 選單選取 `structured-debug`，提供錯誤描述或失敗測試。
 - **流程特色：** 根因分析拆解假說 ➔ Worktree 隔離平行排查 ➔ 多 Agent 驗證 ➔ 編寫失敗測試並修復 ➔ 全套迴歸驗證 ➔ 審查結果解決 ➔ 分支合併收尾。
 
 ### 3. 動態技能導引 (Dynamic Workflow Guide)
-- **啟動方式：**選取 `skill-composition` 取得重構、遷移或舊系統的流程建議；這些情境目前沒有各自獨立的啟動 prompt。
+- **啟動方式**：選取 `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`
@@ -178,7 +178,26 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 最近更新
 
-### v6.4.2 (最新版)
+### v6.4.4（最新版）
+
+- **CodeQL 修復與安全更新（2026-09-28）**：
+  - Code scanning 已 **0 未修復 / 7 已修復**：補上 v6.4.3 通報的 3 個 `src/setup-runner.ts` 警報（詳見 [SECURITY.md](SECURITY.md)）。
+  - **TOML ReDoS 修復**：引號表格偵測 regex 改為線性掃描，惡意設定行不再造成多項式回溯；fail-closed 行為不變。
+  - **原型污染防護**：巢狀 JSON `serverPath`（`openclaw` 目標使用）寫入前拒絕 `__proto__` / `constructor` / `prototype` 與非識別字 key。
+  - 合法設定行為不變；驗證：`npm test` 全綠（基準 **389/389**），`tsc` 乾淨，`npm audit` 0 漏洞。
+
+### v6.4.3
+
+- **Codex 支援與文件清理（2026-09-28）**：
+  - 新增 `codex` 一鍵目標：`setup --target codex` 寫入 `~/.codex/config.toml`（`[mcp_servers.superpowers]`），零依賴 TOML 合併，支援 `--dry-run` / `--backup` / `--bun` / `--remove`。
+  - 新增 `openclaw` / `goose` 目標：前者寫入 `~/.openclaw/openclaw.json`（`mcp.servers`）；後者寫入 goose `config.yaml` 的 `extensions` 區塊（保留使用者的 `enabled`/`timeout`/`envs`）。
+  - 刪除設定章節多餘的「透明與零污染」TIP（與一鍵設定標題重複）；安全細節保留於進階參數與 SECURITY.md。
+  - `docs/desktop-setup.md` 改為純英文的 ChatWise / Cherry Studio 匯入指南（`setup --print-config`）；LM Studio / Roo Code 維持表格一鍵指令。刪除過時的「尚未發布」說明（`lmstudio`、`roo`、`--print-config` 已於 v6.3.9 發布）。
+  - 補上 7 語系 README 導覽（新增西 / 葡 / 印版本）、西 / 葡 / 印 skill-composition 指南，以及 CJK 粗體符號修正。
+  - MiniMax Code Desktop 標註（需手動配置）（設定檔路徑未驗證）。
+  - 驗證：`npm test` 全綠，基準 389/389（新增 17 個 setup-target 案例），`npm audit` 0 漏洞。
+
+### v6.4.2
 
 - **v6.4.2 安全審計與程式碼審計（2026-09-24）**：補上 MCP 伺服器、安裝腳本、建置管線與測試工具的審計缺口（詳見 [SECURITY.md](SECURITY.md)）。
   - **路徑穿越與錯誤訊息修正**：技能名稱先解碼再通過白名單驗證，double-encoding 的 `..%2f` / `%2e%2e` 載荷會以 `InvalidParams` 拒絕；未知工具與 Prompt 改回傳具體可操作的 `InvalidParams`，不再誤報 `MethodNotFound`。

package/docs/desktop-setup.md

@@ -1,46 +1,16 @@
-# Desktop quick setup / 桌面版快速安裝
+# Desktop import guide
 
-The new `lmstudio`, `roo` and `--print-config` options are unreleased. Until the next npm release, run from a checkout:
+This guide covers ChatWise and Cherry Studio, which require manual JSON import.
 
 ```bash
-npm ci
-npm run build
-node out/setup.js --target lmstudio
-# Or choose Roo Code in VS Code Desktop:
-node out/setup.js --target roo
-# Or print JSON to import into a desktop app:
-node out/setup.js --print-config
+npx -y superpowers-mcp setup --print-config
 ```
 
-目前新增選項尚未發布至 npm。發布前請使用上方本機指令；設定中的 MCP 伺服器仍透過 npm 啟動已發布版本。
-
 Install Node.js with npm first and restart the desktop app after saving its configuration. If a GUI cannot find `npx`, use its absolute executable path in the app's MCP configuration (`command -v npx` on macOS/Linux; `where.exe npx` on Windows). This installs the Superpowers MCP connection, not the desktop application. Tool execution also depends on the model and the client's available capabilities.
 
-## File-based desktop setup
-
-After the next npm release:
-
-```bash
-npx -y superpowers-mcp setup --target lmstudio
-npx -y superpowers-mcp setup --target roo
-```
-
-Run only the command for the client you want. Both targets support `--dry-run`, `--backup`, `--bun` and `--remove`. `lm-studio` aliases `lmstudio`; `roo-code` and `roocode` alias `roo`.
-
-| Client | Configuration location |
-| --- | --- |
-| LM Studio, all three OSes | User home + `.lmstudio/mcp.json` |
-| Roo Code, macOS | `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
-| Roo Code, Windows | `%APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
-| Roo Code, Linux | `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
-
-Roo setup targets the standard VS Code Desktop profile. For Insiders, portable builds, remote VS Code or a custom storage location, open Roo's **Edit Global MCP** configuration and merge the JSON below into its existing `mcpServers` object.
-
-LM Studio: open **Program → Install → Edit mcp.json** to inspect the configuration, then enable the integration for your chat. Select a model that supports tool use.
-
 ## ChatWise and Cherry Studio
 
-Copy this complete JSON, or generate it with `node out/setup.js --print-config` (`--bun` selects `bunx`). After release, the equivalent command is `npx -y superpowers-mcp setup --print-config`.
+Copy this complete JSON, or generate it with `npx -y superpowers-mcp setup --print-config` (`--bun` selects `bunx`).
 
 ```json
 {
@@ -55,32 +25,22 @@ Copy this complete JSON, or generate it with `node out/setup.js --print-config`
 
 ### ChatWise
 
-[Add Superpowers to ChatWise / 一鍵加入 ChatWise](https://chatwise.app/mcp-add?json=eyJtY3BTZXJ2ZXJzIjp7InN1cGVycG93ZXJzIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15Iiwic3VwZXJwb3dlcnMtbWNwIl19fX0%3D)
+[Add Superpowers to ChatWise](https://chatwise.app/mcp-add?json=eyJtY3BTZXJ2ZXJzIjp7InN1cGVycG93ZXJzIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15Iiwic3VwZXJwb3dlcnMtbWNwIl19fX0%3D)
 
 ChatWise must already be installed. Alternatively, copy the JSON, open **Settings → Tools → + → Import JSON from Clipboard**, then enable tools for the chat. Use the MCP Tools chat workflow: ChatWise's current Agent preview documents MCP as disabled in that mode.
 
-先安裝 ChatWise，再點上方連結；也可以在 Tools 設定從剪貼簿匯入 JSON，並在對話開啟工具。請使用支援 MCP Tools 的對話模式，目前 Agent 預覽模式不支援 MCP。
-
 ### Cherry Studio
 
 Open **Settings → MCP → MCP Servers → Add → Import from JSON**, paste the JSON, save and enable the server. If using manual creation, choose **stdio**, name `superpowers`, command `npx`, and two separate arguments: `-y` and `superpowers-mcp`. Then open **Work → Agent menu → Edit → MCP** and enable this server for the intended Agent.
 
-在「設定 → MCP → MCP 伺服器 → 新增」匯入 JSON，儲存並啟動後，到「工作 → Agent 選單 → 編輯 → MCP」綁定。只加入伺服器、未綁定 Agent 時，Agent 不會取得工具。
-
 ## Verify the connection
 
 Ask the assistant: **Use `list_skills` to list the Superpowers skills, then use `read_skill` to read `brainstorming`.** Confirm that actual tool results appear. Prompts and resources vary by client; the tool-based path is the common verification route.
 
-Hermes users can now keep inline comments such as `mcp_servers: # configured servers`; setup also recognizes `superpowers: # my agent` during update and removal.
-
 ## References
 
-- [LM Studio MCP configuration and paths](https://lmstudio.ai/blog/lmstudio-v0.3.17)
-- [LM Studio MCP usage](https://lmstudio.ai/docs/app/mcp)
-- [Roo Code MCP configuration](https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo/)
-- [Roo Code storage and configuration migration](https://github.com/RooCodeInc/Roo-Code/issues/8520)
 - [ChatWise JSON import and install links](https://docs.chatwise.app/tools)
 - [ChatWise Agent preview limitations](https://docs.chatwise.app/agent)
 - [Cherry Studio MCP setup and Agent binding](https://docs.cherryai.com.cn/advanced-basic/extensions/mcp)
 
-Paths and import formats were checked against these sources on 2026-09-13. Automated checks exercise configuration generation, preservation and removal; desktop GUI connections have not been tested on physical Windows/Linux installations.
+Import formats were checked against these sources on 2026-09-13. Automated checks exercise configuration generation, preservation and removal; desktop GUI connections have not been tested on physical Windows/Linux installations.

package/docs/skill-compositions.es.md

@@ -0,0 +1,220 @@
+# Superpowers MCP: Composición de skills y flujos de trabajo
+
+[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md) | [Español](skill-compositions.es.md) | [Português (BR)](skill-compositions.pt-BR.md) | [हिन्दी](skill-compositions.hi.md)
+
+> **Fuente de verdad:** este documento en inglés es canónico. Actualízalo primero cuando cambie el comportamiento de los skills y luego sincroniza las traducciones.
+
+
+## 1. Elige un flujo de trabajo
+
+Estos prompts son **lanzadores de flujo de trabajo interactivos**, no automatización en el servidor. Seleccionar uno añade instrucciones estructuradas a la conversación; el agente anfitrión debe tener acceso a archivos, terminal y Git, y debe llamar a `read_skill` en cada etapa. El flujo se detiene siempre que un skill requiera aprobación de diseño, revisión del plan o una decisión de finalización de rama.
+
+| Objetivo | MCP Prompt | Qué hace |
+| :--- | :--- | :--- |
+| Construir una funcionalidad nueva | `feature-pipeline` | Inicia el flujo interactivo completo de funcionalidades. |
+| Investigar y corregir un bug complejo | `structured-debug` | Inicia el flujo estructurado de depuración. |
+| Planificar una gran refactorización o migración | `skill-composition` con escenario de refactorización | Recomienda el Pipeline 3; aún no hay un prompt lanzador dedicado. |
+| Estabilizar un código heredado | `skill-composition` con escenario heredado | Recomienda el Pipeline 4; aún no hay un prompt lanzador dedicado. |
+
+El método de invocación portable es el **menú de MCP Prompts** de tu cliente. Los nombres de slash-command varían según el cliente y pueden incluir el nombre del servidor MCP configurado. Mencionar un prompt por su nombre en el chat ordinario no garantiza que el cliente recupere ese MCP prompt.
+
+La misma guía se expone a los clientes MCP como `guide://superpowers/skill-compositions`.
+
+### Requisitos previos
+
+- Ejecuta en una sesión de agente con acceso al repositorio objetivo, archivos, terminal y Git.
+- Crear worktrees requiere un repositorio Git y permiso para crear ramas y directorios.
+- `subagent-driven-development` requiere herramientas multiagente del host. Cuando no están disponibles, `feature-pipeline` usa `executing-plans` como alternativa integrada.
+- Los pushes, pull requests, merges y limpiezas destructivas siguen siendo decisiones explícitas del usuario.
+
+## 2. Por qué importan las composiciones de skills
+
+Los 15 skills principales de `superpowers-mcp` abarcan todo el ciclo de vida del desarrollo de software (SDLC): desde descubrimiento de requisitos, planificación de arquitectura, configuración de espacios aislados, desarrollo guiado por pruebas (TDD) y depuración sistemática, hasta verificación completa, revisión de código e integración de ramas.
+
+Mientras cada skill atómico actúa como una herramienta de ingeniería de precisión, el desarrollo de nivel productivo requiere **orquestación de flujos**. Las composiciones convierten interacciones ad-hoc con la IA en pipelines disciplinados, reproducibles y con protecciones de seguridad.
+
+---
+
+## 3. Principios arquitectónicos fundamentales
+
+Al componer skills, aplica siempre estos cinco mecanismos de seguridad:
+
+1. **Aislamiento primero (con Git Worktrees)**: Siempre que coordines varios subagentes o depures hipótesis independientes en paralelo, usa `superpowers:using-git-worktrees` para evitar condiciones de carrera y contaminación del espacio de trabajo.
+2. **TDD por defecto**: Ninguna modificación de código sin una prueba que falle primero (ciclo Rojo-Verde-Refactorización) para garantizar seguridad contra regresiones.
+3. **Puertas de revisión de doble capa**: Nunca omitas las comprobaciones de cumplimiento de spec por tarea ni las revisiones de rama por funcionalidad (`requesting-code-review` / `receiving-code-review`).
+4. **Verificación completa antes de finalizar**: Ejecuta toda la suite de pruebas, el verificador de tipos y el linter (`verification-before-completion`) antes de declarar listo o fusionar ramas.
+5. **Frontera de seguridad remota (solo commits locales)**: Mantén los commits en local — sin push/pull/fetch salvo que el plan o tu compañero humano lo indique. Crea la rama desde una ref compartida con `--no-track` (o `--unset-upstream` antes del primer commit) para que la rama de funcionalidad nunca rastree una rama compartida, y nunca reescribas una rama compartida (`git revert` es el único remedio que aplicas tú mismo).
+
+---
+
+## 4. Cuatro pipelines estándar
+
+### Pipeline 1: Desarrollo de funcionalidades de extremo a extremo
+**Ideal para:** Construir funcionalidades nuevas, módulos grandes o mejoras de subsistemas centrales.
+
+```mermaid
+flowchart LR
+    F1[brainstorming] --> F2[writing-plans]
+    F2 --> F3[using-git-worktrees]
+    F3 --> F4["subagent-driven-development / executing-plans (with TDD)"]
+    F4 --> F5[verification-before-completion]
+    F5 --> F6[requesting-code-review]
+    F6 --> F7[finishing-a-development-branch]
+```
+
+| Paso | Skill | Responsabilidad y entregable |
+| :--- | :--- | :--- |
+| **1. Requisitos y diseño** | `brainstorming` | Aclara intención, restricciones, decisiones de arquitectura y casos borde; confirma entendimiento compartido, ejecuta la revisión de traspaso a planificación y produce la Spec de diseño. |
+| **2. Construcción del plan** | `writing-plans` | Descompone la Spec en tareas pequeñas y verificables con Recommended Skills. |
+| **3. Aislamiento del espacio** | `using-git-worktrees` | Crea un worktree Git aislado para proteger la rama principal y el trabajo activo. |
+| **4. Ejecución de tareas** | `subagent-driven-development` o `executing-plans` | Usa subagentes nuevos cuando el host los soporta; si no, ejecuta en línea. Carga `test-driven-development` para tareas de implementación y aplica Rojo ➔ Verde ➔ Refactorización. |
+| **5. Verificación completa** | `verification-before-completion` | Ejecuta toda la suite de pruebas, linter y comprobaciones de tipos para cero regresiones; cuando no hay comando de pruebas, reabre el artefacto y da cuenta de cada parte de la solicitud. |
+| **6. Revisión adversarial** | `requesting-code-review` | Ensambla el paquete de revisión y realiza revisiones integrales de código y arquitectura. |
+| **7. Finalización de rama** | `finishing-a-development-branch` | Exporta hallazgos diferidos (checklist de PR o archivo de seguimientos), presenta las opciones de merge/PR/conservar y ejecuta solo la opción elegida. |
+
+---
+
+### Pipeline 2: Resolución estructurada y depuración multifallo
+**Ideal para:** Bugs complejos, tests inestables, múltiples fallos o incidentes en producción.
+
+```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`**: Investiga causas raíz y divide los fallos en hipótesis distintas y verificables.
+2. **`using-git-worktrees`**: Prepara worktrees aislados para investigaciones paralelas y evita interferencias entre pruebas.
+3. **`dispatching-parallel-agents`**: Despacha subagentes concurrentes para validar o invalidar cada hipótesis.
+4. **`test-driven-development`**: Escribe pruebas mínimas de reproducción que fallen antes de aplicar correcciones específicas.
+5. **`verification-before-completion`**: Valida que todas las pruebas del repositorio pasen con salidas limpias.
+6. **`requesting-code-review`** (y `receiving-code-review`): Revisa el delta de la corrección, asegura cobertura defensiva de regresión y resuelve los hallazgos.
+7. **`finishing-a-development-branch`**: Fusiona la rama del bugfix, elimina worktrees temporales y limpia el espacio.
+
+---
+
+### Pipeline 3: Refactorización grande y migración de sistemas
+**Ideal para:** Refactors arquitectónicos, migraciones de framework o desacoplamiento de servicios.
+
+```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`**: Define contratos de interfaz, estrategias de transición y criterios de paridad.
+2. **`writing-plans` (modo Skeleton-First)**: Diseña primero el slice end-to-end más delgado entre todos los subsistemas.
+3. **`using-git-worktrees`**: Establece worktrees de migración dedicados y duraderos.
+4. **`subagent-driven-development`**: Ejecuta tareas de refactorización por fases con puertas de revisión obligatorias por tarea.
+5. **`verification-before-completion`** + **`requesting-code-review`**: Verificación total de regresión y revisión arquitectónica.
+6. **`finishing-a-development-branch`**: Fusiona la rama de migración, limpia worktrees y finaliza la entrega.
+
+---
+
+### Pipeline 4: Red de seguridad para código heredado
+**Ideal para:** Códigos heredados sin cobertura automatizada ni patrones consistentes.
+
+```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`**: Identifica rutas críticas de negocio y módulos de alto riesgo.
+2. **`writing-plans`**: Crea la hoja de ruta para añadir pruebas de caracterización y de borde.
+3. **`test-driven-development`**: Crea pruebas golden-master y de regresión contra comportamientos existentes con la guardia de caracterización TDD (mutar, verificar fallo, restaurar vía VCS, stay green).
+4. **`systematic-debugging`**: Encuentra defectos ocultos que emergen al establecer baselines.
+5. **`verification-before-completion`**: Consolida barreras de CI automatizadas.
+
+### Meta skill: Forense de sesiones
+
+Fuera de los cuatro pipelines, **`diagnosing-superpowers`** reconstruye qué falló en una sesión pasada desde sus transcripciones en disco: entrevista inicial, descubrimiento de sesión, informes paralelos con evidencia citada y luego un paquete depurado opcional o borrador de GitHub issue. Úsalo cuando una sesión ignoró el plan, repitió trabajo o produjo un resultado inexplicable — y cuando el hallazgo pertenece upstream, también redacta el informe para mantenedores. El servidor MCP solo sirve el contenido del skill; el agente lee los archivos de transcripción del host con sus propias herramientas, así que ninguna transcripción cruza la frontera del servidor.
+
+---
+
+## 5. Esquema de metadatos de skills en planes
+
+En planes generados por `writing-plans`, especifica los skills recomendados por tarea:
+
+```markdown
+### Task 1: Implement Token Authentication Middleware
+- **Goal**: Validate JWT tokens and extract user claims
+- **Target Files**: `src/auth/jwt.ts`, `tests/auth/jwt.test.ts`
+- **Recommended Skill**: `superpowers:test-driven-development`
+- **Task Brief**:
+  1. Write failing test for expired and invalid signatures (FAIL)
+  2. Implement minimal signature verification (PASS)
+  3. Refactor with strict type safety
+```
+
+### Protocolo de despacho controlador → subagente
+Cuando el agente controlador despacha un subagente de tarea:
+1. El controlador lee el `Recommended Skill` indicado en la tarea del plan.
+2. El controlador inyecta instrucciones o guía al subagente para cargar ese skill vía `read_skill(skill_name)`.
+3. El subagente ejecuta bajo la metodología estricta de ese skill (p. ej. Red-Green-Refactor).
+
+---
+
+## 6. Referencia de MCP Prompts nativos
+
+`superpowers-mcp` ofrece MCP prompts nativos listos para usar en IDEs (Cursor, Antigravity, VS Code, Devin Desktop):
+
+| MCP Prompt | Argumentos | Propósito |
+| :--- | :--- | :--- |
+| **`feature-pipeline`** | `feature_name` requerido, `requirements` opcional | Lanzador interactivo de desarrollo de funcionalidades end-to-end. |
+| **`structured-debug`** | `issue_description`, `failing_tests` | Lanzador interactivo de depuración sistemática e investigación multiagente opcional. |
+| **`skill-composition`** | `scenario` | Recomendador dinámico de composición para tareas de funcionalidad, debug, refactor o legado. |
+| **`session-start`** | - | Inyecta el contexto fundacional de Superpowers y reglas de invocación. |
+| **`sdd-implementer`** | `brief_file`, `task_name`, ... | Plantilla de prompt de subagente implementador de tareas SDD. |
+| **`sdd-task-reviewer`** | `brief_file`, `report_file`, `review_file`, ... | Plantilla de prompt revisor de spec y calidad por tarea SDD. |
+| **`sdd-re-review`** | `brief_file`, `review_file`, `previous_findings`, ... | Plantilla de re-revisor SDD de alcance de ronda de corrección. |
+| **`spec-reviewer`** | `spec_file` | Plantilla de prompt revisor adversarial de specs de diseño. |
+| **`plan-reviewer`** | `plan_file`, `spec_file` | Plantilla de prompt revisor adversarial de planes de implementación. |
+
+---
+
+## 7. Guía práctica de uso
+
+Con `superpowers-mcp` instalado, parte de un MCP prompt nativo y deja que sus instrucciones carguen los skills necesarios.
+
+### Método A: Menú de MCP Prompts (recomendado)
+En un cliente con soporte de MCP prompts:
+1. Confirma que el servidor MCP `superpowers` configurado está conectado.
+2. **Nueva funcionalidad**: Selecciona `feature-pipeline` e indica `feature_name` más `requirements` opcional.
+3. **Resolución y bugfixes**: Selecciona `structured-debug` y pega los logs de error o nombres de pruebas que fallan.
+4. **Tareas personalizadas / arquitectura**: Selecciona `skill-composition` para que la IA recomiende el mejor pipeline para tu escenario.
+
+Tu cliente también puede exponer un slash command con namespace. Consulta su selector de prompts para la sintaxis exacta en lugar de asumir que `/feature-pipeline` es portable.
+
+### Método B: Alternativa en lenguaje natural
+Puedes pedir al agente que siga un flujo nombrado, pero esto no garantiza que el cliente recupere el MCP prompt nativo. Para uso determinista, selecciónalo desde el menú de MCP Prompts.
+- *«Sigue el `feature-pipeline` para construir [Nombre de funcionalidad].»*
+- *«Ejecuta el flujo `structured-debug` sobre este error: [Pega error / traza].»*
+- *«Aplica el Pipeline de refactorización de `docs/skill-compositions.es.md` para refactorizar [Módulo].»*
+
+### 💬 Ejemplo interactivo paso a paso:
+```text
+[You]: (Selects the `feature-pipeline` MCP prompt and enters "coupon code checkout system".)
+  ↓
+[AI]: (Loads brainstorming with `read_skill`) "Understood. Does the coupon have an expiry date, and can it stack with site-wide sales?"
+  ↓
+[You]: "It has an expiry date, and it cannot stack."
+  ↓
+[AI]: (After design approval, loads `writing-plans`) "Created implementation plan at docs/superpowers/plans/... Please review."
+  ↓
+[You]: "Looks good, proceed."
+  ↓
+[AI]: (Creates or verifies a worktree ➔ uses SDD or the inline fallback ➔ implements via TDD ➔ verifies ➔ reviews ➔ presents branch-finishing choices)
+  ↓
+[AI]: "All tasks and full test suite passed (100%). Code review clean. Branch ready for merge!"
+```