microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v3.3.10

Find a branch or tag

Branches

hve-core-v3.3.10

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

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

297lines · 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	`"My Project/.github/skills": true`
137	`}`
138	`},`
139	`"extensions": {`
140	`"recommendations": [`
141	`"github.copilot",`
142	`"github.copilot-chat"`
143	`]`
144	`}`
145	`}`
146	```
147
148	`#### Local VS Code`
149
150	`Use the relative clone path from the workspace file's directory:`
151
152	```jsonc
153	`{`
154	`"folders": [`
155	`{`
156	`"name": "My Project",`
157	`"path": ".."`
158	`},`
159	`{`
160	`"name": "HVE Core Fork",`
161	`"path": "../../hve-core"`
162	`}`
163	`],`
164	`"settings": {`
165	`"chat.agentFilesLocations": {`
166	`"../../hve-core/.github/agents/ado": true,`
167	`"../../hve-core/.github/agents/data-science": true,`
168	`"../../hve-core/.github/agents/hve-core": true,`
169	`"../../hve-core/.github/agents/hve-core/subagents": true`
170	`},`
171	`"chat.instructionsFilesLocations": {`
172	`"../../hve-core/.github/instructions/hve-core": true,`
173	`"../../hve-core/.github/instructions/shared": true`
174	`}`
175	`}`
176	`}`
177	```
178
179	`Adjust the relative path to match your clone location.`
180
181	`### Step 3: Configure Devcontainer (Codespaces)`
182
183	Update `.devcontainer/devcontainer.json` to clone your org's fork:
184
185	```jsonc
186	`{`
187	`"name": "My Project + HVE Core",`
188	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
189
190	`"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",`
191
192	`"customizations": {`
193	`"vscode": {`
194	`"extensions": [`
195	`"github.copilot",`
196	`"github.copilot-chat"`
197	`]`
198	`}`
199	`}`
200	`}`
201	```
202
203	`### Step 4: Open the Workspace`
204
205	`> [!WARNING]`
206	> You must open the `.code-workspace` file, not the folder.
207
208	* `File` → `Open Workspace from File...` → select `hve-core.code-workspace` (Local)
209	* Run `code .devcontainer/hve-core.code-workspace` in terminal (Codespaces)
210
211	`> [!NOTE]`
212	> 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`.
213
214	`The VS Code title bar should show your workspace name, not just the folder name.`
215
216	`## Path Resolution`
217
218	Use the actual clone path as the prefix in `chat.*Locations` settings:
219
220	`\| Path Style \| Example \| Recommended \|`
221	`\|---------------\|-----------------------------------------\|--------------\|`
222	\| Absolute path \| `"/workspaces/hve-core/.github/agents"` \| ✅ Codespaces \|
223	\| Relative path \| `"../../hve-core/.github/agents"` \| ✅ Local \|
224	\| Folder name \| `"HVE Core Fork/.github/agents"` \| ❌ Unreliable \|
225
226	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.
227
228	`## Keeping Your Fork Updated`
229
230	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.
231
232	`### Syncing Upstream Changes into Your Fork`
233
234	```bash
235	`# From your fork's local clone`
236	`git fetch upstream`
237	`git merge upstream/main`
238	`# Resolve any conflicts with your org customizations, then push`
239	`git push origin main`
240	```
241
242	`### Pulling Fork Updates into Workspaces`
243
244	`\| Strategy \| Configuration \| When Updates Apply \|`
245	`\|----------------\|-----------------------------------------------------\|--------------------\|`
246	\| Manual \| Run `git -C /workspaces/hve-core pull` when desired \| On demand \|
247	\| On rebuild \| Add `updateContentCommand` to devcontainer.json \| Container rebuild \|
248	\| On every start \| Add `postStartCommand` to devcontainer.json \| Every startup \|
249
250	`> [!TIP]`
251	`> Update on rebuild for stability:`
252
253	```jsonc
254	`{`
255	`"updateContentCommand": "git -C /workspaces/hve-core pull --ff-only \|\| true"`
256	`}`
257	```
258
259	`## Verification`
260
261	`After setup, verify HVE Core is working:`
262
263	`1. Check the Explorer sidebar shows both folders`
264	2. Open Copilot Chat (`Ctrl+Alt+I`)
265	`3. Click the agent picker dropdown`
266	`4. Verify HVE Core agents appear (task-planner, task-researcher, etc.)`
267
268	`## Troubleshooting`
269
270	`### Agents not appearing`
271
272	`* Confirm the workspace is open by checking that the title bar shows the workspace name`
273	* Ensure `path` values in `.code-workspace` point to the correct locations
274	* Reload the window with `Ctrl+Shift+P` → "Developer: Reload Window"
275
276	`### "Folder not found" error`
277
278	`* For local setups, verify HVE Core is cloned at the relative path specified`
279	* For Codespaces, check that `onCreateCommand` ran successfully in creation logs
280
281	`### Settings not applying`
282
283	`* Folder settings override workspace settings, so check for conflicts at the folder level`
284	* Use the actual clone path (absolute or relative) in `chat.*Locations` settings, not folder display names
285
286	`## Next Steps`
287
288	`* [Your First Workflow](../first-workflow.md) - Try HVE Core with a real task`
289	`* [RPI Workflow](../../rpi/) - Research, Plan, Implement methodology`
290	`* [Back to Installation Guide](../install.md) - Compare other methods`
291
292	`---`
293
294	`<!-- markdownlint-disable MD036 -->`
295	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
296	`then carefully refined by our team of discerning human reviewers.*`
297	`<!-- markdownlint-enable MD036 -->`
298

microsoft/hve-core

Branches

Tags

Clone