superpowers-mcp 6.3.7 → 6.3.9

package/docs/desktop-setup.md

@@ -0,0 +1,86 @@
+# Desktop quick setup / 桌面版快速安裝
+
+The new `lmstudio`, `roo` and `--print-config` options are unreleased. Until the next npm release, run from a checkout:
+
+```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
+```
+
+目前新增選項尚未發布至 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`.
+
+```json
+{
+  "mcpServers": {
+    "superpowers": {
+      "command": "npx",
+      "args": ["-y", "superpowers-mcp"]
+    }
+  }
+}
+```
+
+### ChatWise
+
+[Add Superpowers to ChatWise / 一鍵加入 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.

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% 통과했습니다. 리뷰 완료 및 브랜치가 준비되었습니다!"
+```