superpowers-mcp 6.4.2 → 6.4.3

package/docs/skill-compositions.ja.md

@@ -1,12 +1,36 @@
 # Superpowers MCP: スキル構成 & ワークフローパイプライン (Skill Compositions & Workflow Pipelines)
 
-[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+[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)
 
 > **重要:** これらの MCP prompts は対話型ワークフローランチャーであり、サーバー側の自動化ではありません。クライアントの MCP Prompts メニューから選択してください。slash command の構文はクライアントごとに異なります。エージェントにはファイル、ターミナル、Git へのアクセスが必要で、各段階で `read_skill` を呼び出します。設計承認、計画レビュー、ブランチ完了時にはユーザーの判断を待ちます。完全なガイドは `guide://superpowers/skill-compositions` でも取得できます。
 
 > **正典（Source of Truth）：** 本英語版が原本です。スキルの振る舞いが変わったら英語版を先に更新し、翻訳を同期してください。
 
-## 1. スキル構成が重要な理由 (Why Skill Compositions Matter)
+## 1. ワークフローを選択する (Choose a Workflow)
+
+これらの prompt は**対話型ワークフローランチャー**であり、サーバー側の自動化ではありません。いずれかを選択すると構造化された指示が会話に追加されます。ホストエージェントはファイル、ターミナル、Git へのアクセスを持ち、各段階で `read_skill` を呼び出す必要があります。スキルが設計承認、計画レビュー、ブランチ完了の判断を求める場合、ワークフローはユーザーの決定を待ちます。
+
+| 目的 | MCP Prompt | 内容 |
+| :--- | :--- | :--- |
+| 新機能を開発する | `feature-pipeline` | 完全な対話型機能開発ワークフローを開始します。 |
+| 複雑なバグを調査・修正する | `structured-debug` | 構造化デバッグワークフローを開始します。 |
+| 大規模なリファクタリングや移行を計画する | リファクタリングシナリオ付き `skill-composition` | パイプライン 3 を推奨します。専用のランチャー prompt はまだありません。 |
+| レガシーコードベースを安定化させる | レガシーシナリオ付き `skill-composition` | パイプライン 4 を推奨します。専用のランチャー prompt はまだありません。 |
+
+移植性のある呼び出し方法はクライアントの **MCP Prompts メニュー**です。slash-command 名はクライアントごとに異なり、設定済み MCP サーバー名を含む場合があります。通常のチャットで prompt 名に触れただけでは、クライアントがその MCP prompt を取得する保証はありません。
+
+本ガイドは MCP クライアント向けに `guide://superpowers/skill-compositions` としても公開されています。
+
+### 前提条件 (Prerequisites)
+
+- 対象リポジトリ、ファイル、ターミナル、Git にアクセスできるエージェントセッションで実行してください。
+- worktree の作成には Git リポジトリと、ブランチおよびディレクトリを作成する権限が必要です。
+- `subagent-driven-development` にはホスト提供のマルチエージェントツールが必要です。利用できない場合、`feature-pipeline` はインラインの代替として `executing-plans` を使用します。
+- push、pull request、マージ、破壊的なクリーンアップは引き続きユーザーの明示的な判断事項です。
+
+---
+
+## 2. スキル構成が重要な理由 (Why Skill Compositions Matter)
 
 `superpowers-mcp` に含まれる 15 のコアスキルは、要件の明確化、アーキテクチャ設計、分離されたワークスペースの構築、テスト駆動開発 (TDD)、体系的なデバッグから、完全検証、コードレビュー、ブランチ統合に至るまで、ソフトウェア開発ライフサイクル (SDLC) 全体を網羅しています。
 
@@ -14,7 +38,7 @@
 
 ---
 
-## 2. コアアーキテクチャ原則 (Core Architectural Principles)
+## 3. コアアーキテクチャ原則 (Core Architectural Principles)
 
 スキルを組み合わせる際は、常に以下の 5 つの安全防御メカニズムを適用してください。
 
@@ -26,7 +50,7 @@
 
 ---
 
-## 3. 4つの標準スキル構成パイプライン (Four Standard Workflow Pipelines)
+## 4. 4つの標準スキル構成パイプライン (Four Standard Workflow Pipelines)
 
 ### パイプライン 1: エンドツーエンド新機能開発 (Feature Development Pipeline)
 **推奨用途：** 新機能のスクラッチ開発、主要モジュールの追加、コアプロセスのリファクタリング。
@@ -35,11 +59,10 @@
 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]
+    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]
 ```
 
 | ステップ | スキル (Skill) | 責務と成果物 |
@@ -47,11 +70,10 @@ flowchart LR
 | **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 の整理、一時ブランチの削除を実施。 |
+| **4. タスク実行** | `subagent-driven-development` または `executing-plans` | ホストが対応している場合は新しいサブエージェントを使用し、対応していない場合はインラインで実行。実装タスクでは `test-driven-development` を読み込み、Red ➔ Green ➔ Refactor を適用。 |
+| **5. フルテスト検証** | `verification-before-completion` | フルテストスイート、Linter、型チェックを実行し、回帰がないことを確認。テストコマンドが無い場合は成果物を再度開き、要求事項を漏れなく確認。 |
+| **6. コードレビュー** | `requesting-code-review` | レビューパッケージを生成し、多角的なコード＆アーキテクチャレビューを実施。 |
+| **7. ブランチ完了** | `finishing-a-development-branch` | 保留所見をエクスポート（PR チェックリストまたは follow-ups ファイル）してから、マージ/PR、Worktree の整理、一時ブランチの削除を実施。 |
 
 ---
 
@@ -123,7 +145,7 @@ flowchart LR
 
 ---
 
-## 4. スキル作成とメタデータ標準 (Skill Authoring & Metadata Standards)
+## 5. スキル作成とメタデータ標準 (Skill Authoring & Metadata Standards)
 
 `writing-plans` で作成する実装計画において、各タスクに推奨スキルを指定できます：
 
@@ -146,7 +168,7 @@ flowchart LR
 
 ---
 
-## 5. ネイティブ MCP Prompts 一覧
+## 6. ネイティブ MCP Prompts 一覧
 
 `superpowers-mcp` は主要な MCP クライアント（Cursor、Antigravity、VS Code、Devin Desktop など）で利用可能な標準 Prompts を提供します：
 
@@ -164,7 +186,7 @@ flowchart LR
 
 ---
 
-## 6. IDE での実際の操作方法 (How to Use in Practice)
+## 7. IDE での実際の操作方法 (How to Use in Practice)
 
 `superpowers-mcp` を設定すれば、**15 個の個別スキル名を覚える必要は一切ありません**。以下の 2 つの方法で簡単に利用できます：
 

package/docs/skill-compositions.ko.md

@@ -1,20 +1,44 @@
 # Superpowers MCP: 스킬 조합 및 워크플로우 파이프라인 (Skill Compositions & Workflow Pipelines)
 
-[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+[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)
 
 > **중요:** 이 MCP prompts는 대화형 워크플로 런처이며 서버 측 자동화가 아닙니다. 클라이언트의 MCP Prompts 메뉴에서 선택하세요. slash command 문법은 클라이언트마다 다릅니다. 에이전트는 파일, 터미널, Git에 접근할 수 있어야 하며 각 단계에서 `read_skill`을 호출합니다. 설계 승인, 계획 검토, 브랜치 마무리 단계에서는 사용자 결정을 기다립니다. 전체 가이드는 `guide://superpowers/skill-compositions`에서도 읽을 수 있습니다.
 
 > **단일 소스(Source of Truth):** 이 영어 문서가 정본입니다. 스킬 동작이 바뀌면 영어 문서를 먼저 갱신하고 번역을 동기화하세요.
 
-## 1. 스킬 조합이 중요한 이유 (Why Skill Compositions Matter)
+## 1. 워크플로 선택하기 (Choose a Workflow)
+
+이 prompt들은 **대화형 워크플로 런처**이며 서버 측 자동화가 아닙니다. 하나를 선택하면 구조화된 지침이 대화에 추가됩니다. 호스트 에이전트는 파일, 터미널, Git에 접근할 수 있어야 하며 각 단계에서 `read_skill`을 호출해야 합니다. 스킬이 설계 승인, 계획 검토 또는 브랜치 마무리 결정을 요구하면 워크플로가 사용자 결정을 기다립니다.
+
+| 목표 | MCP Prompt | 내용 |
+| :--- | :--- | :--- |
+| 새 기능 개발 | `feature-pipeline` | 완전한 대화형 기능 개발 워크플로를 시작합니다. |
+| 복잡한 버그 조사 및 수정 | `structured-debug` | 구조화된 디버깅 워크플로를 시작합니다. |
+| 대규모 리팩토링 또는 마이그레이션 계획 | 리팩토링 시나리오와 함께 `skill-composition` | 파이프라인 3을 권장합니다. 전용 런처 prompt는 아직 없습니다. |
+| 레거시 코드베이스 안정화 | 레거시 시나리오와 함께 `skill-composition` | 파이프라인 4를 권장합니다. 전용 런처 prompt는 아직 없습니다. |
+
+이식성 있는 호출 방법은 클라이언트의 **MCP Prompts 메뉴**입니다. slash-command 이름은 클라이언트마다 다르며 구성된 MCP 서버 이름을 포함할 수 있습니다. 일반 채팅에서 prompt 이름을 언급하는 것만으로는 클라이언트가 해당 MCP prompt를 가져온다는 보장이 없습니다.
+
+본 가이드는 MCP 클라이언트에 `guide://superpowers/skill-compositions`로도 노출됩니다.
+
+### 사전 요구사항 (Prerequisites)
+
+- 대상 저장소, 파일, 터미널, Git에 접근할 수 있는 에이전트 세션에서 실행하세요.
+- worktree 생성에는 Git 저장소와 브랜치 및 디렉터리 생성 권한이 필요합니다.
+- `subagent-driven-development`에는 호스트가 제공하는 멀티에이전트 도구가 필요합니다. 사용할 수 없으면 `feature-pipeline`이 인라인 대안으로 `executing-plans`를 사용합니다.
+- push, pull request, 병합, 파괴적인 정리는 계속 사용자의 명시적 결정 사항입니다.
+
+---
+
+## 2. 스킬 조합이 중요한 이유 (Why Skill Compositions Matter)
 
 `superpowers-mcp`의 15개 핵심 스킬은 요구사항 명확화, 아키텍처 설계, 격리된 작업 환경 구축, 테스트 주도 개발(TDD), 체계적 디버깅부터 전체 검증, 코드 리뷰, 브랜치 통합에 이르기까지 소프트웨어 개발 라이프사이클(SDLC) 전반을 다룹니다.
 
-각 스킬은 단독으로도 정밀한 엔지니어링 도구 역할을 하지만, 실제 프로덕션 개발에는 **워크플로우 오케스트레이션(편성)**이 필수적입니다. 스킬 조합(Skill Composition)을 통해 임의적인 AI 상호작용을 체계적이고 재현 가능하며 안전하게 보호되는 엔지니어링 파이프라인으로 전환합니다.
+각 스킬은 단독으로도 정밀한 엔지니어링 도구 역할을 하지만, 실제 프로덕션 개발에는 **워크플로우 오케스트레이션(편성)** 이 필수적입니다. 스킬 조합(Skill Composition)을 통해 임의적인 AI 상호작용을 체계적이고 재현 가능하며 안전하게 보호되는 엔지니어링 파이프라인으로 전환합니다.
 
 ---
 
-## 2. 핵심 아키텍처 원칙 (Core Architectural Principles)
+## 3. 핵심 아키텍처 원칙 (Core Architectural Principles)
 
 스킬을 조합할 때는 항상 다음 5가지 안전 보호 메커니즘을 준수해야 합니다:
 
@@ -26,7 +50,7 @@
 
 ---
 
-## 3. 4대 표준 스킬 조합 파이프라인 (Four Standard Workflow Pipelines)
+## 4. 4대 표준 스킬 조합 파이프라인 (Four Standard Workflow Pipelines)
 
 ### 파이프라인 1: 엔드투엔드 새 기능 개발 (Feature Development Pipeline)
 **권장 시나리오:** 새 기능 초기 개발, 주요 모듈 추가, 핵심 프로세스 리팩토링.
@@ -35,11 +59,10 @@
 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]
+    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]
 ```
 
 | 단계 | 스킬 (Skill) | 역할 및 산출물 |
@@ -47,11 +70,10 @@ flowchart LR
 | **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 정리, 임시 브랜치 삭제를 수행. |
+| **4. 태스크 실행** | `subagent-driven-development` 또는 `executing-plans` | 호스트가 지원하면 새 서브에이전트를 사용하고, 지원하지 않으면 인라인으로 실행. 구현 태스크에는 `test-driven-development`를 로드하고 Red ➔ Green ➔ Refactor를 적용. |
+| **5. 전체 검증** | `verification-before-completion` | 전체 테스트 스위트, Linter, 타입 검사를 실행하여 회귀가 없음을 확인. 테스트 명령이 없으면 산출물을 다시 열어 요청 사항을 빠짐없이 점검. |
+| **6. 코드 리뷰** | `requesting-code-review` | 리뷰 패키지를 생성하고 다각적인 코드 및 아키텍처 리뷰 수행. |
+| **7. 브랜치 마무리** | `finishing-a-development-branch` | 보류 발견을 내보낸 뒤(PR 체크리스트 또는 follow-ups 파일) 병합/PR, Worktree 정리, 임시 브랜치 삭제를 수행. |
 
 ---
 
@@ -119,11 +141,11 @@ flowchart LR
 
 ### 메타 스킬: 세션 포렌식 (Session Forensics)
 
-네 가지 파이프라인 밖에, **`diagnosing-superpowers`**는 디스크의 트랜스크립트에서 과거 세션의 문제 경위를 재구성합니다: 인테이크 인터뷰, 세션 탐색, 인용 증거가 있는 병렬 애널리스트 보고서, 그리고 선택적으로 스크럽된 번들이나 GitHub 이슈 초안. 세션이 계획을 무시했거나 작업을 반복했거나 설명할 수 없는 결과를 냈을 때 사용하고, 소견이 업스트림에 속하면 메인테이너 보고도 대신 작성합니다. MCP 서버는 스킬 내용 제공만 담당하며, 에이전트가 자체 도구로 호스트의 기록 파일을 읽기 때문에 트랜스크립트가 서버를 경유하지 않습니다.
+네 가지 파이프라인 밖에, **`diagnosing-superpowers`** 는 디스크의 트랜스크립트에서 과거 세션의 문제 경위를 재구성합니다: 인테이크 인터뷰, 세션 탐색, 인용 증거가 있는 병렬 애널리스트 보고서, 그리고 선택적으로 스크럽된 번들이나 GitHub 이슈 초안. 세션이 계획을 무시했거나 작업을 반복했거나 설명할 수 없는 결과를 냈을 때 사용하고, 소견이 업스트림에 속하면 메인테이너 보고도 대신 작성합니다. MCP 서버는 스킬 내용 제공만 담당하며, 에이전트가 자체 도구로 호스트의 기록 파일을 읽기 때문에 트랜스크립트가 서버를 경유하지 않습니다.
 
 ---
 
-## 4. 계획 기반 스킬 구성 스키마 (Plan-Driven Skill Metadata Schema)
+## 5. 계획 기반 스킬 구성 스키마 (Plan-Driven Skill Metadata Schema)
 
 `writing-plans`로 생성된 구현 계획에서 각 태스크별 권장 스킬을 지정할 수 있습니다:
 
@@ -146,7 +168,7 @@ flowchart LR
 
 ---
 
-## 5. 네이티브 MCP Prompts 레퍼런스
+## 6. 네이티브 MCP Prompts 레퍼런스
 
 `superpowers-mcp`는 주요 IDE(Cursor, Antigravity, VS Code, Devin Desktop 등)에서 즉시 사용할 수 있는 표준 Prompts를 제공합니다:
 
@@ -164,7 +186,7 @@ flowchart LR
 
 ---
 
-## 6. IDE에서 실제로 사용하는 방법 (How to Use in Practice)
+## 7. IDE에서 실제로 사용하는 방법 (How to Use in Practice)
 
 `superpowers-mcp`를 설정하면 **15개의 개별 스킬 이름을 일일이 기억할 필요가 없습니다**. 아래의 두 가지 간단한 방법으로 시작할 수 있습니다:
 

package/docs/skill-compositions.md

@@ -1,6 +1,6 @@
 # Superpowers MCP: Skill Compositions & Workflow Pipelines
 
-[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+[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)
 
 > **Source of truth:** this English document is canonical. Update it first when skill behavior changes, then sync the translations.
 

package/docs/skill-compositions.pt-BR.md

@@ -0,0 +1,220 @@
+# Superpowers MCP: Composição de Skills e Pipelines de Workflow
+
+[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)
+
+> **Fonte da verdade:** este documento em inglês é canônico. Atualize-o primeiro quando o comportamento das skills mudar e depois sincronize as traduções.
+
+
+## 1. Escolha um workflow
+
+Estes prompts são **lançadores interativos de workflow**, não automação no servidor. Selecionar um adiciona instruções estruturadas à conversa; o agente host precisa ter acesso a arquivos, terminal e Git, e precisa chamar `read_skill` em cada etapa. O workflow pausa sempre que uma skill exigir aprovação de design, revisão do plano ou uma decisão de finalização de branch.
+
+| Objetivo | MCP Prompt | O que faz |
+| :--- | :--- | :--- |
+| Construir uma feature nova | `feature-pipeline` | Inicia o workflow interativo completo de features. |
+| Investigar e corrigir um bug complexo | `structured-debug` | Inicia o workflow estruturado de debugging. |
+| Planejar um grande refactor ou migração | `skill-composition` com cenário de refactor | Recomenda o Pipeline 3; ainda não há prompt lançador dedicado. |
+| Estabilizar um codebase legado | `skill-composition` com cenário legado | Recomenda o Pipeline 4; ainda não há prompt lançador dedicado. |
+
+O método portátil de invocação é o **menu de MCP Prompts** do seu cliente. Nomes de slash-command variam por cliente e podem incluir o nome do servidor MCP configurado. Apenas mencionar um prompt pelo nome no chat comum não garante que o cliente recupere aquele MCP prompt.
+
+O mesmo guia é exposto aos clientes MCP como `guide://superpowers/skill-compositions`.
+
+### Pré-requisitos
+
+- Execute em uma sessão de agente com acesso ao repositório alvo, arquivos, terminal e Git.
+- Criar worktrees exige um repositório Git e permissão para criar branches e diretórios.
+- `subagent-driven-development` exige ferramentas multiagente do host. Quando indisponíveis, `feature-pipeline` usa `executing-plans` como fallback inline.
+- Pushes, pull requests, merges e limpezas destrutivas continuam sendo decisões explícitas do usuário.
+
+## 2. Por que composições de skills importam
+
+As 15 skills principais do `superpowers-mcp` cobrem todo o ciclo de vida do software (SDLC): da descoberta de requisitos, planejamento de arquitetura, setup de workspaces isolados, desenvolvimento guiado por testes (TDD) e debugging sistemático, até verificação completa, code review e integração de branches.
+
+Enquanto cada skill atômica funciona como uma ferramenta de engenharia de precisão, o desenvolvimento em nível de produção exige **orquestração de workflows**. As composições transformam interações ad-hoc com IA em pipelines disciplinados, reproduzíveis e com travas de segurança.
+
+---
+
+## 3. Princípios arquiteturais fundamentais
+
+Ao compor skills, aplique sempre estes cinco mecanismos de segurança:
+
+1. **Isolamento primeiro (via Git Worktrees)**: Sempre que coordenar múltiplos subagentes ou debugar hipóteses independentes em paralelo, use `superpowers:using-git-worktrees` para evitar race conditions e poluição do workspace.
+2. **TDD por padrão**: Nenhuma modificação de código sem um teste falhando antes (ciclo Vermelho-Verde-Refatoração) para garantir segurança contra regressões.
+3. **Gates de revisão em duas camadas**: Nunca pule checagens de conformidade com a spec por tarefa nem revisões de branch por feature (`requesting-code-review` / `receiving-code-review`).
+4. **Verificação completa antes de concluir**: Rode toda a suíte de testes, o checador de tipos e o linter (`verification-before-completion`) antes de declarar pronto ou fazer merge de branches.
+5. **Fronteira de segurança remota (só commits locais)**: Mantenha os commits locais — sem push/pull/fetch a menos que o plano ou seu parceiro humano diga. Crie o branch a partir de uma ref compartilhada com `--no-track` (ou `--unset-upstream` antes do primeiro commit) para que o branch de feature nunca rastreie um branch compartilhado, e nunca reescreva um branch compartilhado (`git revert` é o único remédio que você aplica sozinho).
+
+---
+
+## 4. Quatro pipelines padrão de workflow
+
+### Pipeline 1: Desenvolvimento de features de ponta a ponta
+**Ideal para:** Construir features novas, módulos grandes ou melhorias em subsistemas centrais.
+
+```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]
+```
+
+| Etapa | Skill | Responsabilidade e entregável |
+| :--- | :--- | :--- |
+| **1. Requisitos e design** | `brainstorming` | Esclarece intenção, restrições, decisões de arquitetura e edge cases; confirma entendimento compartilhado, executa a revisão de handoff de planejamento e produz a Spec de design. |
+| **2. Construção do plano** | `writing-plans` | Decompõe a Spec em tarefas pequenas e testáveis com Recommended Skills. |
+| **3. Isolamento do workspace** | `using-git-worktrees` | Cria um worktree Git isolado para proteger o branch principal e o trabalho ativo. |
+| **4. Execução das tarefas** | `subagent-driven-development` ou `executing-plans` | Usa subagentes novos quando o host suporta; senão, executa inline. Carrega `test-driven-development` para tarefas de implementação e aplica Vermelho ➔ Verde ➔ Refatoração. |
+| **5. Verificação completa** | `verification-before-completion` | Executa toda a suíte de testes, linter e checagens de tipos para zero regressões; quando não há comando de testes, reabre o artefato e presta contas de cada parte do pedido. |
+| **6. Revisão adversarial** | `requesting-code-review` | Monta o pacote de revisão e faz revisões abrangentes de código e arquitetura. |
+| **7. Finalização do branch** | `finishing-a-development-branch` | Exporta achados diferidos (checklist de PR ou arquivo de follow-ups), apresenta as opções de merge/PR/manter e executa só a opção escolhida. |
+
+---
+
+### Pipeline 2: Troubleshooting estruturado e debugging multifalha
+**Ideal para:** Bugs complexos, testes instáveis, múltiplas falhas ou incidentes em produção.
+
+```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 raiz e quebra as falhas em hipóteses distintas e testáveis.
+2. **`using-git-worktrees`**: Prepara worktrees isolados para investigações paralelas e evita interferência entre testes.
+3. **`dispatching-parallel-agents`**: Despacha subagentes concorrentes para validar ou invalidar cada hipótese.
+4. **`test-driven-development`**: Escreve testes mínimos de reprodução que falham antes de aplicar correções pontuais.
+5. **`verification-before-completion`**: Valida que todos os testes do repositório passam com saídas limpas.
+6. **`requesting-code-review`** (e `receiving-code-review`): Revisa o delta da correção, garante cobertura defensiva de regressão e resolve os achados.
+7. **`finishing-a-development-branch`**: Faz merge do branch do bugfix, remove worktrees temporários e limpa o workspace.
+
+---
+
+### Pipeline 3: Refatoração grande e migração de sistemas
+**Ideal para:** Refactors arquiteturais, migrações de framework ou desacoplamento de serviços.
+
+```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 interface, estratégias de transição e critérios de paridade.
+2. **`writing-plans` (modo Skeleton-First)**: Desenha primeiro a fatia end-to-end mais fina entre todos os subsistemas.
+3. **`using-git-worktrees`**: Estabelece worktrees de migração dedicados e duradouros.
+4. **`subagent-driven-development`**: Executa tarefas de refatoração por fases com gates de revisão obrigatórios por tarefa.
+5. **`verification-before-completion`** + **`requesting-code-review`**: Verificação total de regressão e revisão arquitetural.
+6. **`finishing-a-development-branch`**: Faz merge do branch de migração, limpa worktrees e finaliza a entrega.
+
+---
+
+### Pipeline 4: Rede de segurança para código legado
+**Ideal para:** Códigos legados sem cobertura automatizada nem padrões 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 caminhos críticos de negócio e módulos de alto risco.
+2. **`writing-plans`**: Cria o roteiro para adicionar testes de caracterização e de borda.
+3. **`test-driven-development`**: Cria testes golden-master e de regressão contra comportamentos existentes com a guarda de caracterização TDD (mutar, verificar falha, restaurar via VCS, stay green).
+4. **`systematic-debugging`**: Encontra defeitos ocultos que emergem ao estabelecer baselines.
+5. **`verification-before-completion`**: Consolida barreiras de CI automatizadas.
+
+### Meta skill: Forense de sessões
+
+Fora dos quatro pipelines, **`diagnosing-superpowers`** reconstrói o que deu errado numa sessão passada a partir de suas transcrições em disco: entrevista inicial, descoberta da sessão, relatórios paralelos com evidências citadas e depois um pacote anonimizado opcional ou rascunho de GitHub issue. Use quando uma sessão ignorou o plano, repetiu trabalho ou produziu um resultado inexplicável — e quando o achado pertence ao upstream, ele também redige o relatório para os mantenedores. O servidor MCP só serve o conteúdo da skill; o agente lê os arquivos de transcrição do host com suas próprias ferramentas, então nenhuma transcrição cruza a fronteira do servidor.
+
+---
+
+## 5. Esquema de metadados de skills em planos
+
+Em planos gerados por `writing-plans`, especifique as skills recomendadas por tarefa:
+
+```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
+Quando o agente controlador despacha um subagente de tarefa:
+1. O controlador lê o `Recommended Skill` indicado na tarefa do plano.
+2. O controlador injeta instruções ou orienta o subagente a carregar aquela skill via `read_skill(skill_name)`.
+3. O subagente executa sob a metodologia estrita daquela skill (ex. Vermelho-Verde-Refatoração).
+
+---
+
+## 6. Referência de MCP Prompts nativos
+
+`superpowers-mcp` oferece MCP prompts nativos prontos para usar em IDEs (Cursor, Antigravity, VS Code, Devin Desktop):
+
+| MCP Prompt | Argumentos | Propósito |
+| :--- | :--- | :--- |
+| **`feature-pipeline`** | `feature_name` obrigatório, `requirements` opcional | Lançador interativo de desenvolvimento de features end-to-end. |
+| **`structured-debug`** | `issue_description`, `failing_tests` | Lançador interativo de debugging sistemático e investigação multiagente opcional. |
+| **`skill-composition`** | `scenario` | Recomendador dinâmico de composição para tarefas de feature, debug, refactor ou legado. |
+| **`session-start`** | - | Injeta o contexto fundacional do Superpowers e regras de invocação. |
+| **`sdd-implementer`** | `brief_file`, `task_name`, ... | Template de prompt de subagente implementador de tarefas SDD. |
+| **`sdd-task-reviewer`** | `brief_file`, `report_file`, `review_file`, ... | Template de prompt revisor de spec e qualidade por tarefa SDD. |
+| **`sdd-re-review`** | `brief_file`, `review_file`, `previous_findings`, ... | Template de re-revisor SDD de escopo da rodada de correção. |
+| **`spec-reviewer`** | `spec_file` | Template de prompt revisor adversarial de specs de design. |
+| **`plan-reviewer`** | `plan_file`, `spec_file` | Template de prompt revisor adversarial de planos de implementação. |
+
+---
+
+## 7. Guia prático de uso
+
+Com o `superpowers-mcp` instalado, parta de um MCP prompt nativo e deixe que suas instruções carreguem as skills necessárias.
+
+### Método A: Menu de MCP Prompts (recomendado)
+Num cliente com suporte a MCP prompts:
+1. Confirme que o servidor MCP `superpowers` configurado está conectado.
+2. **Nova feature**: Selecione `feature-pipeline` e informe `feature_name` mais `requirements` opcional.
+3. **Resolução e bugfixes**: Selecione `structured-debug` e cole os logs de erro ou nomes de testes que falham.
+4. **Tarefas personalizadas / arquitetura**: Selecione `skill-composition` para que a IA recomende o melhor pipeline para seu cenário.
+
+Seu cliente também pode expor um slash command com namespace. Consulte seu seletor de prompts para a sintaxe exata em vez de assumir que `/feature-pipeline` é portátil.
+
+### Método B: Alternativa em linguagem natural
+Você pode pedir ao agente que siga um workflow nomeado, mas isso não garante que o cliente recupere o MCP prompt nativo. Para uso determinístico, selecione-o no menu de MCP Prompts.
+- *"Siga o `feature-pipeline` para construir [Nome da feature]."*
+- *"Execute o fluxo `structured-debug` sobre este erro: [Cole erro / trace]."*
+- *"Aplique o Pipeline de refatoração de `docs/skill-compositions.pt-BR.md` para refatorar [Módulo]."*
+
+### 💬 Exemplo interativo passo a passo:
+```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

@@ -1,12 +1,36 @@
 # Superpowers MCP：技能編排與工作流流水線指南 (Skill Compositions & Workflow Pipelines)
 
-[English](skill-compositions.md) | [繁體中文](skill-compositions.zh-TW.md) | [日本語](skill-compositions.ja.md) | [한국어](skill-compositions.ko.md)
+[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)
 
-> **重要：**這些 MCP prompts 是互動式工作流啟動器，不是伺服器端自動化。請從客戶端的 MCP Prompts 選單選取；slash command 語法依客戶端而異。Agent 必須能存取檔案、終端機與 Git，並透過 `read_skill` 載入各階段技能。流程會在設計核准、計畫審閱及分支收尾時等待使用者決定。完整指南也可透過 `guide://superpowers/skill-compositions` 讀取。
+> **重要**：這些 MCP prompts 是互動式工作流啟動器，不是伺服器端自動化。請從客戶端的 MCP Prompts 選單選取；slash command 語法依客戶端而異。Agent 必須能存取檔案、終端機與 Git，並透過 `read_skill` 載入各階段技能。流程會在設計核准、計畫審閱及分支收尾時等待使用者決定。完整指南也可透過 `guide://superpowers/skill-compositions` 讀取。
 
 > **單一來源（Source of Truth）：** 本英文文件為正式版本。技能行為變更時請先更新英文版，再同步翻譯。
 
-## 1. 為什麼需要技能組合 (Why Skill Compositions Matter)
+## 1. 選擇工作流 (Choose a Workflow)
+
+這些 prompts 是**互動式工作流啟動器**，而非伺服器端自動化。選取其一會將結構化指令加入對話；host agent 必須具備檔案、終端機與 Git 存取權，並在每個階段呼叫 `read_skill`。當技能需要設計核准、計畫審閱或分支收尾決策時，流程會暫停等待使用者決定。
+
+| 目標 | MCP Prompt | 功能 |
+| :--- | :--- | :--- |
+| 開發新功能 | `feature-pipeline` | 啟動完整的互動式功能開發流程。 |
+| 調查並修復複雜 Bug | `structured-debug` | 啟動結構化除錯流程。 |
+| 規劃大型重構或遷移 | 搭配重構情境的 `skill-composition` | 推薦 Pipeline 3；目前尚無專屬啟動 prompt。 |
+| 穩定舊程式碼庫 | 搭配舊系統情境的 `skill-composition` | 推薦 Pipeline 4；目前尚無專屬啟動 prompt。 |
+
+跨客戶端通用的呼叫方式是客戶端的 **MCP Prompts 選單**。Slash-command 名稱依客戶端而異，也可能包含已設定的 MCP 伺服器名稱。僅在一般對話中提及 prompt 名稱，並不保證客戶端會取回該 MCP prompt。
+
+本指南亦以 `guide://superpowers/skill-compositions` 暴露給 MCP 客戶端。
+
+### 前置需求 (Prerequisites)
+
+- 在可存取目標儲存庫、檔案、終端機與 Git 的 agent 會話中執行。
+- 建立 worktree 需要 Git 儲存庫，以及建立分支與目錄的權限。
+- `subagent-driven-development` 需要 host 提供的多 agent 工具。若無可用，`feature-pipeline` 會以 `executing-plans` 作為 inline 替代。
+- Push、pull request、merge 與破壞性清理仍屬使用者明確決策。
+
+---
+
+## 2. 為什麼需要技能組合 (Why Skill Compositions Matter)
 
 `superpowers-mcp` 的 15 個核心技能涵蓋了現代軟體工程生命週期（SDLC）的各個階段：從需求澄清、架構規劃、隔離實作、TDD 開發、系統化除錯，到全套驗證、代碼審查與分支整合。
 
@@ -14,7 +38,7 @@
 
 ---
 
-## 2. 核心架構守則 (Core Architectural Principles)
+## 3. 核心架構守則 (Core Architectural Principles)
 
 在編排技能時，必須恪守以下五大防護機制：
 
@@ -26,7 +50,7 @@
 
 ---
 
-## 3. 四大標準工作流流水線 (Four Standard Workflow Pipelines)
+## 4. 四大標準工作流流水線 (Four Standard Workflow Pipelines)
 
 ### Pipeline 1: 端到端新功能開發 (Feature Development Pipeline)
 **適用於：** 從零開發新功能、新增模組或重構核心流程。
@@ -35,11 +59,10 @@
 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]
+    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]
 ```
 
 | 步驟 | 技能 (Skill) | 職責與產出 |
@@ -47,11 +70,10 @@ flowchart LR
 | **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、刪除暫存分支。 |
+| **4. 任務執行** | `subagent-driven-development` 或 `executing-plans` | host 支援時使用全新 Subagent，否則採 inline 執行；實作任務載入 `test-driven-development` 並執行 Red ➔ Green ➔ Refactor。 |
+| **5. 全套驗證** | `verification-before-completion` | 執行專案完整測試套件、Linter、型別檢查，確認無迴歸問題；若無測試指令，則須重新開啟成品並逐項核對需求。 |
+| **6. 程式碼審查** | `requesting-code-review` | 產生 Review Package，發起多維度架構與程式碼品質審查。 |
+| **7. 分支收尾** | `finishing-a-development-branch` | 先匯出延後發現（PR 清單或提交 follow-ups 檔），再合併/PR、清理 Worktree、刪除暫存分支。 |
 
 ---
 
@@ -123,7 +145,7 @@ flowchart LR
 
 ---
 
-## 4. 計畫驅動的技能編排規格 (Plan-Driven Skill Metadata Schema)
+## 5. 計畫驅動的技能編排規格 (Plan-Driven Skill Metadata Schema)
 
 在 `writing-plans` 產生的 Implementation Plan 中，可針對各任務指定建議使用的 Skill：
 
@@ -146,7 +168,7 @@ flowchart LR
 
 ---
 
-## 5. MCP Prompts 跨平台支援
+## 6. MCP Prompts 跨平台支援
 
 為了讓 Cursor, Antigravity, VS Code, Devin Desktop 等客戶端能一鍵發起技能組合，`superpowers-mcp` 原生提供了標準 MCP Prompts：
 
@@ -164,7 +186,7 @@ flowchart LR
 
 ---
 
-## 6. 如何在 IDE 中實際操作與觸發 (How to Use in Practice)
+## 7. 如何在 IDE 中實際操作與觸發 (How to Use in Practice)
 
 只要安裝了 `superpowers-mcp`，您**完全不需要手動記住 15 個技能名稱**。有以下兩種最簡單的使用方式：