microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/getting-started/README.md
121lines · modecode
| 1 | --- |
| 2 | title: Getting Started with HVE Core |
| 3 | description: Quick setup guide for using HVE Core Copilot customizations in your projects |
| 4 | author: Microsoft |
| 5 | ms.date: 2025-12-02 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - github copilot |
| 9 | - multi-root workspace |
| 10 | - setup |
| 11 | - getting started |
| 12 | estimated_reading_time: 5 |
| 13 | --- |
| 14 | |
| 15 | HVE Core provides GitHub Copilot customizations (custom agents, instructions, and prompts) that enhance your development workflow. This guide helps you get started quickly. |
| 16 | |
| 17 | ## Installation |
| 18 | |
| 19 | ### Quick Install: VS Code Extension ⭐ |
| 20 | |
| 21 | **Simplest method:** Install directly from VS Code Marketplace: |
| 22 | |
| 23 | 1. Open VS Code Extensions view (`Ctrl+Shift+X`) |
| 24 | 2. Search for "HVE Core" |
| 25 | 3. Click **Install** |
| 26 | |
| 27 | Or visit: [HVE Core on Marketplace](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) |
| 28 | |
| 29 | **Pros:** Zero configuration, automatic updates, works everywhere |
| 30 | **Cons:** Cannot customize components |
| 31 | |
| 32 | See [Extension Installation Guide](methods/extension.md) for full details. |
| 33 | |
| 34 | ### Custom Installation |
| 35 | |
| 36 | For customization or version control, see [Installing HVE-Core](install.md) to choose from six installation methods. |
| 37 | |
| 38 | > **Contributing to HVE-Core?** See the [Contributing Guide](../contributing/README.md) for development setup and contribution guidelines. |
| 39 | |
| 40 | **Quick start:** Use the `hve-core-installer` agent: |
| 41 | |
| 42 | 1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) |
| 43 | 2. Select `hve-core-installer` from the agent picker |
| 44 | 3. Follow the guided installation |
| 45 | |
| 46 | ### Installation Methods |
| 47 | |
| 48 | HVE-Core supports seven installation methods. See the [installation guide](install.md) for a decision matrix to help you choose: |
| 49 | |
| 50 | | Method | Best For | |
| 51 | |-----------------------------------------------|-------------------------------| |
| 52 | | [VS Code Extension](methods/extension.md) ⭐ | Simplest, no config needed | |
| 53 | | [Multi-Root Workspace](methods/multi-root.md) | Any environment, portable | |
| 54 | | [Submodule](methods/submodule.md) | Teams needing version control | |
| 55 | | [Peer Directory Clone](methods/peer-clone.md) | Local VS Code, solo | |
| 56 | | [Git-Ignored Folder](methods/git-ignored.md) | Local devcontainer, solo | |
| 57 | | [Mounted Directory](methods/mounted.md) | Advanced devcontainer sharing | |
| 58 | | [GitHub Codespaces](methods/codespaces.md) | Codespaces-only projects | |
| 59 | |
| 60 | ## Verifying Setup |
| 61 | |
| 62 | After installation, verify everything works: |
| 63 | |
| 64 | 1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) |
| 65 | 2. Click the **agent picker dropdown** |
| 66 | 3. Verify HVE-Core agents appear: |
| 67 | - task-planner |
| 68 | - task-researcher |
| 69 | - prompt-builder |
| 70 | - pr-review |
| 71 | 4. Select an agent and submit a test prompt |
| 72 | |
| 73 | ## Troubleshooting |
| 74 | |
| 75 | ### Installation Issues |
| 76 | |
| 77 | #### Agent not available |
| 78 | |
| 79 | - Ensure GitHub Copilot extension is installed and active |
| 80 | - Reload VS Code window: `Ctrl+Shift+P` → "Developer: Reload Window" |
| 81 | - Check that hve-core is accessible (cloned or configured correctly) |
| 82 | |
| 83 | #### Copilot not discovering customizations |
| 84 | |
| 85 | - For Multi-Root: Ensure you opened the `.code-workspace` file, not just the folder |
| 86 | - Verify `chat.modeFilesLocations` points to the correct path |
| 87 | - Check the window title shows the workspace name |
| 88 | |
| 89 | #### Git or clone errors |
| 90 | |
| 91 | - Verify Git is installed: run `git --version` in terminal |
| 92 | - Check network connectivity to github.com |
| 93 | - See the [installation guide](install.md) for method-specific troubleshooting |
| 94 | |
| 95 | ## Optional Scripts |
| 96 | |
| 97 | HVE Core includes utility scripts you may want to copy into your project: |
| 98 | |
| 99 | | Script | Purpose | |
| 100 | |----------------------------------------------------|-----------------------------------------------------| |
| 101 | | `scripts/dev-tools/Generate-PrReference.ps1` | Generate PR reference docs for handoff to reviewers | |
| 102 | | `scripts/linting/Validate-MarkdownFrontmatter.ps1` | Validate markdown frontmatter against JSON schemas | |
| 103 | | `scripts/linting/Invoke-PSScriptAnalyzer.ps1` | Run PSScriptAnalyzer with project settings | |
| 104 | | `scripts/security/Test-DependencyPinning.ps1` | Check GitHub Actions for pinned dependencies | |
| 105 | |
| 106 | Copy the scripts you need to your project's `scripts/` directory and adjust paths as needed. |
| 107 | |
| 108 | ## Next Steps |
| 109 | |
| 110 | - Try [Your First Workflow](first-workflow.md) for a quick start |
| 111 | - Learn the [RPI Workflow](../rpi/README.md) for complex tasks |
| 112 | - Explore [Agents](../../.github/CUSTOM-AGENTS.md) for available agents |
| 113 | - Review [Instructions](../../.github/instructions/README.md) for coding guidelines |
| 114 | - Check the [README](../../README.md) for feature overview |
| 115 | |
| 116 | --- |
| 117 | |
| 118 | <!-- markdownlint-disable MD036 --> |
| 119 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 120 | then carefully refined by our team of discerning human reviewers.* |
| 121 | <!-- markdownlint-enable MD036 --> |