microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/getting-started/install.md
241lines · modecode
| 1 | --- |
| 2 | title: Installing HVE-Core |
| 3 | description: Choose the right installation method for your environment |
| 4 | sidebar_position: 2 |
| 5 | author: Microsoft |
| 6 | ms.date: 2025-12-02 |
| 7 | ms.topic: how-to |
| 8 | keywords: |
| 9 | - installation |
| 10 | - setup |
| 11 | - github copilot |
| 12 | - devcontainer |
| 13 | - codespaces |
| 14 | estimated_reading_time: 5 |
| 15 | --- |
| 16 | |
| 17 | HVE-Core provides GitHub Copilot customizations (custom agents, instructions, and prompts) that enhance your development workflow. This guide helps you choose the right installation method for your environment. |
| 18 | |
| 19 | ## Recommended: VS Code Extension ⭐ |
| 20 | |
| 21 | **For most users**, the simplest method is to install directly from the VS Code Marketplace: |
| 22 | |
| 23 | ```text |
| 24 | VS Code → Extensions → Search "HVE Core" → Install |
| 25 | ``` |
| 26 | |
| 27 | **Or visit:** [HVE Core on Marketplace](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) |
| 28 | |
| 29 | **Why choose the extension:** |
| 30 | |
| 31 | * ✅ Zero configuration required |
| 32 | * ✅ Automatic updates via VS Code |
| 33 | * ✅ Works everywhere (local, devcontainers, Codespaces) |
| 34 | * ✅ No project files needed |
| 35 | * ✅ Instant availability |
| 36 | |
| 37 | **When to use alternatives:** |
| 38 | |
| 39 | * ❌ You need to customize components → Use custom installation methods below |
| 40 | * ❌ Team needs version control → Use [Submodule](methods/submodule.md) |
| 41 | * ❌ Contributing to HVE-Core → Use [Peer Clone](methods/peer-clone.md) |
| 42 | |
| 43 | See [Extension Installation Guide](methods/extension.md) for complete documentation. |
| 44 | |
| 45 | ## Custom Installation Methods |
| 46 | |
| 47 | If you need customization or version control of HVE-Core, choose from the methods below. |
| 48 | |
| 49 | ## Quick Start |
| 50 | |
| 51 | > **Starter prompt:** "Help me choose how to install this library" |
| 52 | |
| 53 | Open Copilot Chat, select the `hve-core-installer` agent, and use this prompt. The agent will ask three questions about your environment and recommend the best method. |
| 54 | |
| 55 | ## Help Me Choose |
| 56 | |
| 57 | Answer these questions to find your recommended installation method: |
| 58 | |
| 59 | 1. **What's your development environment?** |
| 60 | * Local VS Code (no devcontainer) |
| 61 | * Local devcontainer (Docker Desktop) |
| 62 | * GitHub Codespaces |
| 63 | * Both local and Codespaces |
| 64 | |
| 65 | 2. **Solo or team development?** |
| 66 | * Solo: Just you, no version control of HVE-Core needed |
| 67 | * Team: Multiple people, need reproducible setup |
| 68 | |
| 69 | 3. **Update preference?** |
| 70 | * Auto: Always get latest HVE-Core |
| 71 | * Controlled: Pin to specific version, update explicitly |
| 72 | |
| 73 | ### Decision Matrix |
| 74 | |
| 75 | | Environment | Team | Updates | Recommended Method | |
| 76 | |---------------------------|------|------------|-----------------------------------------------| |
| 77 | | **Any** (simplest) | Any | Auto | [VS Code Extension](methods/extension.md) ⭐ | |
| 78 | | Local (no container) | Solo | Manual | [Peer Directory Clone](methods/peer-clone.md) | |
| 79 | | Local (no container) | Team | Controlled | [Submodule](methods/submodule.md) | |
| 80 | | Local devcontainer | Solo | Auto | [Git-Ignored Folder](methods/git-ignored.md) | |
| 81 | | Local devcontainer | Team | Controlled | [Submodule](methods/submodule.md) | |
| 82 | | Codespaces only | Solo | Auto | [GitHub Codespaces](methods/codespaces.md) | |
| 83 | | Codespaces only | Team | Controlled | [Submodule](methods/submodule.md) | |
| 84 | | Both local + Codespaces | Any | Any | [Multi-Root Workspace](methods/multi-root.md) | |
| 85 | | Advanced (shared install) | Solo | Auto | [Mounted Directory](methods/mounted.md) | |
| 86 | |
| 87 | ⭐ **VS Code Extension** is the recommended method for most users who don't need customization. |
| 88 | |
| 89 | ## Collection Packages |
| 90 | |
| 91 | HVE-Core supports role-based artifact collections tailored to specific roles: |
| 92 | |
| 93 | | Collection | Extension Name | Collection ID | Maturity | Description | |
| 94 | |---------------|-----------------|----------------|--------------|--------------------------------------| |
| 95 | | **Full** | `hve-core` | `hve-core-all` | Stable | All artifacts (recommended for most) | |
| 96 | | **Developer** | `hve-developer` | `developer` | Experimental | Software engineering focus | |
| 97 | |
| 98 | > [!NOTE] |
| 99 | > Experimental collections are only available via PreRelease extension builds. The Stable channel includes the Full collection only. |
| 100 | |
| 101 | ### Extension Installation (Full Collection) |
| 102 | |
| 103 | The VS Code Marketplace extension installs the **full collection** containing all stable artifacts. This is the recommended approach for most users. |
| 104 | |
| 105 | ### Clone Methods (Collection Filtering) |
| 106 | |
| 107 | Clone-based installation methods support collection-based agent filtering through the installer agent: |
| 108 | |
| 109 | 1. Clone the repository using your preferred method |
| 110 | 2. Run the `hve-core-installer` agent |
| 111 | 3. In Phase 7 (Agent Customization), select your role-based collection or install all agents |
| 112 | |
| 113 | The installer reads collection assignments from the collection manifests (`collections/*.collection.yml`) and copies only the agents assigned to your selected collection. Agents marked for all collections are always included. |
| 114 | |
| 115 | > [!NOTE] |
| 116 | > Collection filtering applies to agents only. Copying of related prompts, instructions, and skills based on collection is planned for a future release. |
| 117 | |
| 118 | ### Quick Decision Tree |
| 119 | |
| 120 | ```text |
| 121 | ┌─────────────────────────────────────────────────────────────────┐ |
| 122 | │ │ |
| 123 | │ Want the simplest setup? │ |
| 124 | │ └─ Yes ──────────────────────────────► VS Code Extension ⭐ │ |
| 125 | │ │ |
| 126 | │ Need to customize HVE-Core? │ |
| 127 | │ ├─ Local VS Code only ──────────────► Peer Directory Clone │ |
| 128 | │ ├─ Local devcontainer only ─────────► Git-Ignored Folder │ |
| 129 | │ ├─ Codespaces only ─────────────────► GitHub Codespaces │ |
| 130 | │ └─ Both local + Codespaces ─────────► Multi-Root Workspace │ |
| 131 | │ │ |
| 132 | │ Working in a team? │ |
| 133 | │ └─ Yes, need version control ───────► Submodule │ |
| 134 | │ │ |
| 135 | └─────────────────────────────────────────────────────────────────┘ |
| 136 | ``` |
| 137 | |
| 138 | ## Installation Methods |
| 139 | |
| 140 | ### Simplest Method (Recommended for Most Users) |
| 141 | |
| 142 | | Method | Best For | Complexity | |
| 143 | |---------------------------------------------|----------------------------------|------------| |
| 144 | | [VS Code Extension](methods/extension.md) ⭐ | Anyone wanting zero-config setup | Minimal | |
| 145 | |
| 146 | ### Consumer Methods (Customization + Version Control) |
| 147 | |
| 148 | These methods are for projects that want to use and potentially customize HVE-Core's components: |
| 149 | |
| 150 | | Method | Best For | Complexity | |
| 151 | |-----------------------------------------------|-------------------------------|------------| |
| 152 | | [Multi-Root Workspace](methods/multi-root.md) | Any environment, portable | Low | |
| 153 | | [Submodule](methods/submodule.md) | Teams needing version control | Medium | |
| 154 | |
| 155 | ### Developer Methods |
| 156 | |
| 157 | These methods are for HVE-Core contributors or advanced scenarios: |
| 158 | |
| 159 | | Method | Best For | Complexity | |
| 160 | |-----------------------------------------------|-------------------------------|------------| |
| 161 | | [Peer Directory Clone](methods/peer-clone.md) | Local VS Code, solo | Low | |
| 162 | | [Git-Ignored Folder](methods/git-ignored.md) | Local devcontainer, solo | Low | |
| 163 | | [Mounted Directory](methods/mounted.md) | Advanced devcontainer sharing | High | |
| 164 | | [GitHub Codespaces](methods/codespaces.md) | Codespaces-only projects | Medium | |
| 165 | |
| 166 | ## Using the Installer Agent |
| 167 | |
| 168 | The `hve-core-installer` agent automates any installation method: |
| 169 | |
| 170 | 1. Open GitHub Copilot Chat in VS Code (`Ctrl+Alt+I`) |
| 171 | 2. Select `hve-core-installer` from the agent picker |
| 172 | 3. Answer the environment detection questions |
| 173 | 4. The agent executes your chosen method |
| 174 | |
| 175 | The agent handles: |
| 176 | |
| 177 | * Environment detection (Local VS Code, Devcontainer, Codespaces) |
| 178 | * Repository cloning or configuration |
| 179 | * VS Code settings updates |
| 180 | * Devcontainer configuration |
| 181 | * Validation of the installation |
| 182 | |
| 183 | ## Validation |
| 184 | |
| 185 | After installation, verify everything works: |
| 186 | |
| 187 | 1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) |
| 188 | 2. Click the agent picker dropdown |
| 189 | 3. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder) |
| 190 | 4. Select an agent and submit a test prompt |
| 191 | |
| 192 | Run the installer in validation mode: |
| 193 | |
| 194 | > "Validate my HVE-Core installation" |
| 195 | |
| 196 | ## Post-Installation: Update Your .gitignore |
| 197 | |
| 198 | HVE-Core agents create ephemeral workflow artifacts in a `.copilot-tracking/` folder within your project. These files include research documents, implementation plans, PR review tracking, and other machine-generated content that should typically not be committed to version control. |
| 199 | |
| 200 | **Add this line to your project's `.gitignore`:** |
| 201 | |
| 202 | ```text |
| 203 | .copilot-tracking/ |
| 204 | ``` |
| 205 | |
| 206 | > [!IMPORTANT] |
| 207 | > This applies to all installation methods (extension, submodule, peer clone, etc.). The `.copilot-tracking/` folder is created in your project directory, not in HVE-Core itself. |
| 208 | |
| 209 | **What gets stored there:** |
| 210 | |
| 211 | * Research documents from `task-researcher` |
| 212 | * Implementation plans from `task-planner` |
| 213 | * PR review artifacts from `pr-review` |
| 214 | * Work item planning files for ADO workflows |
| 215 | * Temporary prompt files used by agents |
| 216 | |
| 217 | These artifacts are useful during your workflow session but are ephemeral by design. They help agents maintain context across sessions without polluting your repository history. |
| 218 | |
| 219 | ## MCP Server Configuration (Optional) |
| 220 | |
| 221 | Some HVE-Core agents use MCP (Model Context Protocol) servers to integrate with Azure DevOps, GitHub, or documentation services. These are optional enhancements; agents work without MCP configuration. |
| 222 | |
| 223 | If you use agents like `ado-prd-to-wit` or `github-backlog-manager`, see [MCP Server Configuration](mcp-configuration.md) for setup instructions. That guide includes: |
| 224 | |
| 225 | * Which agents require which MCP servers |
| 226 | * Complete configuration templates |
| 227 | * Method-specific placement notes (extension, submodule, Codespaces, etc.) |
| 228 | * Troubleshooting for common issues |
| 229 | |
| 230 | ## Next Steps |
| 231 | |
| 232 | * [Your First Workflow](first-workflow.md) - Try HVE-Core with a real task |
| 233 | * [RPI Workflow](../rpi/) - Research, Plan, Implement methodology |
| 234 | * [Contributing](../contributing/) - Contribute to HVE-Core |
| 235 | |
| 236 | --- |
| 237 | |
| 238 | <!-- markdownlint-disable MD036 --> |
| 239 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 240 | then carefully refined by our team of discerning human reviewers.* |
| 241 | <!-- markdownlint-enable MD036 --> |
| 242 | |