superpowers-mcp 6.3.6 → 6.3.8

package/docs/skill-compositions.md

@@ -0,0 +1,216 @@
+# Superpowers MCP: Skill Compositions & Workflow Pipelines
+
+[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+
+> **Source of truth:** this English document is canonical. Update it first when skill behavior changes, then sync the translations.
+
+
+## 1. Choose a Workflow
+
+These prompts are **interactive workflow launchers**, not server-side automation. Selecting one adds structured instructions to the conversation; the host agent must have file, terminal, and Git access and must call `read_skill` for each stage. The workflow pauses whenever a skill requires design approval, plan review, or a branch-finishing choice.
+
+| Goal | MCP Prompt | What It Does |
+| :--- | :--- | :--- |
+| Build a new feature | `feature-pipeline` | Starts the complete interactive feature workflow. |
+| Investigate and fix a complex bug | `structured-debug` | Starts the structured debugging workflow. |
+| Plan a large refactor or migration | `skill-composition` with a refactor scenario | Recommends Pipeline 3; there is no dedicated launcher prompt yet. |
+| Stabilize a legacy codebase | `skill-composition` with a legacy scenario | Recommends Pipeline 4; there is no dedicated launcher prompt yet. |
+
+The portable invocation method is your client's **MCP Prompts menu**. Slash-command names vary by client and may include the configured MCP server name. Merely mentioning a prompt name in ordinary chat does not guarantee that the client will retrieve that MCP prompt.
+
+The same guide is exposed to MCP clients as `guide://superpowers/skill-compositions`.
+
+### Prerequisites
+
+- Run in an agent session with access to the target repository, files, terminal, and Git.
+- Worktree creation requires a Git repository and permission to create branches and directories.
+- `subagent-driven-development` requires host-provided multi-agent tools. When unavailable, `feature-pipeline` uses `executing-plans` as its inline fallback.
+- Pushes, pull requests, merges, and destructive cleanup remain explicit user decisions.
+
+## 2. Why Skill Compositions Matter
+
+The 14 core skills in `superpowers-mcp` span the entire software development lifecycle (SDLC): from requirements discovery, architecture planning, isolated workspace setup, test-driven development (TDD), and systematic debugging, to full verification, code review, and branch integration.
+
+While each atomic skill acts as a precision engineering tool, production-grade development requires **workflow orchestration**. Skill compositions transform ad-hoc AI interactions into disciplined, reproducible, and safety-guarded engineering pipelines.
+
+---
+
+## 3. Core Architectural Principles
+
+When composing skills, always enforce these five safety mechanisms:
+
+1. **Isolation First (via Git Worktrees)**: Whenever coordinating multiple subagents or debugging independent hypotheses in parallel, always use `superpowers:using-git-worktrees` to avoid filesystem race conditions and workspace pollution.
+2. **Test-Driven by Default (TDD)**: No code modifications should occur without a failing test first (Red-Green-Refactor cycle) to guarantee regression safety.
+3. **Dual-Layer Review Gates**: Never skip task-level spec compliance checks or feature-level branch reviews (`requesting-code-review` / `receiving-code-review`).
+4. **Full Verification Before Completion**: Run the entire project test suite, type-checker, and linter (`verification-before-completion`) before claiming done or merging branches.
+5. **Remote-Safety Boundary (Local Commits Only)**: Keep commits local — no push/pull/fetch unless the plan or your human partner says so. Branch from a shared ref with `--no-track` (or `--unset-upstream` before the first commit) so a feature branch never tracks a shared branch, and never rewrite a shared branch (`git revert` is the only remedy you apply yourself).
+
+---
+
+## 4. Four Standard Workflow Pipelines
+
+### Pipeline 1: End-to-End Feature Development
+**Ideal for:** Building new features, major modules, or core subsystem enhancements.
+
+```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]
+```
+
+| Step | Skill | Responsibility & Deliverable |
+| :--- | :--- | :--- |
+| **1. Requirements & Design** | `brainstorming` | Clarify intent, constraints, architecture decisions, and edge cases; confirm shared understanding, run the planning-handoff review, and output the Design Spec. |
+| **2. Plan Construction** | `writing-plans` | Decompose Spec into bite-sized, testable tasks annotated with Recommended Skills. |
+| **3. Workspace Isolation** | `using-git-worktrees` | Create an isolated Git worktree to protect the main branch and active work. |
+| **4. Task Execution** | `subagent-driven-development` or `executing-plans` | Use fresh subagents when the host supports them; otherwise execute inline. Load `test-driven-development` for implementation tasks and enforce Red ➔ Green ➔ Refactor. |
+| **5. Full Suite Verification** | `verification-before-completion` | Execute the full test suite, linter, and type checks to ensure zero regressions; when there is no test command, re-open the artifact and account for every part of the request. |
+| **6. Adversarial Review** | `requesting-code-review` | Assemble review package and perform comprehensive code & architecture reviews. |
+| **7. Branch Finalization** | `finishing-a-development-branch` | Export deferred findings (PR checklist or committed follow-ups file), then present the available merge/PR/keep choices and perform only the option the user selects. |
+
+---
+
+### Pipeline 2: Structured Troubleshooting & Multi-failure Debugging
+**Ideal for:** Complex bugs, flaky tests, multiple test failures, or production incidents.
+
+```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`**: Investigate root causes and break failures into distinct, testable hypotheses.
+2. **`using-git-worktrees`**: Provision isolated worktrees for parallel investigations to prevent test interference.
+3. **`dispatching-parallel-agents`**: Dispatch concurrent subagents to validate or invalidate individual hypotheses.
+4. **`test-driven-development`**: Write minimal failing reproduction tests before applying targeted bugfixes.
+5. **`verification-before-completion`**: Validate that all repository tests pass with clean outputs.
+6. **`requesting-code-review`** (and `receiving-code-review`): Review the fix delta, ensure defensive regression test coverage, and resolve review findings.
+7. **`finishing-a-development-branch`**: Merge the bugfix branch, remove temporary worktrees, and clean up workspace.
+
+---
+
+### Pipeline 3: Large Refactoring & System Migration
+**Ideal for:** Architectural refactors, framework migrations, or service decoupling.
+
+```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 interface contracts, transition strategies, and parity validation criteria.
+2. **`writing-plans` (Skeleton-First Mode)**: Design the thinnest end-to-end slice across all subsystems first.
+3. **`using-git-worktrees`**: Establish dedicated long-lived migration worktrees.
+4. **`subagent-driven-development`**: Execute phased refactoring tasks with mandatory per-task review gates.
+5. **`verification-before-completion`** + **`requesting-code-review`**: Full regression verification and architectural review.
+6. **`finishing-a-development-branch`**: Merge migration branch, clean up worktrees, and finalize delivery.
+
+---
+
+### Pipeline 4: Legacy Codebase Safety Net
+**Ideal for:** Legacy codebases lacking automated test coverage or consistent patterns.
+
+```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`**: Identify critical business paths and high-risk modules.
+2. **`writing-plans`**: Create a roadmap for adding characterization and boundary tests.
+3. **`test-driven-development`**: Author golden-master and regression tests against existing behaviors using the TDD characterization guard (mutate, verify failure, restore via VCS, stay green).
+4. **`systematic-debugging`**: Root-cause hidden defects surfaced while establishing test baselines.
+5. **`verification-before-completion`**: Solidify automated CI test barriers.
+
+---
+
+## 5. Plan-Driven Skill Metadata Schema
+
+In plans generated by `writing-plans`, specify recommended skills for each task:
+
+```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
+```
+
+### Controller-to-Subagent Dispatch Protocol
+When the controller agent dispatches a task subagent:
+1. The controller reads the `Recommended Skill` specified in the plan task.
+2. The controller injects instructions or guides the subagent to load that skill via `read_skill(skill_name)`.
+3. The subagent executes under the strict methodology of that skill (e.g., Red-Green-Refactor).
+
+---
+
+## 6. Native MCP Prompts Reference
+
+`superpowers-mcp` provides native, ready-to-use MCP prompts across IDEs (Cursor, Antigravity, VS Code, Devin Desktop):
+
+| MCP Prompt | Arguments | Purpose |
+| :--- | :--- | :--- |
+| **`feature-pipeline`** | required `feature_name`, optional `requirements` | Interactive launcher for end-to-end feature development. |
+| **`structured-debug`** | `issue_description`, `failing_tests` | Interactive launcher for systematic debugging and optional multi-agent investigation. |
+| **`skill-composition`** | `scenario` | Dynamic skill composition recommender for feature, debug, refactor, or legacy tasks. |
+| **`session-start`** | - | Injects foundational Superpowers context and skill invocation rules. |
+| **`sdd-implementer`** | `brief_file`, `task_name`, ... | SDD task implementer subagent prompt template. |
+| **`sdd-task-reviewer`** | `brief_file`, `report_file`, `review_file`, ... | SDD per-task spec & quality reviewer prompt template. |
+| **`sdd-re-review`** | `brief_file`, `review_file`, `previous_findings`, ... | SDD fix-round scoped re-reviewer prompt template. |
+| **`spec-reviewer`** | `spec_file` | Adversarial design specification reviewer prompt template. |
+| **`plan-reviewer`** | `plan_file`, `spec_file` | Adversarial implementation plan reviewer prompt template. |
+
+---
+
+## 7. Practical Usage Guide
+
+With `superpowers-mcp` installed, start from a native MCP prompt and let its instructions load the required skills.
+
+### Method A: MCP Prompts Menu (Recommended)
+In a client that supports MCP prompts:
+1. Confirm that the configured `superpowers` MCP server is connected.
+2. **New Feature Development**: Select `feature-pipeline` and provide `feature_name` plus optional `requirements`.
+3. **Troubleshooting & Bugfixes**: Select `structured-debug` and paste the error logs or failing test names.
+4. **Custom / Architecture Tasks**: Select `skill-composition` to let the AI recommend the best pipeline for your scenario.
+
+Your client may also expose a namespaced slash command. Consult its prompt picker for the exact syntax rather than assuming `/feature-pipeline` is portable.
+
+### Method B: Natural-Language Fallback
+You may ask the agent to follow a named workflow, but this does not guarantee that the client retrieves the native MCP prompt. For deterministic use, select it from the MCP Prompts menu.
+- *"Please follow the `feature-pipeline` to build [Feature Name]."*
+- *"Run the `structured-debug` workflow on this error: [Paste error / trace]."*
+- *"Apply the Refactoring Pipeline from `docs/skill-compositions.md` to refactor [Module]."*
+
+### 💬 Interactive Step-by-Step Walkthrough Example:
+```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!"
+```

package/docs/skill-compositions.zh-TW.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 語法依客戶端而異。Agent 必須能存取檔案、終端機與 Git，並透過 `read_skill` 載入各階段技能。流程會在設計核准、計畫審閱及分支收尾時等待使用者決定。完整指南也可透過 `guide://superpowers/skill-compositions` 讀取。
+
+> **單一來源（Source of Truth）：** 本英文文件為正式版本。技能行為變更時請先更新英文版，再同步翻譯。
+
+## 1. 為什麼需要技能組合 (Why Skill Compositions Matter)
+
+`superpowers-mcp` 的 14 個核心技能涵蓋了現代軟體工程生命週期（SDLC）的各個階段：從需求澄清、架構規劃、隔離實作、TDD 開發、系統化除錯，到全套驗證、代碼審查與分支整合。
+
+單一技能如同「高精度的專業工具」，但真實開發需要「工作流編排（Orchestration）」。透過技能組合（Skill Composition），能將鬆散的 AI 操作轉化為嚴謹、可重複驗證、防護嚴密的工程流水線。
+
+---
+
+## 2. 核心架構守則 (Core Architectural Principles)
+
+在編排技能時，必須恪守以下五大防護機制：
+
+1. **物理隔離優先 (Isolation First via Git Worktrees)**：凡涉及多 Agent 協作或平行除錯，必須強制使用 `superpowers:using-git-worktrees` 建立獨立目錄，防止檔案衝突 (Race Condition) 與環境污染。
+2. **測試驅動開發 (TDD by Default)**：程式碼變更前必須先有失敗測試（Red-Green-Refactor），確保迴歸安全。
+3. **雙層審查閘門 (Dual-layer Review)**：Task 級別的規格合規檢查與 Feature 級別的全面分支審查（`requesting-code-review` / `receiving-code-review`）不可省略。
+4. **全套驗證後方可完結 (Verification Before Completion)**：在交付分支或聲明完成前，必須執行全專案測試套件（`verification-before-completion`）。
+5. **遠端安全邊界（Local Commits Only）**：Commit 一律保持本地，未經計畫或人類夥伴指示不得 push/pull/fetch；從共享 ref 開分支時必須 `--no-track`（或於首次 commit 前 `--unset-upstream`），確保功能分支不追蹤共享分支；且嚴禁改寫共享分支（只能以 `git revert` 前向修正）。
+
+---
+
+## 3. 四大標準工作流流水線 (Four Standard Workflow Pipelines)
+
+### Pipeline 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` | 將 Spec 轉化為可獨立驗證的原子任務清單，標註 Recommended Skill。 |
+| **3. 環境隔離** | `using-git-worktrees` | 建立獨立的 Git Worktree 工作區，保護主分支與日常工作。 |
+| **4. 任務執行** | `subagent-driven-development` | 派發獨立 Subagent 依序執行任務，嚴守上下文乾淨原則。 |
+| **5. 邏輯實作** | `test-driven-development` | 針對各任務邏輯，嚴格執行 Red ➔ Green ➔ Refactor 流程。 |
+| **6. 全套驗證** | `verification-before-completion` | 執行專案完整測試套件、Linter、型別檢查，確認無迴歸問題；若無測試指令，則須重新開啟成品並逐項核對需求。 |
+| **7. 程式碼審查** | `requesting-code-review` | 產生 Review Package，發起多維度架構與程式碼品質審查。 |
+| **8. 分支收尾** | `finishing-a-development-branch` | 先匯出延後發現（PR 清單或提交 follow-ups 檔），再合併/PR、清理 Worktree、刪除暫存分支。 |
+
+---
+
+### Pipeline 2: 結構化多點除錯 (Structured Troubleshooting Pipeline)
+**適用於：** 處理多個測試失敗、難以重現的 Bug 或生產環境 Incident。
+
+```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`**：為平行調查的子問題建立隔離 Worktrees，避免測試環境與檔案讀寫干擾。
+3. **`dispatching-parallel-agents`**：平行分派 Agent 驗證各假說與修復方案。
+4. **`test-driven-development`**：為確認的 Bug 編寫重現測試（Reproduction Test），接著進行修復。
+5. **`verification-before-completion`**：驗證全部測試通過，確保修復未破壞其他功能。
+6. **`requesting-code-review`**（與 `receiving-code-review`）：審查 Bugfix 差異與防護測試完整性，並徹底解決所有審查發現。
+7. **`finishing-a-development-branch`**：完成分支合併/PR，安全刪除暫存 Worktree 與過期分支。
+
+---
+
+### Pipeline 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`**：分階段重構，每一階段均有獨立 Task Review 確保架構未走偏。
+5. **`verification-before-completion`** + **`requesting-code-review`**：全面迴歸測試與專家架構審查。
+6. **`finishing-a-development-branch`**：合併遷移分支，清理 Worktrees，乾淨收尾。
+
+---
+
+### Pipeline 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`**：辨識系統關鍵路徑（Critical Path）與高風險模組。
+2. **`writing-plans`**：制定防護測試（Characterization Tests）補充計畫。
+3. **`test-driven-development`**：以 TDD 特徵化守門（變異→確認失敗→VCS 還原→維持綠燈）為既有行為編寫金絲雀與規格測試。
+4. **`systematic-debugging`**：針對補測試過程中發現的潛在隱患進行根因排查。
+5. **`verification-before-completion`**：建立 CI/CD 測試防線。
+
+---
+
+## 4. 計畫驅動的技能編排規格 (Plan-Driven Skill Metadata Schema)
+
+在 `writing-plans` 產生的 Implementation Plan 中，可針對各任務指定建議使用的 Skill：
+
+```markdown
+### Task 1: 實作 Token 驗證中介軟體 (Token Middleware)
+- **Goal**: 驗證 JWT Token 並解析 Claims
+- **Target Files**: `src/auth/jwt.ts`, `tests/auth/jwt.test.ts`
+- **Recommended Skill**: `superpowers:test-driven-development`
+- **Task Brief**:
+  1. 編寫 JWT 簽名與過期驗證測試 (FAIL)
+  2. 實作驗證邏輯使測試通過 (PASS)
+  3. 重構並確保型別安全
+```
+
+### 主 Agent 與 Subagent 調度協議
+當主 Agent 根據 Plan 派發 Subagent 時：
+1. 主 Agent 讀取 Task 中的 `Recommended Skill`。
+2. 主 Agent 透過 `read_skill(skill_name)` 獲取該技能內容，或在 Prompt 中指示 Subagent 自行讀取。
+3. Subagent 嚴格按照該技能的工作守則（例如 TDD 的紅綠重構環節）執行任務。
+
+---
+
+## 5. MCP Prompts 跨平台支援
+
+為了讓 Cursor, Antigravity, VS Code, Devin Desktop 等客戶端能一鍵發起技能組合，`superpowers-mcp` 原生提供了標準 MCP 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 任務實作子代理 Prompt |
+| **`sdd-task-reviewer`** | `brief_file`, `report_file`, `review_file`, ... | SDD 單一任務審查子代理 Prompt |
+| **`sdd-re-review`** | `brief_file`, `review_file`, `previous_findings`, ... | SDD 修復輪次局部覆審子代理 Prompt |
+| **`spec-reviewer`** | `spec_file` | 對抗式設計規格審查子代理 Prompt |
+| **`plan-reviewer`** | `plan_file`, `spec_file` | 對抗式實作計畫審查子代理 Prompt |
+
+---
+
+## 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. **排查 Bug / 失敗測試**：選擇 `structured-debug`，貼上錯誤訊息或測試檔案。
+3. **不知道選什麼流程**：選擇 `skill-composition`，讓 AI 針對您的情境為您推薦專屬步驟。
+
+### 方式 B：直接用自然語言告訴 AI
+您也可以在一般對話中提出以下要求，但這不保證客戶端會取回原生 MCP prompt；需要確定行為時，請使用 MCP Prompts 選單：
+- *「請按照 `feature-pipeline` 的流程，幫我開發 [功能名稱]」*
+- *「請用 `structured-debug` 流程幫我分析並修復這個報錯：[貼上報錯訊息]」*
+- *「請按照 `docs/skill-compositions.zh-TW.md` 的 Refactoring Pipeline 幫我重構 [模組名稱]」*
+
+### 💬 實戰互動節奏示範（以開發新功能為例）：
+```text
+【您】:（從 MCP Prompts 選單選取 `feature-pipeline`，輸入「購物車折扣券功能」）
+  ↓
+【AI】:（透過 `read_skill` 載入 brainstorming）「好的，請問折扣券是否有使用期限？是否能與其他優惠疊加？」
+  ↓
+【您】:「有期限，不能與全館折扣疊加」
+  ↓
+【AI】:（設計核准後載入 writing-plans）「我已生成實作計畫 docs/superpowers/plans/...，請確認任務清單」
+  ↓
+【您】:「計畫沒問題，開始執行」
+  ↓
+【AI】:（建立或確認 worktree ➔ 使用 SDD 或行內 fallback ➔ TDD 實作 ➔ 驗證與審查 ➔ 提供分支收尾選項）
+  ↓
+【AI】: 「所有任務與全套測試皆已 100% 通過，Review 完成，分支已就緒！」
+```