GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
hve-core-v2.1.0

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/multi-root.md

216lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Multi-Root Workspace Installation
3description: Set up HVE-Core using VS Code multi-root workspaces for any environment
4author: Microsoft
5ms.date: 2025-12-02
6ms.topic: how-to
7keywords:
8 - multi-root workspace
9 - installation
10 - github copilot
11 - codespaces
12 - devcontainer
13estimated_reading_time: 8
14---
15
16Multi-root workspaces are the **RECOMMENDED** method for consuming HVE-Core. This approach works in any environment (Local VS Code, Devcontainers, Codespaces) and provides the most portable configuration.
17
18## When to Use This Method
19
20✅ **Use this when:**
21
22* You want a single configuration that works everywhere
23* Your project uses Codespaces or devcontainers
24* You need paths that work for the whole team
25* You want integrated source control across both projects
26
27❌ **Consider alternatives when:**
28
29* Your team needs version-pinned dependencies → [Submodule](submodule.md)
30* You're developing HVE-Core itself → [Peer Clone](peer-clone.md)
31
32## How It Works
33
34A `.code-workspace` file defines multiple folders as a single workspace. VS Code treats HVE-Core as part of your project, making all paths work correctly.
35
36```text
37┌─────────────────────────────────────────────┐
38│ VS Code Multi-Root Workspace │
39├─────────────────────────────────────────────┤
40│ 📁 My Project (primary) │
41│ └── Your code │
42│ 📁 HVE-Core Library (secondary) │
43│ └── .github/agents, prompts, etc. │
44└─────────────────────────────────────────────┘
45 ↑
46 .code-workspace file defines this
47```
48
49## Quick Start
50
51Use the `hve-core-installer` agent:
52
531. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
542. Select `hve-core-installer` from the agent picker
553. Say: "Install HVE-Core using multi-root workspace"
564. Follow the guided setup
57
58## Manual Setup
59
60### Step 1: Clone HVE-Core
61
62**Local VS Code:**
63
64```bash
65# Clone next to your project
66cd /path/to/your-projects
67git clone https://github.com/microsoft/hve-core.git
68```
69
70**Codespaces/Devcontainer:** HVE-Core will be cloned automatically (see Step 3).
71
72### Step 2: Create the Workspace File
73
74Create `.devcontainer/hve-core.code-workspace` in your project:
75
76```jsonc
77{
78 "folders": [
79 {
80 "name": "My Project",
81 "path": ".."
82 },
83 {
84 "name": "HVE-Core Library",
85 "path": "/workspaces/hve-core"
86 }
87 ],
88 "settings": {
89 "chat.agentFilesLocations": {
90 "HVE-Core Library/.github/agents": true,
91 "My Project/.github/agents": true
92 },
93 "chat.promptFilesLocations": {
94 "HVE-Core Library/.github/prompts": true,
95 "My Project/.github/prompts": true
96 },
97 "chat.instructionsFilesLocations": {
98 "HVE-Core Library/.github/instructions": true,
99 "My Project/.github/instructions": true
100 }
101 },
102 "extensions": {
103 "recommendations": [
104 "github.copilot",
105 "github.copilot-chat"
106 ]
107 }
108}
109```
110
111**For local development**, use a relative path instead:
112
113```jsonc
114{
115 "name": "HVE-Core Library",
116 "path": "../../hve-core"
117}
118```
119
120### Step 3: Configure Devcontainer (Codespaces)
121
122Update `.devcontainer/devcontainer.json`:
123
124```jsonc
125{
126 "name": "My Project + HVE-Core",
127 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
128
129 "onCreateCommand": "git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core 2>/dev/null || git -C /workspaces/hve-core pull --ff-only || true",
130
131 "customizations": {
132 "vscode": {
133 "extensions": [
134 "github.copilot",
135 "github.copilot-chat"
136 ]
137 }
138 }
139}
140```
141
142### Step 4: Open the Workspace
143
144**Critical:** You must open the `.code-workspace` file, not the folder.
145
146* **Local:** `File` → `Open Workspace from File...` → select `hve-core.code-workspace`
147* **Codespaces:** Run `code .devcontainer/hve-core.code-workspace` in terminal
148
149The VS Code title bar should show your workspace name, not just the folder name.
150
151## Path Resolution
152
153Multi-root workspaces use folder names for paths:
154
155| Path Style | Example | Recommended |
156|----------------------|-----------------------------------------|-------------------|
157| Folder name relative | `"HVE-Core Library/.github/agents"` | ✅ Yes |
158| Absolute path | `"/workspaces/hve-core/.github/agents"` | ⚠️ Less portable |
159
160The folder names in your `.code-workspace` file (`"name": "HVE-Core Library"`) become path prefixes in settings.
161
162## Keeping HVE-Core Updated
163
164| Strategy | Configuration | When Updates Apply |
165|----------------|-----------------------------------------------------|--------------------|
166| Manual | Run `git -C /workspaces/hve-core pull` when desired | On demand |
167| On rebuild | Add `updateContentCommand` to devcontainer.json | Container rebuild |
168| On every start | Add `postStartCommand` to devcontainer.json | Every startup |
169
170**Recommended:** Update on rebuild for stability:
171
172```jsonc
173{
174 "updateContentCommand": "git -C /workspaces/hve-core pull --ff-only || true"
175}
176```
177
178## Verification
179
180After setup, verify HVE-Core is working:
181
1821. Check the Explorer sidebar shows both folders
1832. Open Copilot Chat (`Ctrl+Alt+I`)
1843. Click the agent picker dropdown
1854. Verify HVE-Core agents appear (task-planner, task-researcher, etc.)
186
187## Troubleshooting
188
189### Agents not appearing
190
191* **Verify workspace is open:** Title bar should show workspace name
192* **Check folder paths:** Ensure `path` values in `.code-workspace` are correct
193* **Reload window:** `Ctrl+Shift+P` → "Developer: Reload Window"
194
195### "Folder not found" error
196
197* **Local:** Verify HVE-Core is cloned at the relative path specified
198* **Codespaces:** Check `onCreateCommand` ran successfully in creation logs
199
200### Settings not applying
201
202* **Settings precedence:** Folder settings override workspace settings
203* **Path format:** Use folder names (`"HVE-Core Library/..."`) not absolute paths
204
205## Next Steps
206
207* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task
208* [RPI Workflow](../../rpi/README.md) - Research, Plan, Implement methodology
209* [Back to Installation Guide](../install.md) - Compare other methods
210
211---
212
213<!-- markdownlint-disable MD036 -->
214*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
215then carefully refined by our team of discerning human reviewers.*
216<!-- markdownlint-enable MD036 -->
217