microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

1a96b7384cd85a53b6036e7275d391fcb75cd11d

Find a branch or tag

Branches

1a96b7384cd85a53b6036e7275d391fcb75cd11d

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

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

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

microsoft/hve-core

Branches

Tags

Clone