microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

c330c7aabebb16d36787e09c239c99de34d6cfcb

Find a branch or tag

Branches

c330c7aabebb16d36787e09c239c99de34d6cfcb

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

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

298lines · modecode

Raw Download

Latest commit unavailable.

unknown

1	`---`
2	`title: Multi-Root Workspace Installation`
3	`description: Set up your enterprise fork of HVE Core using VS Code multi-root workspaces`
4	`sidebar_position: 6`
5	`author: Microsoft`
6	`ms.date: 2026-03-10`
7	`ms.topic: how-to`
8	`keywords:`
9	`- multi-root workspace`
10	`- installation`
11	`- github copilot`
12	`- codespaces`
13	`- devcontainer`
14	`- enterprise fork`
15	`estimated_reading_time: 8`
16	`---`
17
18	`Forking HVE Core lets your enterprise customize agents, prompts, instructions, and skills for your organization while staying connected to upstream improvements. Multi-root workspaces bring that fork into any project workspace, giving teams a portable configuration that works across Local VS Code, Devcontainers, and Codespaces.`
19
20	`## When to Use This Method`
21
22	`✅ Use this when:`
23
24	`* Your enterprise maintains a fork of HVE Core with org-specific customizations`
25	`* You need a single configuration that works across Local VS Code, Devcontainers, and Codespaces`
26	`* Teams share a common set of customized agents, prompts, and instructions`
27	`* You want to pull upstream improvements on your own schedule`
28
29	`❌ Consider alternatives when:`
30
31	`* Your team needs version-pinned dependencies without a fork → [Submodule](submodule.md)`
32	`* You're contributing back to HVE Core itself → [Peer Clone](peer-clone.md)`
33
34	`## How It Works`
35
36	Your enterprise forks the `microsoft/hve-core` repository, adds org-specific agents, prompts, and instructions, then uses a `.code-workspace` file to bring that fork into any project as a secondary root. VS Code treats the fork as part of your project, making all paths work correctly.
37
38	```text
39	`┌──────────────────────────────────────────────────┐`
40	`│ VS Code Multi-Root Workspace │`
41	`├──────────────────────────────────────────────────┤`
42	`│ 📁 My Project (primary) │`
43	`│ └── Your application code │`
44	`│ 📁 HVE Core Fork (secondary) │`
45	`│ └── .github/agents, prompts, instructions │`
46	`│ └── Org-specific customizations │`
47	`└──────────────────────────────────────────────────┘`
48	`↑`
49	`.code-workspace file defines this`
50
51	`microsoft/hve-core (upstream)`
52	`↓ sync on your schedule`
53	`your-org/hve-core (fork)`
54	```
55
56	`## Quick Start`
57
58	`Install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) for the fastest setup. For guided setup with installation method selection and MCP configuration, install the [HVE Core Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer) extension and ask any agent "help me customize hve-core installation". Use the manual steps below for direct configuration.`
59
60	`## Manual Setup`
61
62	`### Step 1: Fork and Clone`
63
64	If your organization has not already forked HVE Core, create a fork of `microsoft/hve-core` under your org's GitHub account. Then clone your fork.
65
66	`#### Local VS Code`
67
68	```bash
69	`# Clone your org's fork next to your project`
70	`cd /path/to/your-projects`
71	`git clone https://github.com/your-org/hve-core.git`
72
73	`# Add upstream for syncing improvements`
74	`cd hve-core`
75	`git remote add upstream https://github.com/microsoft/hve-core.git`
76	```
77
78	`Codespaces/Devcontainer: Your fork will be cloned automatically (see Step 3).`
79
80	`### Step 2: Create the Workspace File`
81
82	Create `.devcontainer/hve-core.code-workspace` in your project:
83
84	`> [!IMPORTANT]`
85	> Use the actual clone path (not the folder display name) as the prefix in `chat.*Locations` settings.
86	`> Folder display names do not resolve reliably as path prefixes.`
87
88	`#### Codespaces / Devcontainer`
89
90	`Use the absolute clone path:`
91
92	```jsonc
93	`{`
94	`"folders": [`
95	`{`
96	`"name": "My Project",`
97	`"path": ".."`
98	`},`
99	`{`
100	`"name": "HVE Core Fork",`
101	`"path": "/workspaces/hve-core"`
102	`}`
103	`],`
104	`"settings": {`
105	`"chat.agentFilesLocations": {`
106	`"/workspaces/hve-core/.github/agents/ado": true,`
107	`"/workspaces/hve-core/.github/agents/data-science": true,`
108	`"/workspaces/hve-core/.github/agents/design-thinking": true,`
109	`"/workspaces/hve-core/.github/agents/github": true,`
110	`"/workspaces/hve-core/.github/agents/project-planning": true,`
111	`"/workspaces/hve-core/.github/agents/hve-core": true,`
112	`"/workspaces/hve-core/.github/agents/hve-core/subagents": true,`
113	`"/workspaces/hve-core/.github/agents/security": true,`
114	`"My Project/.github/agents": true`
115	`},`
116	`"chat.promptFilesLocations": {`
117	`"/workspaces/hve-core/.github/prompts/ado": true,`
118	`"/workspaces/hve-core/.github/prompts/design-thinking": true,`
119	`"/workspaces/hve-core/.github/prompts/github": true,`
120	`"/workspaces/hve-core/.github/prompts/hve-core": true,`
121	`"/workspaces/hve-core/.github/prompts/security": true,`
122	`"My Project/.github/prompts": true`
123	`},`
124	`"chat.instructionsFilesLocations": {`
125	`"/workspaces/hve-core/.github/instructions/ado": true,`
126	`"/workspaces/hve-core/.github/instructions/coding-standards": true,`
127	`"/workspaces/hve-core/.github/instructions/design-thinking": true,`
128	`"/workspaces/hve-core/.github/instructions/github": true,`
129	`"/workspaces/hve-core/.github/instructions/hve-core": true,`
130	`"/workspaces/hve-core/.github/instructions/shared": true,`
131	`"My Project/.github/instructions": true`
132	`},`
133	`"chat.agentSkillsLocations": {`
134	`"/workspaces/hve-core/.github/skills": true,`
135	`"/workspaces/hve-core/.github/skills/shared": true,`
136	`"/workspaces/hve-core/.github/skills/coding-standards": true,`
137	`"My Project/.github/skills": true`
138	`}`
139	`},`
140	`"extensions": {`
141	`"recommendations": [`
142	`"github.copilot",`
143	`"github.copilot-chat"`
144	`]`
145	`}`
146	`}`
147	```
148
149	`#### Local VS Code`
150
151	`Use the relative clone path from the workspace file's directory:`
152
153	```jsonc
154	`{`
155	`"folders": [`
156	`{`
157	`"name": "My Project",`
158	`"path": ".."`
159	`},`
160	`{`
161	`"name": "HVE Core Fork",`
162	`"path": "../../hve-core"`
163	`}`
164	`],`
165	`"settings": {`
166	`"chat.agentFilesLocations": {`
167	`"../../hve-core/.github/agents/ado": true,`
168	`"../../hve-core/.github/agents/data-science": true,`
169	`"../../hve-core/.github/agents/hve-core": true,`
170	`"../../hve-core/.github/agents/hve-core/subagents": true`
171	`},`
172	`"chat.instructionsFilesLocations": {`
173	`"../../hve-core/.github/instructions/hve-core": true,`
174	`"../../hve-core/.github/instructions/shared": true`
175	`}`
176	`}`
177	`}`
178	```
179
180	`Adjust the relative path to match your clone location.`
181
182	`### Step 3: Configure Devcontainer (Codespaces)`
183
184	Update `.devcontainer/devcontainer.json` to clone your org's fork:
185
186	```jsonc
187	`{`
188	`"name": "My Project + HVE Core",`
189	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
190
191	`"onCreateCommand": "git clone --depth 1 https://github.com/your-org/hve-core.git /workspaces/hve-core 2>/dev/null \|\| git -C /workspaces/hve-core pull --ff-only \|\| true",`
192
193	`"customizations": {`
194	`"vscode": {`
195	`"extensions": [`
196	`"github.copilot",`
197	`"github.copilot-chat"`
198	`]`
199	`}`
200	`}`
201	`}`
202	```
203
204	`### Step 4: Open the Workspace`
205
206	`> [!WARNING]`
207	> You must open the `.code-workspace` file, not the folder.
208
209	* `File` → `Open Workspace from File...` → select `hve-core.code-workspace` (Local)
210	* Run `code .devcontainer/hve-core.code-workspace` in terminal (Codespaces)
211
212	`> [!NOTE]`
213	> The dev container spec has no `workspaceFile` property, so Codespaces and devcontainers always open in single-folder mode. You must manually switch to the workspace file after the container starts. For Codespaces without a fork, the [Codespaces method](codespaces.md) avoids this extra step by configuring settings directly in `devcontainer.json`.
214
215	`The VS Code title bar should show your workspace name, not just the folder name.`
216
217	`## Path Resolution`
218
219	Use the actual clone path as the prefix in `chat.*Locations` settings:
220
221	`\| Path Style \| Example \| Recommended \|`
222	`\|---------------\|-----------------------------------------\|--------------\|`
223	\| Absolute path \| `"/workspaces/hve-core/.github/agents"` \| ✅ Codespaces \|
224	\| Relative path \| `"../../hve-core/.github/agents"` \| ✅ Local \|
225	\| Folder name \| `"HVE Core Fork/.github/agents"` \| ❌ Unreliable \|
226
227	Folder display names (`"name"` field) label roots in the Explorer sidebar but do not resolve reliably as path prefixes in `chat.*Locations` settings. Always use the filesystem path from the folder's `"path"` field instead.
228
229	`## Keeping Your Fork Updated`
230
231	Sync your fork with upstream `microsoft/hve-core` to pick up new agents, prompts, and improvements. Pull from your fork into workspaces on a schedule that suits your team.
232
233	`### Syncing Upstream Changes into Your Fork`
234
235	```bash
236	`# From your fork's local clone`
237	`git fetch upstream`
238	`git merge upstream/main`
239	`# Resolve any conflicts with your org customizations, then push`
240	`git push origin main`
241	```
242
243	`### Pulling Fork Updates into Workspaces`
244
245	`\| Strategy \| Configuration \| When Updates Apply \|`
246	`\|----------------\|-----------------------------------------------------\|--------------------\|`
247	\| Manual \| Run `git -C /workspaces/hve-core pull` when desired \| On demand \|
248	\| On rebuild \| Add `updateContentCommand` to devcontainer.json \| Container rebuild \|
249	\| On every start \| Add `postStartCommand` to devcontainer.json \| Every startup \|
250
251	`> [!TIP]`
252	`> Update on rebuild for stability:`
253
254	```jsonc
255	`{`
256	`"updateContentCommand": "git -C /workspaces/hve-core pull --ff-only \|\| true"`
257	`}`
258	```
259
260	`## Verification`
261
262	`After setup, verify HVE Core is working:`
263
264	`1. Check the Explorer sidebar shows both folders`
265	2. Open Copilot Chat (`Ctrl+Alt+I`)
266	`3. Click the agent picker dropdown`
267	`4. Verify HVE Core agents appear (task-planner, task-researcher, etc.)`
268
269	`## Troubleshooting`
270
271	`### Agents not appearing`
272
273	`* Confirm the workspace is open by checking that the title bar shows the workspace name`
274	* Ensure `path` values in `.code-workspace` point to the correct locations
275	* Reload the window with `Ctrl+Shift+P` → "Developer: Reload Window"
276
277	`### "Folder not found" error`
278
279	`* For local setups, verify HVE Core is cloned at the relative path specified`
280	* For Codespaces, check that `onCreateCommand` ran successfully in creation logs
281
282	`### Settings not applying`
283
284	`* Folder settings override workspace settings, so check for conflicts at the folder level`
285	* Use the actual clone path (absolute or relative) in `chat.*Locations` settings, not folder display names
286
287	`## Next Steps`
288
289	`* [Your First Workflow](../first-workflow.md) - Try HVE Core with a real task`
290	`* [RPI Workflow](../../rpi/) - Research, Plan, Implement methodology`
291	`* [Back to Installation Guide](../install.md) - Compare other methods`
292
293	`---`
294
295	`<!-- markdownlint-disable MD036 -->`
296	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
297	`then carefully refined by our team of discerning human reviewers.*`
298	`<!-- markdownlint-enable MD036 -->`
299

microsoft/hve-core

Branches

Tags

Clone