microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/getting-started/troubleshooting.md
97lines · modecode
| 1 | --- |
| 2 | title: Troubleshooting |
| 3 | description: Solutions for common installation problems and answers to frequently asked questions about HVE Core collections. |
| 4 | sidebar_position: 8 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-03-11 |
| 7 | ms.topic: troubleshooting |
| 8 | keywords: [troubleshooting, FAQ, installation, collections, hve-core, hve-installer] |
| 9 | estimated_reading_time: 5 |
| 10 | --- |
| 11 | |
| 12 | This page covers common installation problems and answers frequently asked questions about HVE Core extensions and collections. |
| 13 | |
| 14 | ## Common Installation Problems |
| 15 | |
| 16 | ### Extension Not Loading After Install |
| 17 | |
| 18 | The extension appears in the Extensions sidebar but HVE Core agents and prompts are not available in Copilot Chat. |
| 19 | |
| 20 | #### Solutions |
| 21 | |
| 22 | 1. Run the `Developer: Reload Window` command from the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`). |
| 23 | 2. Verify that GitHub Copilot Chat is installed and active in the Extensions sidebar. HVE Core requires it. |
| 24 | 3. Open the Output panel (`Ctrl+Shift+U`) and select the HVE Core channel. Look for error messages during extension activation. |
| 25 | 4. Confirm your VS Code version is 1.99 or later under Help > About. |
| 26 | |
| 27 | ### Agent or Prompt Not Appearing in Copilot |
| 28 | |
| 29 | Some agents or prompts are missing from the `@` mention list or `/` command list in Copilot Chat. |
| 30 | |
| 31 | #### Solutions |
| 32 | |
| 33 | 1. Agents and prompts load from `.github/` directories in the open workspace. Verify that `.github/agents/` and `.github/prompts/` folders exist and contain `.agent.md` or `.prompt.md` files. |
| 34 | 2. Copilot Chat loads workspace-scoped agents only when a folder or workspace is open. Opening a single file does not activate workspace agents. |
| 35 | 3. If you used the HVE Installer, confirm that the selected collections were deployed. Run the installer agent again to verify the installed artifact list. |
| 36 | 4. Ensure your `.gitignore` does not exclude `.github/agents/` or `.github/prompts/` directories. |
| 37 | |
| 38 | ### Collection Conflicts Between HVE Core All and HVE Installer |
| 39 | |
| 40 | Duplicate agents appear in Copilot Chat, or agents behave unexpectedly after installing both extensions. |
| 41 | |
| 42 | #### Solutions |
| 43 | |
| 44 | 1. The HVE Core All extension installs the full `hve-core-all` collection containing every artifact. The HVE Installer deploys individual collections selectively. Using both can produce duplicate artifacts. Choose one extension. |
| 45 | 2. If you want all artifacts, keep HVE Core All and uninstall HVE Installer. If you want selective collections, keep HVE Installer and uninstall HVE Core All. |
| 46 | 3. After uninstalling, delete any leftover `.github/agents/`, `.github/prompts/`, `.github/instructions/`, and `.github/skills/` directories that were deployed by the removed extension. Then reinstall with your preferred method. |
| 47 | |
| 48 | ### Version Compatibility Issues |
| 49 | |
| 50 | Errors appear after updating VS Code or one of the HVE extensions, or agents reference features that do not exist. |
| 51 | |
| 52 | #### Solutions |
| 53 | |
| 54 | 1. When updating VS Code, also update GitHub Copilot, GitHub Copilot Chat, and the HVE extension to their latest versions. |
| 55 | 2. Review the [CHANGELOG](https://github.com/microsoft/hve-core/blob/main/CHANGELOG.md) for breaking changes between versions. |
| 56 | 3. If artifacts are out of sync, remove the existing `.github/` HVE Core artifacts and reinstall using your preferred method. |
| 57 | |
| 58 | ## Collection FAQ |
| 59 | |
| 60 | ### Which Extension Should I Install? |
| 61 | |
| 62 | | Scenario | Recommended Extension | |
| 63 | |-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| |
| 64 | | You want everything HVE Core offers | [HVE Core All](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core-all) (Full) | |
| 65 | | You want only specific domains (ADO, Design Thinking, etc.) | [HVE Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer) (Selective) | |
| 66 | | You plan to contribute to HVE Core | Clone the repository directly, see [Developer Setup](install.md#developer-setup) | |
| 67 | |
| 68 | ### How Do I Switch from HVE Core All to HVE Installer? |
| 69 | |
| 70 | 1. Uninstall the HVE Core All extension from the VS Code Extensions sidebar. |
| 71 | 2. Delete the `.github/` HVE Core artifacts that the extension deployed to your workspace. |
| 72 | 3. Install the [HVE Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer) extension. |
| 73 | 4. Open Copilot Chat and ask any agent: *"help me customize hve-core installation"*. |
| 74 | 5. Select the collections you need. |
| 75 | |
| 76 | ### Can I Use Both Extensions Simultaneously? |
| 77 | |
| 78 | Using both extensions in the same workspace is not recommended. Both deploy artifacts to `.github/` directories, which can result in duplicate agents and prompts. Choose one extension based on whether you need the full collection or selective deployment. See [Collection Conflicts](#collection-conflicts-between-hve-core-all-and-hve-installer) above for details. |
| 79 | |
| 80 | ### How Do I Update to the Latest Collection Version? |
| 81 | |
| 82 | Marketplace extensions update automatically. When a new version is published, VS Code downloads and installs it. You can also manually check for updates in the Extensions sidebar. |
| 83 | |
| 84 | For clone-based setups, pull the latest changes from the upstream repository: |
| 85 | |
| 86 | ```bash |
| 87 | git pull upstream main |
| 88 | ``` |
| 89 | |
| 90 | Then reinstall dependencies with `npm ci` if `package.json` changed. |
| 91 | |
| 92 | --- |
| 93 | |
| 94 | <!-- markdownlint-disable MD036 --> |
| 95 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 96 | then carefully refined by our team of discerning human reviewers.* |
| 97 | <!-- markdownlint-enable MD036 --> |
| 98 | |