hve-core-installer

HVE-Core インストーラースキル

環境検出、クローンベースの6種類のインストール方法、拡張機能のクイックインストール、検証、MCP の設定、コンポーネントを選択してインストールするワークフローを備えた、判断に基づくインストーラーです。

役割の定義

次の2つのペルソナが連携して動作します。

• インストーラーペルソナは、環境を検出し、インストール方法の選択を案内し、インストール手順を実行します
• バリデーターペルソナは、パス、設定、エージェントへのアクセス可否を確認して、インストールの成功を検証します

インストーラーペルソナがすべての検出と実行を担当します。インストールの完了後、成功を確認してから完了を報告するため、バリデーターペルソナに切り替えます。

再実行時の動作： インストーラーを再実行すると、既存のインストールを検証するか、アップグレードを提案します。いつでも安全に再実行できます。

必須フェーズ

フェーズ	名前	目的
1	環境の検出	ユーザーの同意を得て、環境を検出します
2	インストールパスの選択	拡張機能（クイック）とクローンベースのインストールから選択します
3	環境の検出と判断マトリックス	クローンパスの場合：環境を検出し、方法を推奨します
4	インストール方法	選択したインストール方法を実行します
5	検証	インストールの成功を確認し、設定を構成します
6	インストール後のセットアップ	gitignore を設定し、MCP に関するガイダンスを提示します
7	コンポーネントのインストール	オプション：選択したコンポーネントをローカルで使用するためにコピーします（クローンベースのみ）

フローパス：

• 拡張機能パス：フェーズ1 → フェーズ2 → フェーズ6 → 完了
• クローンベースのパス：フェーズ1 → フェーズ2 → フェーズ3 → フェーズ4 → フェーズ5 → フェーズ6 → フェーズ7 → 完了

フェーズ1：環境の検出

選択肢を提示する前に、ユーザーの環境を検出し、適用可能なインストール方法に絞り込みます。

チェックポイント1：最初の同意

次の内容を提示し、明示的な同意を待ちます。

🚀 HVE-Core Installer

I'll help you install HVE-Core agents, instructions and skills.

Available content:
• Specialized agents, including RPI Agent, Documentation, and domain planners
• Technology-specific coding instructions (bash, python, markdown, etc.)
• Domain-specific skills (pr-reference, etc.)

I'll ask 2-3 questions to recommend the best installation method for your setup.

Would you like to proceed?

ユーザーが同意しない場合は、次のように応答します。「インストールをキャンセルしました。このスキルはいつでも呼び出して再開できます。」

同意を得たら、フェーズ2に進み、インストールパスの選択肢を提示します。

フェーズ2：インストールパスの選択

環境を検出する前に、インストールパスの選択肢を提示します。拡張機能のインストールでは、シェルの選択や環境の検出は不要です。

チェックポイント2：インストールパスの選択

次の選択肢を提示します。

🚀 Choose Your Installation Path

**Option 1: Quick Install (Recommended)**
Install the HVE Core extension from VS Code Marketplace.
• ⏱️ Takes about 10 seconds
• 🔄 Automatic updates
• ✅ No configuration needed

**Option 2: Clone-Based Installation**
Clone HVE-Core repository for customization.
• 🎨 Full customization support
• 📁 Files visible in your workspace
• 🤝 Team version control options

Which would you prefer? (1/2 or quick/clone)

ユーザー入力の処理：

• 「1」、「quick」、「extension」、「marketplace」→ 拡張機能のインストールを実行
• 「2」、「clone」、「custom」、「team」→ フェーズ3（環境の検出）に進む
• 応答が不明確な場合 → 明確にするよう尋ねる

ユーザーがオプション1（クイックインストール）を選択した場合：

1. 拡張機能のインストールを実行します（以下の「拡張機能のインストール実行」を参照）
2. インストールの成功を検証します
3. 成功レポートを表示するか、代替オプションを提示します

ユーザーがオプション2（クローンベース）を選択した場合：

• 次のように尋ねます：「どのシェルを使用しますか？（powershell/bash）」
• シェルの検出ルール：
  • 「powershell」、「pwsh」、「ps1」、「ps」→ PowerShell
  • 「bash」、「sh」、「zsh」→ Bash
  • 応答が不明確な場合 → Windows では PowerShell、macOS/Linux では Bash
• 前提条件の確認に進み、次に環境検出スクリプトを実行して、フェーズ3のワークフローに進みます

拡張機能ではなくクローンを選ぶ場合：

• エージェント、指示、またはスキルをカスタマイズする必要がある
• チームでバージョン管理された HVE-Core が必要である
• オフラインまたはエアギャップ環境である

前提条件の確認

クローンベースのインストールを行う前に、git が利用可能であることを確認します。

• 実行：git --version
• 失敗した場合：「クローンベースのインストールには Git が必要です。git をインストールするか、Extension Quick Install を選択してください。」

ユーザーが Bash を選択した場合は、jq も利用可能であることを確認します。

• 実行：jq --version
• 失敗した場合：「Bash コンポーネントのスクリプトには jq が必要です。jq をインストールするか、PowerShell を選択してください。」

拡張機能のインストール実行

ユーザーが Quick Install を選択した場合は、まず使用している VS Code の種類を尋ねます。

Which VS Code variant are you using?

  [1] VS Code (stable)
  [2] VS Code Insiders

Your choice? (1/2)

ユーザー入力の処理：

• 「1」、「code」、「stable」→ code CLI を使用
• 「2」、「insiders」、「code-insiders」→ code-insiders CLI を使用
• 回答が不明確な場合 → 確認を求める

検証スクリプトで使用するため、ユーザーの選択を code_cli 変数に保存します。

進行状況メッセージを表示します：

📥 Installing HVE Core extension from marketplace...

Note: You may see a trust confirmation dialog if this is your first extension from this publisher.

VS Code CLI コマンドを実行します：

<code_cli> --install-extension ise-hve-essentials.hve-core

コマンドの実行後、拡張機能の検証に進みます。

拡張機能の検証

検出されたプラットフォームに応じて、適切な検証スクリプトを実行します（Windows = PowerShell、macOS/Linux = Bash）。ユーザーが先ほど選択した code_cli の値（code または code-insiders）を使用します。

PowerShell： code_cli 変数を設定した状態で、scripts/validate-extension.ps1 を実行します。

Bash： code_cli 変数を設定した状態で、scripts/validate-extension.sh を実行します。

拡張機能のインストール成功レポート

検証が成功したら、次の内容を表示します。

✅ Extension Installation Complete!

The HVE Core extension has been installed from the VS Code Marketplace.

📦 Extension: ise-hve-essentials.hve-core
📌 Version: [detected version]
🔗 Marketplace: https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core

🧪 Available Agents:
• rpi-agent, documentation, backlog-manager, and adr-creation
• code-review, security-planner, ux-ui-designer, and more!

🪝 Hooks (manual step): The Marketplace extension is declarative and does not
  write chat.hookFilesLocations. To enable the bundled telemetry hook, add its
  folder to that setting yourself, or use a clone-based or CLI plugin install
  that documents this configuration.

📋 Configuring optional settings...

拡張機能のインストール成功レポートを表示した後、gitignore と MCP 設定のオプションについて、Phase 6: Post-Installation Setup に進みます。

拡張機能エラーからの復旧

拡張機能のインストールに失敗した場合は、状況に応じたガイダンスを提示します。

エラーの状況	ユーザーへのメッセージ	復旧アクション
信頼ダイアログで拒否された	"Installation was cancelled. You may have declined the publisher trust prompt."	再試行するか、クローン方式に切り替えるよう提案
ネットワーク障害	"Unable to connect to VS Code Marketplace. Check your network connection."	再試行または CLI の代替手段を提案
組織のポリシーによるブロック	"Extension installation may be restricted by your organization's policies."	手動インストール用の CLI コマンドを提示
不明な失敗	"Extension installation failed unexpectedly."	フォールバックとしてクローンベースのインストールを提案

失敗後のフロー制御：

拡張機能のインストールに失敗し、ユーザーが問題を解決できない場合：

• 次のように尋ねます：「代わりにクローンベースのインストール方法を試しますか？（yes/no）」
• はいの場合：環境検出スクリプトと Phase 3 のワークフローに進みます
• いいえの場合：手動インストール手順を提示してセッションを終了します

環境検出スクリプト

ユーザーのシェルに応じて、適切な検出スクリプトを実行します。

PowerShell： scripts/detect-environment.ps1 を実行します

Bash： scripts/detect-environment.sh を実行します

Phase 3: 環境検出と判断マトリックス

検出された環境に基づき、推奨方法を決定するため、次の質問をします。

質問 1：環境の確認

検出結果に応じて選択肢を絞り込んで提示します。

### Question 1: What's your development environment?

Based on my detection, you appear to be in: [DETECTED_ENV_TYPE]

Please confirm or correct:

| Option | Description                               |
|--------|-------------------------------------------|
| **A**  | 💻 Local VS Code (no devcontainer)        |
| **B**  | 🐳 Local devcontainer (Docker Desktop)    |
| **C**  | ☁️ GitHub Codespaces only                 |
| **D**  | 🔄 Both local devcontainer AND Codespaces |

Which best describes your setup? (A/B/C/D)

質問 2：チームまたは個人

### Question 2: Team or solo development?

| Option   | Description                                                   |
|----------|---------------------------------------------------------------|
| **Solo** | Solo developer - no need for version control of HVE-Core      |
| **Team** | Multiple people - need reproducible, version-controlled setup |

Are you working solo or with a team? (solo/team)

質問 3：更新の設定

環境とチームに関する回答に一致する方法が複数ある場合にのみ、この質問をします。

### Question 3: Update preference?

| Option         | Description                                   |
|----------------|-----------------------------------------------|
| **Auto**       | Always get latest HVE-Core on rebuild/startup |
| **Controlled** | Pin to specific version, update explicitly    |

How would you like to receive updates? (auto/controlled)

判断マトリックス

このマトリックスを使用して、推奨方法を判断します。

環境	チーム	更新	推奨方法
任意（最も簡単）	任意	-	拡張機能のクイックインストール（すべての環境で動作）
ローカル（コンテナーなし）	個人	-	方法 1：ピアクローン
ローカル（コンテナーなし）	チーム	管理下	方法 6：サブモジュール
ローカルの devcontainer	個人	自動	方法 2：Git で無視
ローカルの devcontainer	チーム	管理下	方法 6：サブモジュール
Codespaces のみ	個人	自動	方法 4：Codespaces
Codespaces のみ	チーム	管理下	方法 6：サブモジュール
ローカルと Codespaces の両方	任意	任意	方法 5：マルチルートワークスペース
HVE-Core リポジトリ（Codespaces）	-	-	方法 4：Codespaces（設定済み）

方法の選択ロジック

回答を集めた後：

1. 回答を判断マトリックスに照合します
2. 根拠とともに推奨方法を提示します
3. ユーザーが別の方法を希望する場合は、代替案を提示します

## 📋 Your Recommended Setup

Based on your answers:
* **Environment**: [answer]
* **Team**: [answer]
* **Updates**: [answer]

### ✅ Recommended: Method [N] - [Name]

**Why this fits your needs:**
* [Benefit 1 matching their requirements]
* [Benefit 2 matching their requirements]
* [Benefit 3 matching their requirements]

Would you like to proceed with this method, or see alternatives?

フェーズ 4：インストール方法

サポートされている各インストール方法の手順は、references/installation-methods.md に最初から最後まで記載されています。上記の判断マトリックスで決定した方法を選択し、そちらの手順に従ってください。このファイルを利用できない場合は、選択した方法ではインストールを続行できないことをユーザーに警告し、手順を独自に考案せずに停止してください。

フェーズ 5：検証（Validator ペルソナ）

インストール完了後、Validator ペルソナに切り替えてインストールを検証します。

重要

検証に成功したら、フェーズ 6 に進んでインストール後のセットアップを行い、その後、フェーズ 7 に進んでオプションのコンポーネントをインストールします（クローンベースの方法のみ）。

チェックポイント 3：設定の承認

settings.json を変更する前に、次の内容を提示します。

⚙️ VS Code Settings Update

I will now update your VS Code settings to add HVE-Core paths.

Changes to be made:
• [List paths based on selected method]

⚠️ Authorization Required: Do you authorize these settings changes? (yes/no)

ユーザーが拒否した場合：「インストールをキャンセルしました。設定は変更されていません。」

検証ワークフロー

選択した方法に基づいて検証を実行します。実行前にベースパス変数を設定します。

方法	ベースパス
1	../hve-core
2	.hve-core
3, 4	/workspaces/hve-core
5	ワークスペースファイルを確認
6	lib/hve-core

PowerShell： method と basePath 変数を設定して、scripts/validate-installation.ps1 を実行します。

Bash： メソッド番号とベースパスを引数として、scripts/validate-installation.sh を実行します。

成功レポート

検証に成功したら、次を表示します。

✅ Core Installation Complete!

Method [N]: [Name] installed successfully.

📍 Location: [path based on method]
⚙️ Settings: [settings file or workspace file]
📖 Documentation: https://github.com/microsoft/hve-core/blob/main/docs/getting-started/methods/[method-doc].md

🧪 Available Agents:
• rpi-agent, documentation, backlog-manager, and adr-creation
• code-review, security-planner, ux-ui-designer, and more!

📋 Configuring optional settings...

成功レポートを表示した後、フェーズ 6 に進んでインストール後のセットアップを行います。

フェーズ 6：インストール後のセットアップ

references/post-installation-setup.md を読み、次に進む前に記載されているすべての手順を実行してください。このファイルを利用できない場合は、インストール後のセットアップを完了できないことをユーザーに警告し、手順を独自に考案せずに停止してください。

フェーズ 7：コンポーネントのインストールとアップグレード

references/component-installation.mdを読み、そこに定められたすべての確認ステップを含め、コンポーネントのインストールとアップグレードの手順に正確に従ってください。方法 3 と 5 では、競合の検出やコピーを行う前に、既存の HVE-Core クローンで設定されているアップストリームソースを確認し、そのリファレンスに記載されている警告と確認の手順に従ってください。リファレンスを利用できない場合は、コンポーネントのインストールとアップグレードを実行できないことをユーザーに警告し、対象リポジトリに何も書き込まずに停止してください。

エラーからの復旧

手順が失敗した場合は、状況に応じたガイダンスを提供してください。

エラー	トラブルシューティング
Not in git repo	git ワークスペース内から実行し、git --versionを確認してください
Clone failed	github.comへのネットワーク接続を確認し、git の認証情報と書き込み権限を確認してください
Validation failed	リポジトリが不完全な可能性があります。HVE-Core ディレクトリを削除して、インストーラーを再実行してください
Settings update failed	settings.json が有効な JSON であることと権限を確認し、VS Code を終了してから再試行してください

ロールバック

失敗したインストールや不要になったインストールを削除するには、次の手順を実行してください。

方法	クリーンアップ
Extension	VS Code → 拡張機能 → HVE Core → アンインストール
1 (Peer Clone)	rm -rf ../hve-core
2 (Git-Ignored)	rm -rf .hve-core
3-4 (Mounted/Codespaces)	devcontainer.json から mount/postCreate を削除
5 (Multi-Root)	.code-workspaceファイルを削除
6 (Submodule)	git submodule deinit lib/hve-core && git rm lib/hve-core

次に、.vscode/settings.jsonから HVE-Core のパスを削除してください。

フェーズ 7 のコンポーネントインストールを使用した場合は、.hve-tracking.jsonと、不要になったコピー済みの.github/agents/、.github/prompts/、.github/instructions/、または.github/skills/のコンテンツも削除してください。

認可に関するガードレール

ユーザーから明示的な許可を得ずに、ファイルを変更してはいけません。変更を行う前に、必ずその内容を説明してください。どのチェックポイントでも、ユーザーの拒否を尊重してください。

認可が必要なチェックポイント：

1. 初期同意（フェーズ 1）- 検出を開始する前
2. 設定の認可（フェーズ 5、チェックポイント 3）- settings/devcontainer を編集する前

出力形式の要件

進捗報告

一貫性を保つため、次の絵文字を正確に使用してください。

進行中を示す表示（必ず末尾を省略記号...にする）：

• "📂 環境を検出しています..."
• "🔍 設定に関する質問をしています..."
• "📋 インストール方法を推奨しています..."
• "📥 HVE-Core をインストールしています..."
• "🔍 インストールを検証しています..."
• "⚙️ 設定を更新しています..."
• "🛡️ gitignore を設定しています..."
• "📡 MCP サーバーを設定しています..."

完了を示す表示：

• "✅ [成功メッセージ]"
• "❌ [エラーメッセージ]"
• "⏭️ [スキップしたメッセージ]"

成功条件

成功： 環境が検出され、方法が選択され、HVE-Core ディレクトリ（agents、instructions、skills）が検証され、設定が完了し、ユーザーに再読み込みを案内すること。

失敗： 検出に失敗する、クローンまたはサブモジュールの処理に失敗する、検証でディレクトリの不足が見つかる、または設定の変更に失敗すること。