microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

3a3a0fdf923d96a9e8a9ac734c73f24433b525e8

Find a branch or tag

Branches

3a3a0fdf923d96a9e8a9ac734c73f24433b525e8

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

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

261lines · 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	```jsonc
85	`{`
86	`"folders": [`
87	`{`
88	`"name": "My Project",`
89	`"path": ".."`
90	`},`
91	`{`
92	`"name": "HVE-Core Fork",`
93	`"path": "/workspaces/hve-core"`
94	`}`
95	`],`
96	`"settings": {`
97	`"chat.agentFilesLocations": {`
98	`"HVE-Core Fork/.github/agents/ado": true,`
99	`"HVE-Core Fork/.github/agents/data-science": true,`
100	`"HVE-Core Fork/.github/agents/design-thinking": true,`
101	`"HVE-Core Fork/.github/agents/github": true,`
102	`"HVE-Core Fork/.github/agents/project-planning": true,`
103	`"HVE-Core Fork/.github/agents/hve-core": true,`
104	`"HVE-Core Fork/.github/agents/hve-core/subagents": true,`
105	`"HVE-Core Fork/.github/agents/security": true,`
106	`"My Project/.github/agents": true`
107	`},`
108	`"chat.promptFilesLocations": {`
109	`"HVE-Core Fork/.github/prompts/ado": true,`
110	`"HVE-Core Fork/.github/prompts/design-thinking": true,`
111	`"HVE-Core Fork/.github/prompts/github": true,`
112	`"HVE-Core Fork/.github/prompts/hve-core": true,`
113	`"HVE-Core Fork/.github/prompts/security": true,`
114	`"My Project/.github/prompts": true`
115	`},`
116	`"chat.instructionsFilesLocations": {`
117	`"HVE-Core Fork/.github/instructions/ado": true,`
118	`"HVE-Core Fork/.github/instructions/coding-standards": true,`
119	`"HVE-Core Fork/.github/instructions/design-thinking": true,`
120	`"HVE-Core Fork/.github/instructions/github": true,`
121	`"HVE-Core Fork/.github/instructions/hve-core": true,`
122	`"HVE-Core Fork/.github/instructions/shared": true,`
123	`"My Project/.github/instructions": true`
124	`},`
125	`"chat.agentSkillsLocations": {`
126	`"HVE-Core Fork/.github/skills": true,`
127	`"HVE-Core Fork/.github/skills/shared": true,`
128	`"My Project/.github/skills": true`
129	`}`
130	`},`
131	`"extensions": {`
132	`"recommendations": [`
133	`"github.copilot",`
134	`"github.copilot-chat"`
135	`]`
136	`}`
137	`}`
138	```
139
140	`For local development, use a relative path instead:`
141
142	```jsonc
143	`{`
144	`"name": "HVE-Core Fork",`
145	`"path": "../../hve-core"`
146	`}`
147	```
148
149	`### Step 3: Configure Devcontainer (Codespaces)`
150
151	Update `.devcontainer/devcontainer.json` to clone your org's fork:
152
153	```jsonc
154	`{`
155	`"name": "My Project + HVE-Core",`
156	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
157
158	`"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",`
159
160	`"customizations": {`
161	`"vscode": {`
162	`"extensions": [`
163	`"github.copilot",`
164	`"github.copilot-chat"`
165	`]`
166	`}`
167	`}`
168	`}`
169	```
170
171	`### Step 4: Open the Workspace`
172
173	`> [!WARNING]`
174	> You must open the `.code-workspace` file, not the folder.
175
176	* `File` → `Open Workspace from File...` → select `hve-core.code-workspace` (Local)
177	* Run `code .devcontainer/hve-core.code-workspace` in terminal (Codespaces)
178
179	`The VS Code title bar should show your workspace name, not just the folder name.`
180
181	`## Path Resolution`
182
183	`Multi-root workspaces use folder names for paths:`
184
185	`\| Path Style \| Example \| Recommended \|`
186	`\|----------------------\|-----------------------------------------\|-------------------\|`
187	\| Folder name relative \| `"HVE-Core Fork/.github/agents"` \| ✅ Yes \|
188	\| Absolute path \| `"/workspaces/hve-core/.github/agents"` \| ⚠️ Less portable \|
189
190	The folder names in your `.code-workspace` file (`"name": "HVE-Core Fork"`) become path prefixes in settings.
191
192	`## Keeping Your Fork Updated`
193
194	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.
195
196	`### Syncing Upstream Changes into Your Fork`
197
198	```bash
199	`# From your fork's local clone`
200	`git fetch upstream`
201	`git merge upstream/main`
202	`# Resolve any conflicts with your org customizations, then push`
203	`git push origin main`
204	```
205
206	`### Pulling Fork Updates into Workspaces`
207
208	`\| Strategy \| Configuration \| When Updates Apply \|`
209	`\|----------------\|-----------------------------------------------------\|--------------------\|`
210	\| Manual \| Run `git -C /workspaces/hve-core pull` when desired \| On demand \|
211	\| On rebuild \| Add `updateContentCommand` to devcontainer.json \| Container rebuild \|
212	\| On every start \| Add `postStartCommand` to devcontainer.json \| Every startup \|
213
214	`> [!TIP]`
215	`> Update on rebuild for stability:`
216
217	```jsonc
218	`{`
219	`"updateContentCommand": "git -C /workspaces/hve-core pull --ff-only \|\| true"`
220	`}`
221	```
222
223	`## Verification`
224
225	`After setup, verify HVE-Core is working:`
226
227	`1. Check the Explorer sidebar shows both folders`
228	2. Open Copilot Chat (`Ctrl+Alt+I`)
229	`3. Click the agent picker dropdown`
230	`4. Verify HVE-Core agents appear (task-planner, task-researcher, etc.)`
231
232	`## Troubleshooting`
233
234	`### Agents not appearing`
235
236	`* Confirm the workspace is open by checking that the title bar shows the workspace name`
237	* Ensure `path` values in `.code-workspace` point to the correct locations
238	* Reload the window with `Ctrl+Shift+P` → "Developer: Reload Window"
239
240	`### "Folder not found" error`
241
242	`* For local setups, verify HVE-Core is cloned at the relative path specified`
243	* For Codespaces, check that `onCreateCommand` ran successfully in creation logs
244
245	`### Settings not applying`
246
247	`* Folder settings override workspace settings, so check for conflicts at the folder level`
248	* Use folder names (`"HVE-Core Fork/..."`) instead of absolute paths
249
250	`## Next Steps`
251
252	`* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task`
253	`* [RPI Workflow](../../rpi/) - Research, Plan, Implement methodology`
254	`* [Back to Installation Guide](../install.md) - Compare other methods`
255
256	`---`
257
258	`<!-- markdownlint-disable MD036 -->`
259	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
260	`then carefully refined by our team of discerning human reviewers.*`
261	`<!-- markdownlint-enable MD036 -->`
262

microsoft/hve-core

Branches

Tags

Clone