Labsco
microsoft logo

hve-core-installer

✓ Official★ 1,200

by microsoft · part of microsoft/hve-core

Decision-driven installer for HVE-Core with 6 clone-based installation methods, extension quick-install, environment detection, and agent customization…

🔥🔥✓ VerifiedFreeQuick setup
#automation#cloud#devops#git#maps#security#design#project-mgmt
🔒 Repo-maintenance skill. It exists to help maintain microsoft/hve-core itself — it's only useful if you contribute code to that project.

Decision-driven installer for HVE-Core with 6 clone-based installation methods, extension quick-install, environment detection, and agent customization…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by microsoft

Decision-driven installer for HVE-Core with 6 clone-based installation methods, extension quick-install, environment detection, and agent customization… npx skills add https://github.com/microsoft/hve-core --skill hve-core-installer Download ZIPGitHub1.2k

Role Definition

Operate as two collaborating personas:

  • The Installer persona detects the environment, guides method selection, and executes installation steps

  • The Validator persona verifies installation success by checking paths, settings, and agent accessibility

The Installer persona handles all detection and execution. After installation completes, switch to the Validator persona to verify success before reporting completion.

Re-run Behavior: Running the installer again validates an existing installation or offers upgrade. Safe to re-run anytime.

Required Phases

Phase Name Purpose 1 Environment Detection Obtain consent and detect user's environment 2 Installation Path Selection Choose between Extension (quick) or Clone-based installation 3 Environment Detection & Decision Matrix For clone path: detect environment and recommend method 4 Installation Methods Execute the selected installation method 5 Validation Verify installation success and configure settings 6 Post-Installation Setup Configure gitignore and present MCP guidance 7 Agent Customization Optional: copy agents for local customization (clone-based only)

Flow paths:

  • Extension path: Phase 1 → Phase 2 → Phase 6 → Complete

  • Clone-based path: Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7 → Complete

Phase 1: Environment Detection

Before presenting options, detect the user's environment to filter applicable installation methods.

Checkpoint 1: Initial Consent

Present the following and await explicit consent:

Copy & paste — that's it
🚀 HVE-Core Installer

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

Available content:
• 25+ specialized agents (task-researcher, task-planner, etc.)
• Reusable prompt templates for common workflows
• 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?

If user declines, respond: "Installation cancelled. You can invoke this skill anytime to restart."

Upon consent, proceed to Phase 2 to offer the installation path choice.

Phase 3: Environment Detection & Decision Matrix

Based on detected environment, ask the following questions to determine the recommended method.

Question 1: Environment Confirmation

Present options filtered by detection results:

Copy & paste — that's it
### 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)

Question 2: Team or Solo

Copy & paste — that's it
### 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)

Question 3: Update Preference

Ask this question only when multiple methods match the environment + team answers:

Copy & paste — that's it
### 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)

Decision Matrix

Use this matrix to determine the recommended method:

Environment Team Updates Recommended Method Any (simplest) Any - Extension Quick Install (works in all environments) Local (no container) Solo - Method 1: Peer Clone Local (no container) Team Controlled Method 6: Submodule Local devcontainer Solo Auto Method 2: Git-Ignored Local devcontainer Team Controlled Method 6: Submodule Codespaces only Solo Auto Method 4: Codespaces Codespaces only Team Controlled Method 6: Submodule Both local + Codespaces Any Any Method 5: Multi-Root Workspace HVE-Core repo (Codespaces) - - Method 4: Codespaces (already configured)

Method Selection Logic

After gathering answers:

  • Match answers to decision matrix

  • Present recommendation with rationale

  • Offer alternative if user prefers different approach

Copy & paste — that's it

## Phase 5: Validation (Validator Persona)

After installation completes, switch to the **Validator** persona and verify the installation.

 
 [!IMPORTANT]
After successful validation, proceed to Phase 6 for post-installation setup, then Phase 7 for optional agent customization (clone-based methods only).

 

### Checkpoint 3: Settings Authorization

 Before modifying settings.json, present the following:

⚙️ 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)

Copy & paste — that's it

 If user declines: "Installation cancelled. No settings changes were made."

### Validation Workflow

 Run validation based on the selected method. Set the base path variable before running:

 Method Base Path 
 1 `../hve-core` 
 2 `.hve-core` 
 3, 4 `/workspaces/hve-core` 
 5 Check workspace file 
 6 `lib/hve-core` 
 

 **PowerShell:** Run [scripts/validate-installation.ps1](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/validate-installation.ps1) with the `method` and `basePath` variables set.

 **Bash:** Run [scripts/validate-installation.sh](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/validate-installation.sh) with the method number and base path as arguments.

### Success Report

 Upon successful validation, display:

✅ 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: • task-researcher, task-planner, task-implementor, task-reviewer • github-backlog-manager, adr-creation, doc-ops, pr-review • prompt-builder, memory, and more!

📋 Configuring optional settings...

Copy & paste — that's it

 
 After displaying the success report, proceed to Phase 6 for post-installation setup.

## Phase 7: Agent Customization (Optional)

[!IMPORTANT]
Generated scripts in this phase require PowerShell 7+ (`pwsh`). Windows PowerShell 5.1 is not supported.

 
 After Phase 6 completes, offer users the option to copy agent files into their target repository. This phase ONLY applies to clone-based installation methods (1-6), NOT to extension installation.

### Skip Condition

 If user selected **Extension Quick Install** (Option 1) in Phase 2, skip Phase 7 entirely. Extension installation bundles agents automatically.

### Checkpoint 6: Agent Copy Decision

 Present the agent selection prompt:

📂 Agent Customization (Optional)

HVE-Core includes specialized agents for common workflows. Copying agents enables local customization and offline use.

🔬 RPI Core (Research-Plan-Implement workflow) • task-researcher - Technical research and evidence gathering • task-planner - Implementation plan creation • task-implementor - Plan execution with tracking • task-reviewer - Implementation review and validation • rpi-agent - RPI workflow coordinator

📋 Planning & Documentation • adr-creation, agile-coach, brd-builder, doc-ops, prd-builder • product-manager-advisor, security-planner, ux-ui-designer

⚙️ Generators • gen-data-spec, gen-jupyter-notebook, gen-streamlit-dashboard

✅ Review & Testing • pr-review, prompt-builder, test-streamlit-dashboard

🧠 Utilities • memory - Conversation memory and session continuity

🔗 Platform-Specific • ado-prd-to-wit (Azure DevOps) • github-backlog-manager (GitHub)

Options: [1] Install RPI Core only (recommended) [2] Install by collection [3] Skip agent installation

Your choice? (1/2/3)

Copy & paste — that's it

 
 User input handling:

 

- "1", "rpi", "rpi core", "core" → Copy RPI Core bundle only 

- "2", "collection", "by collection" → Proceed to Collection Selection sub-flow 

- "3", "skip", "none", "no" → Skip to success report 

- Unclear response → Ask for clarification 

### Collection Selection Sub-Flow

 When the user selects option 2, read collection manifests to present available collections.

#### Step 1: Read collections and build collection agent counts

 Read `collections/*.collection.yml` from the HVE-Core source (at `$hveCoreBasePath`). Derive collection options from collection `id` and `name`. For each selected collection, count agent items where `kind` equals `agent` and effective item maturity is `stable` (item `maturity` omitted defaults to `stable`; exclude `experimental` and `deprecated`).

#### Step 2: Present collection options

🎭 Collection Selection

Choose one or more collections to install agents tailored to your role, more to come in the future.

#CollectionAgentsDescription
1Developer[N]Software engineers writing code

Enter collection number(s) separated by commas (e.g., "1"):

Copy & paste — that's it

 
 Agent counts `[N]` include agents matching the collection with `stable` maturity.

 User input handling:

 

- Single number (e.g., "1") → Select that collection 

- Multiple numbers (e.g., "1, 3") → Combine agent sets from selected collections 

- Collection name (e.g., "developer") → Match by identifier 

- Unclear response → Ask for clarification 

#### Step 3: Build filtered agent list

 For each selected collection identifier:

 

- Iterate through `items` in the collection manifest 

- Include items where `kind` is `agent` AND `maturity` is `stable` 

- Deduplicate across multiple selected collections 

#### Step 4: Present filtered agents for confirmation

📋 Agents for [Collection Name(s)]

The following [N] agents will be copied:

• [agent-name-1] - tags: [tag-1, tag-2] • [agent-name-2] - tags: [tag-1, tag-2] ...

Proceed with installation? (yes/no)

Copy & paste — that's it

 
 User input handling:

 

- "yes", "y" → Proceed with copy using filtered agent list 

- "no", "n" → Return to Checkpoint 6 for re-selection 

- Unclear response → Ask for clarification 

 
 [!NOTE]
Collection filtering applies to agents only. Copying of related prompts, instructions, and skills based on collection is planned for a future release.

 

### Agent Bundle Definitions

 Bundle Agents 
 `hve-core` task-researcher, task-planner, task-implementor, task-reviewer, rpi-agent 
 `collection:<id>` Stable agents matching the collection 
 

### Collision Detection

 Before copying, check for existing agent files with matching names.

 **PowerShell:** Run [scripts/collision-detection.ps1](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/collision-detection.ps1) with the `hveCoreBasePath`, `selection`, and optional `collectionAgents` variables set.

 **Bash:** Run [scripts/collision-detection.sh](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/collision-detection.sh) with the HVE-Core base path and file list as arguments.

### Collision Resolution Prompt

 If collisions are detected, present:

⚠️ Existing Agents Detected

The following agents already exist in your project: • [list collision files]

Options: [O] Overwrite with HVE-Core version [K] Keep existing (skip these files) [C] Compare (show diff for first file)

Or for all conflicts: [OA] Overwrite all [KA] Keep all existing

Your choice?

Copy & paste — that's it

 
 User input handling:

 

- "o", "overwrite" → Overwrite current file, ask about next 

- "k", "keep" → Keep current file, ask about next 

- "c", "compare" → Show diff, then re-prompt 

- "oa", "overwrite all" → Overwrite all collisions 

- "ka", "keep all" → Keep all existing files 

### Agent Copy Execution

 After selection and collision resolution, execute the copy operation.

 **PowerShell:** Run [scripts/agent-copy.ps1](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/agent-copy.ps1) with the required variables set.

 **Bash:** Run [scripts/agent-copy.sh](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/agent-copy.sh) with the HVE-Core base path, collection ID, and file list as arguments.

### Agent Copy Success Report

 Upon successful copy, display:

✅ Agent Installation Complete!

Copied [N] agents to .github/agents/ Created .hve-tracking.json for upgrade tracking

📄 Installed Agents: • [list of copied agent names]

🔄 Upgrade Workflow: Run this installer again to check for agent updates. Modified files will prompt before overwriting. Use 'eject' to take ownership of any file.

Proceeding to final success report...

Copy & paste — that's it

## Phase 7 Upgrade Mode

When `.hve-tracking.json` already exists, Phase 7 operates in upgrade mode.

### Upgrade Detection

 At Phase 7 start, check for existing manifest.

 **PowerShell:** Run [scripts/upgrade-detection.ps1](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/upgrade-detection.ps1) with the `hveCoreBasePath` variable set.

 **Bash:** Run [scripts/upgrade-detection.sh](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/upgrade-detection.sh) with the HVE-Core base path as an argument.

### Upgrade Prompt

 If upgrade mode with version change:

🔄 HVE-Core Agent Upgrade

Source: microsoft/hve-core v[SOURCE_VERSION] Installed: v[INSTALLED_VERSION]

Checking file status...

Copy & paste — that's it

 

### File Status Check

 Compare current files against manifest.

 **PowerShell:** Run [scripts/file-status-check.ps1](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/file-status-check.ps1).

 **Bash:** Run [scripts/file-status-check.sh](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/file-status-check.sh) to compare files against the manifest.

### Upgrade Summary Display

 Present upgrade summary:

📋 Upgrade Summary

Files to update (managed): ✅ .github/agents/hve-core/task-researcher.agent.md ✅ .github/agents/hve-core/task-planner.agent.md

Files requiring decision (modified): ⚠️ .github/agents/hve-core/task-implementor.agent.md

Files skipped (ejected): 🔒 .github/agents/custom-agent.agent.md

For modified files, choose: [A] Accept upstream (overwrite your changes) [K] Keep local (skip this update) [E] Eject (never update this file again) [D] Show diff

Process file: task-implementor.agent.md?

Copy & paste — that's it

 

### Diff Display

 When user requests diff:

───────────────────────────────────── File: .github/agents/hve-core/task-implementor.agent.md Status: modified ─────────────────────────────────────

--- Local version +++ HVE-Core version

@@ -10,3 +10,5 @@

Role Definition

-Your local modifications here +Updated behavior with new capabilities + +New section added in latest version ─────────────────────────────────────

[A] Accept upstream / [K] Keep local / [E] Eject

Copy & paste — that's it

 

### Status Transitions

 After user decision, update manifest:

 Decision Status Change Manifest Update 
 Accept `modified` → `managed` Update hash, version 
 Keep `modified` → `modified` No change (skip file) 
 Eject `*` → `ejected` Add `ejectedAt` timestamp 
 

### Eject Implementation

 When user ejects a file:

 **PowerShell:** Run [scripts/eject.ps1](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/eject.ps1) with the `FilePath` parameter.

 **Bash:** Run [scripts/eject.sh](https://github.com/microsoft/hve-core/blob/main/.github/skills/installer/hve-core-installer/scripts/eject.sh) with the file path as an argument.

### Upgrade Completion

 After processing all files:

✅ Upgrade Complete!

Updated: [N] files Skipped: [M] files (kept local or ejected) Version: v[OLD] → v[NEW]

Proceeding to final success report...

Copy & paste — that's it

## Error Recovery

Provide targeted guidance when steps fail:

 

 Error Troubleshooting 
 **Not in git repo** Run from within a git workspace; verify `git --version` 
 **Clone failed** Check network to github.com; verify git credentials and write permissions 
 **Validation failed** Repository may be incomplete; delete HVE-Core directory and re-run installer 
 **Settings update failed** Verify settings.json is valid JSON; check permissions; try closing VS Code

## Rollback

To remove a failed or unwanted installation:

 Method Cleanup 
 Extension VS Code → Extensions → HVE Core → Uninstall 
 1 (Peer Clone) `rm -rf ../hve-core` 
 2 (Git-Ignored) `rm -rf .hve-core` 
 3-4 (Mounted/Codespaces) Remove mount/postCreate from devcontainer.json 
 5 (Multi-Root) Delete `.code-workspace` file 
 6 (Submodule) `git submodule deinit lib/hve-core && git rm lib/hve-core` 
 

 Then remove HVE-Core paths from `.vscode/settings.json`.

 If you used Phase 7 agent copy, also delete `.hve-tracking.json` and optionally `.github/agents/` if you no longer need copied agents.

## Authorization Guardrails

Never modify files without explicit user authorization. Always explain changes before making them. Respect denial at any checkpoint.

 Checkpoints requiring authorization:

 

- Initial Consent (Phase 1) - before starting detection 

- Settings Authorization (Phase 5, Checkpoint 3) - before editing settings/devcontainer

## Success Criteria

**Success:** Environment detected, method selected, HVE-Core directories validated (agents, prompts, instructions, skills), settings configured, user directed to reload.

 **Failure:** Detection fails, clone/submodule fails, validation finds missing directories, or settings modification fails.