microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/getting-started/install.md
211lines · modecode
| 1 | --- |
| 2 | title: Installing HVE-Core |
| 3 | description: Choose the right installation method for your environment |
| 4 | author: Microsoft |
| 5 | ms.date: 2025-12-02 |
| 6 | ms.topic: how-to |
| 7 | keywords: |
| 8 | - installation |
| 9 | - setup |
| 10 | - github copilot |
| 11 | - devcontainer |
| 12 | - codespaces |
| 13 | estimated_reading_time: 5 |
| 14 | --- |
| 15 | |
| 16 | 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. |
| 17 | |
| 18 | ## Recommended: VS Code Extension ⭐ |
| 19 | |
| 20 | **For most users**, the simplest method is to install directly from the VS Code Marketplace: |
| 21 | |
| 22 | ```text |
| 23 | VS Code → Extensions → Search "HVE Core" → Install |
| 24 | ``` |
| 25 | |
| 26 | **Or visit:** [HVE Core on Marketplace](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) |
| 27 | |
| 28 | **Why choose the extension:** |
| 29 | |
| 30 | * ✅ Zero configuration required |
| 31 | * ✅ Automatic updates via VS Code |
| 32 | * ✅ Works everywhere (local, devcontainers, Codespaces) |
| 33 | * ✅ No project files needed |
| 34 | * ✅ Instant availability |
| 35 | |
| 36 | **When to use alternatives:** |
| 37 | |
| 38 | * ❌ You need to customize components → Use custom installation methods below |
| 39 | * ❌ Team needs version control → Use [Submodule](methods/submodule.md) |
| 40 | * ❌ Contributing to HVE-Core → Use [Peer Clone](methods/peer-clone.md) |
| 41 | |
| 42 | See [Extension Installation Guide](methods/extension.md) for complete documentation. |
| 43 | |
| 44 | ## Custom Installation Methods |
| 45 | |
| 46 | If you need customization or version control of HVE-Core, choose from the methods below. |
| 47 | |
| 48 | ## Quick Start |
| 49 | |
| 50 | > **Starter prompt:** "Help me choose how to install this library" |
| 51 | |
| 52 | 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. |
| 53 | |
| 54 | ## Help Me Choose |
| 55 | |
| 56 | Answer these questions to find your recommended installation method: |
| 57 | |
| 58 | 1. **What's your development environment?** |
| 59 | * Local VS Code (no devcontainer) |
| 60 | * Local devcontainer (Docker Desktop) |
| 61 | * GitHub Codespaces |
| 62 | * Both local and Codespaces |
| 63 | |
| 64 | 2. **Solo or team development?** |
| 65 | * Solo: Just you, no version control of HVE-Core needed |
| 66 | * Team: Multiple people, need reproducible setup |
| 67 | |
| 68 | 3. **Update preference?** |
| 69 | * Auto: Always get latest HVE-Core |
| 70 | * Controlled: Pin to specific version, update explicitly |
| 71 | |
| 72 | ### Decision Matrix |
| 73 | |
| 74 | | Environment | Team | Updates | Recommended Method | |
| 75 | |---------------------------|------|------------|-----------------------------------------------| |
| 76 | | **Any** (simplest) | Any | Auto | [VS Code Extension](methods/extension.md) ⭐ | |
| 77 | | Local (no container) | Solo | Manual | [Peer Directory Clone](methods/peer-clone.md) | |
| 78 | | Local (no container) | Team | Controlled | [Submodule](methods/submodule.md) | |
| 79 | | Local devcontainer | Solo | Auto | [Git-Ignored Folder](methods/git-ignored.md) | |
| 80 | | Local devcontainer | Team | Controlled | [Submodule](methods/submodule.md) | |
| 81 | | Codespaces only | Solo | Auto | [GitHub Codespaces](methods/codespaces.md) | |
| 82 | | Codespaces only | Team | Controlled | [Submodule](methods/submodule.md) | |
| 83 | | Both local + Codespaces | Any | Any | [Multi-Root Workspace](methods/multi-root.md) | |
| 84 | | Advanced (shared install) | Solo | Auto | [Mounted Directory](methods/mounted.md) | |
| 85 | |
| 86 | ⭐ **VS Code Extension** is the recommended method for most users who don't need customization. |
| 87 | |
| 88 | ### Quick Decision Tree |
| 89 | |
| 90 | ```text |
| 91 | ┌─────────────────────────────────────────────────────────────────┐ |
| 92 | │ │ |
| 93 | │ Want the simplest setup? │ |
| 94 | │ └─ Yes ──────────────────────────────► VS Code Extension ⭐ │ |
| 95 | │ │ |
| 96 | │ Need to customize HVE-Core? │ |
| 97 | │ ├─ Local VS Code only ──────────────► Peer Directory Clone │ |
| 98 | │ ├─ Local devcontainer only ─────────► Git-Ignored Folder │ |
| 99 | │ ├─ Codespaces only ─────────────────► GitHub Codespaces │ |
| 100 | │ └─ Both local + Codespaces ─────────► Multi-Root Workspace │ |
| 101 | │ │ |
| 102 | │ Working in a team? │ |
| 103 | │ └─ Yes, need version control ───────► Submodule │ |
| 104 | │ │ |
| 105 | └─────────────────────────────────────────────────────────────────┘ |
| 106 | ``` |
| 107 | |
| 108 | ## Installation Methods |
| 109 | |
| 110 | ### Simplest Method (Recommended for Most Users) |
| 111 | |
| 112 | | Method | Best For | Complexity | |
| 113 | |---------------------------------------------|----------------------------------|------------| |
| 114 | | [VS Code Extension](methods/extension.md) ⭐ | Anyone wanting zero-config setup | Minimal | |
| 115 | |
| 116 | ### Consumer Methods (Customization + Version Control) |
| 117 | |
| 118 | These methods are for projects that want to use and potentially customize HVE-Core's components: |
| 119 | |
| 120 | | Method | Best For | Complexity | |
| 121 | |-----------------------------------------------|-------------------------------|------------| |
| 122 | | [Multi-Root Workspace](methods/multi-root.md) | Any environment, portable | Low | |
| 123 | | [Submodule](methods/submodule.md) | Teams needing version control | Medium | |
| 124 | |
| 125 | ### Developer Methods |
| 126 | |
| 127 | These methods are for HVE-Core contributors or advanced scenarios: |
| 128 | |
| 129 | | Method | Best For | Complexity | |
| 130 | |-----------------------------------------------|-------------------------------|------------| |
| 131 | | [Peer Directory Clone](methods/peer-clone.md) | Local VS Code, solo | Low | |
| 132 | | [Git-Ignored Folder](methods/git-ignored.md) | Local devcontainer, solo | Low | |
| 133 | | [Mounted Directory](methods/mounted.md) | Advanced devcontainer sharing | High | |
| 134 | | [GitHub Codespaces](methods/codespaces.md) | Codespaces-only projects | Medium | |
| 135 | |
| 136 | ## Using the Installer Agent |
| 137 | |
| 138 | The `hve-core-installer` agent automates any installation method: |
| 139 | |
| 140 | 1. Open GitHub Copilot Chat in VS Code (`Ctrl+Alt+I`) |
| 141 | 2. Select `hve-core-installer` from the agent picker |
| 142 | 3. Answer the environment detection questions |
| 143 | 4. The agent executes your chosen method |
| 144 | |
| 145 | The agent handles: |
| 146 | |
| 147 | * Environment detection (Local VS Code, Devcontainer, Codespaces) |
| 148 | * Repository cloning or configuration |
| 149 | * VS Code settings updates |
| 150 | * Devcontainer configuration |
| 151 | * Validation of the installation |
| 152 | |
| 153 | ## Validation |
| 154 | |
| 155 | After installation, verify everything works: |
| 156 | |
| 157 | 1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) |
| 158 | 2. Click the agent picker dropdown |
| 159 | 3. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder) |
| 160 | 4. Select an agent and submit a test prompt |
| 161 | |
| 162 | Run the installer in validation mode: |
| 163 | |
| 164 | > "Validate my HVE-Core installation" |
| 165 | |
| 166 | ## Post-Installation: Update Your .gitignore |
| 167 | |
| 168 | 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. |
| 169 | |
| 170 | **Add this line to your project's `.gitignore`:** |
| 171 | |
| 172 | ```text |
| 173 | .copilot-tracking/ |
| 174 | ``` |
| 175 | |
| 176 | > [!IMPORTANT] |
| 177 | > 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. |
| 178 | |
| 179 | **What gets stored there:** |
| 180 | |
| 181 | * Research documents from `task-researcher` |
| 182 | * Implementation plans from `task-planner` |
| 183 | * PR review artifacts from `pr-review` |
| 184 | * Work item planning files for ADO workflows |
| 185 | * Temporary prompt files used by agents |
| 186 | |
| 187 | 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. |
| 188 | |
| 189 | ## MCP Server Configuration (Optional) |
| 190 | |
| 191 | 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. |
| 192 | |
| 193 | If you use agents like `ado-prd-to-wit` or `github-issue-manager`, see [MCP Server Configuration](mcp-configuration.md) for setup instructions. That guide includes: |
| 194 | |
| 195 | * Which agents require which MCP servers |
| 196 | * Complete configuration templates |
| 197 | * Method-specific placement notes (extension, submodule, Codespaces, etc.) |
| 198 | * Troubleshooting for common issues |
| 199 | |
| 200 | ## Next Steps |
| 201 | |
| 202 | * [Your First Workflow](first-workflow.md) - Try HVE-Core with a real task |
| 203 | * [RPI Workflow](../rpi/README.md) - Research, Plan, Implement methodology |
| 204 | * [Contributing](../contributing/README.md) - Contribute to HVE-Core |
| 205 | |
| 206 | --- |
| 207 | |
| 208 | <!-- markdownlint-disable MD036 --> |
| 209 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 210 | then carefully refined by our team of discerning human reviewers.* |
| 211 | <!-- markdownlint-enable MD036 --> |
| 212 | |