superpowers-mcp 6.3.7 → 6.3.8

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

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!"
+```