microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

dabed001c8ac7da3f2e4368ae1f279080c627cbd

Find a branch or tag

Branches

dabed001c8ac7da3f2e4368ae1f279080c627cbd

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/codespaces.md

444lines · modecode

Raw Download

Latest commit unavailable.

unknown

1	`---`
2	`title: GitHub Codespaces Installation`
3	`description: Install HVE-Core in GitHub Codespaces using postCreateCommand`
4	`author: Microsoft`
5	`ms.date: 2025-12-03`
6	`ms.topic: how-to`
7	`keywords:`
8	`- codespaces`
9	`- installation`
10	`- github copilot`
11	`- postCreateCommand`
12	`- cloud development`
13	`estimated_reading_time: 7`
14	`---`
15
16	GitHub Codespaces requires a specific installation approach because traditional methods (peer directories, bind mounts) don't work in cloud environments. This method uses `postCreateCommand` to clone HVE-Core into the persistent `/workspaces` directory.
17
18	`## When to Use This Method`
19
20	`✅ Use this when:`
21
22	`* Your project runs exclusively in Codespaces`
23	`* You want automatic HVE-Core setup for all users`
24	`* You need zero-config onboarding for contributors`
25
26	`❌ Consider alternatives when:`
27
28	`* You also need local devcontainer support → [Multi-Root Workspace](multi-root.md)`
29	`* Your team needs version control → [Submodule](submodule.md)`
30	`* You're using local VS Code only → [Peer Clone](peer-clone.md)`
31
32	`## Why Other Methods Don't Work in Codespaces`
33
34	`\| Feature \| Local Devcontainer \| GitHub Codespaces \|`
35	`\|----------------------------\|--------------------\|------------------------------\|`
36	\| `${localWorkspaceFolder}` \| ✅ Resolves to host \| ❌ Not available \|
37	`\| Bind mounts to host \| ✅ Full support \| ❌ No host access \|`
38	\| Persistent storage \| Host filesystem \| `/workspaces` only \|
39	`\| User settings modification \| ✅ Via file system \| ❌ Only via Settings Sync[^1] \|`
40
41	[^1]: User-level settings require Settings Sync. Workspace/container-level settings can still be configured via `devcontainer.json` using `customizations.vscode.settings`.
42
43	`## How It Works`
44
45	`Codespaces has a specific storage model:`
46
47	```text
48	`/`
49	`├── workspaces/ # ✅ PERSISTENT - survives stops/restarts`
50	`│ ├── your-repo/ # Your cloned repository`
51	`│ └── hve-core/ # 👈 HVE-Core goes here`
52	`├── home/codespace/ # ⚠️ Semi-persistent (survives stops, not rebuilds)`
53	`└── <system-dirs>/ # ❌ Not persistent`
54	```
55
56	The `postCreateCommand` clones HVE-Core into `/workspaces/hve-core` where it persists across Codespace sessions.
57
58	`## Quick Start`
59
60	Use the `hve-core-installer` agent:
61
62	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
63	2. Select `hve-core-installer` from the agent picker
64	`3. Say: "Install HVE-Core for Codespaces"`
65	`4. Follow the guided setup`
66
67	`## Manual Setup`
68
69	`### Step 1: Update devcontainer.json`
70
71	`Add the clone command and VS Code settings:`
72
73	```jsonc
74	`{`
75	`"name": "My Project with HVE-Core",`
76	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
77
78	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
79
80	`"customizations": {`
81	`"vscode": {`
82	`"settings": {`
83	`"chat.agentFilesLocations": {`
84	`"/workspaces/hve-core/.github/agents/ado": true,`
85	`"/workspaces/hve-core/.github/agents/data-science": true,`
86	`"/workspaces/hve-core/.github/agents/design-thinking": true,`
87	`"/workspaces/hve-core/.github/agents/github": true,`
88	`"/workspaces/hve-core/.github/agents/installer": true,`
89	`"/workspaces/hve-core/.github/agents/project-planning": true,`
90	`"/workspaces/hve-core/.github/agents/hve-core": true,`
91	`"/workspaces/hve-core/.github/agents/hve-core/subagents": true,`
92	`"/workspaces/hve-core/.github/agents/security-planning": true`
93	`},`
94	`"chat.promptFilesLocations": {`
95	`"/workspaces/hve-core/.github/prompts/ado": true,`
96	`"/workspaces/hve-core/.github/prompts/design-thinking": true,`
97	`"/workspaces/hve-core/.github/prompts/github": true,`
98	`"/workspaces/hve-core/.github/prompts/hve-core": true,`
99	`"/workspaces/hve-core/.github/prompts/security-planning": true`
100	`},`
101	`"chat.instructionsFilesLocations": {`
102	`"/workspaces/hve-core/.github/instructions/ado": true,`
103	`"/workspaces/hve-core/.github/instructions/coding-standards": true,`
104	`"/workspaces/hve-core/.github/instructions/design-thinking": true,`
105	`"/workspaces/hve-core/.github/instructions/github": true,`
106	`"/workspaces/hve-core/.github/instructions/hve-core": true,`
107	`"/workspaces/hve-core/.github/instructions/shared": true`
108	`},`
109	`"chat.agentSkillsLocations": {`
110	`"/workspaces/hve-core/.github/skills": true,`
111	`"/workspaces/hve-core/.github/skills/shared": true`
112	`}`
113	`}`
114	`}`
115	`}`
116	`}`
117	```
118
119	`### Step 2: Commit and Push`
120
121	```bash
122	`git add .devcontainer/devcontainer.json`
123	`git commit -m "feat: add HVE-Core support for Codespaces"`
124	`git push`
125	```
126
127	`### Step 3: Create or Rebuild Codespace`
128
129	`* New Codespace: Create from the updated branch`
130	* Existing Codespace: Rebuild (`Ctrl+Shift+P` → "Codespaces: Rebuild Container")
131
132	`### Step 4: Validate Installation`
133
134	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
135	`2. Click the agent picker dropdown`
136	`3. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder)`
137
138	`## Complete Configuration Examples`
139
140	`### Minimal Configuration`
141
142	```jsonc
143	`{`
144	`"name": "HVE-Core Enabled",`
145	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
146
147	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
148
149	`"customizations": {`
150	`"vscode": {`
151	`"settings": {`
152	`"chat.agentFilesLocations": {`
153	`"/workspaces/hve-core/.github/agents/ado": true,`
154	`"/workspaces/hve-core/.github/agents/data-science": true,`
155	`"/workspaces/hve-core/.github/agents/design-thinking": true,`
156	`"/workspaces/hve-core/.github/agents/github": true,`
157	`"/workspaces/hve-core/.github/agents/installer": true,`
158	`"/workspaces/hve-core/.github/agents/project-planning": true,`
159	`"/workspaces/hve-core/.github/agents/hve-core": true,`
160	`"/workspaces/hve-core/.github/agents/hve-core/subagents": true,`
161	`"/workspaces/hve-core/.github/agents/security-planning": true`
162	`},`
163	`"chat.promptFilesLocations": {`
164	`"/workspaces/hve-core/.github/prompts/ado": true,`
165	`"/workspaces/hve-core/.github/prompts/design-thinking": true,`
166	`"/workspaces/hve-core/.github/prompts/github": true,`
167	`"/workspaces/hve-core/.github/prompts/hve-core": true,`
168	`"/workspaces/hve-core/.github/prompts/security-planning": true`
169	`},`
170	`"chat.instructionsFilesLocations": {`
171	`"/workspaces/hve-core/.github/instructions/ado": true,`
172	`"/workspaces/hve-core/.github/instructions/coding-standards": true,`
173	`"/workspaces/hve-core/.github/instructions/design-thinking": true,`
174	`"/workspaces/hve-core/.github/instructions/github": true,`
175	`"/workspaces/hve-core/.github/instructions/hve-core": true,`
176	`"/workspaces/hve-core/.github/instructions/shared": true`
177	`},`
178	`"chat.agentSkillsLocations": {`
179	`"/workspaces/hve-core/.github/skills": true,`
180	`"/workspaces/hve-core/.github/skills/shared": true`
181	`}`
182	`}`
183	`}`
184	`}`
185	`}`
186	```
187
188	`### Full-Featured Configuration`
189
190	```jsonc
191	`{`
192	`"name": "HVE-Core Development Environment",`
193	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
194
195	`"features": {`
196	`"ghcr.io/devcontainers/features/git:1": {},`
197	`"ghcr.io/devcontainers/features/github-cli:1": {}`
198	`},`
199
200	`"postCreateCommand": {`
201	`"clone-hve-core": "if [ ! -d /workspaces/hve-core ]; then git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core && echo '✅ HVE-Core cloned'; else echo '✅ HVE-Core present'; fi",`
202	`"verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' \|\| echo '⚠️ Missing'"`
203	`},`
204
205	`"updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null \|\| echo 'Update skipped'",`
206
207	`"customizations": {`
208	`"vscode": {`
209	`"settings": {`
210	`"chat.promptFilesLocations": {`
211	`"/workspaces/hve-core/.github/prompts/ado": true,`
212	`"/workspaces/hve-core/.github/prompts/design-thinking": true,`
213	`"/workspaces/hve-core/.github/prompts/github": true,`
214	`"/workspaces/hve-core/.github/prompts/hve-core": true,`
215	`"/workspaces/hve-core/.github/prompts/security-planning": true,`
216	`".github/prompts": true`
217	`},`
218	`"chat.instructionsFilesLocations": {`
219	`"/workspaces/hve-core/.github/instructions/ado": true,`
220	`"/workspaces/hve-core/.github/instructions/coding-standards": true,`
221	`"/workspaces/hve-core/.github/instructions/design-thinking": true,`
222	`"/workspaces/hve-core/.github/instructions/github": true,`
223	`"/workspaces/hve-core/.github/instructions/hve-core": true,`
224	`"/workspaces/hve-core/.github/instructions/shared": true,`
225	`".github/instructions": true`
226	`},`
227	`"chat.agentFilesLocations": {`
228	`"/workspaces/hve-core/.github/agents/ado": true,`
229	`"/workspaces/hve-core/.github/agents/data-science": true,`
230	`"/workspaces/hve-core/.github/agents/design-thinking": true,`
231	`"/workspaces/hve-core/.github/agents/github": true,`
232	`"/workspaces/hve-core/.github/agents/installer": true,`
233	`"/workspaces/hve-core/.github/agents/project-planning": true,`
234	`"/workspaces/hve-core/.github/agents/hve-core": true,`
235	`"/workspaces/hve-core/.github/agents/hve-core/subagents": true,`
236	`"/workspaces/hve-core/.github/agents/security-planning": true,`
237	`".github/agents": true`
238	`},`
239	`"chat.agentSkillsLocations": {`
240	`"/workspaces/hve-core/.github/skills": true,`
241	`"/workspaces/hve-core/.github/skills/shared": true,`
242	`".github/skills": true`
243	`}`
244	`}`
245	`}`
246	`}`
247	`}`
248	```
249
250	`### Dual-Environment (Local + Codespaces)`
251
252	`For projects needing HVE-Core in both local devcontainers and Codespaces:`
253
254	```jsonc
255	`{`
256	`"name": "HVE-Core (Local + Codespaces)",`
257	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
258
259	`// Clone if not already present (Codespaces path)`
260	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
261
262	`// Local only: mount peer directory (silently fails in Codespaces)`
263	`"mounts": [`
264	`"source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"`
265	`],`
266
267	`"customizations": {`
268	`"vscode": {`
269	`"settings": {`
270	`// Both paths - VS Code ignores non-existent paths`
271	`"chat.promptFilesLocations": {`
272	`"/workspaces/hve-core/.github/prompts/ado": true,`
273	`"/workspaces/hve-core/.github/prompts/design-thinking": true,`
274	`"/workspaces/hve-core/.github/prompts/github": true,`
275	`"/workspaces/hve-core/.github/prompts/hve-core": true,`
276	`"/workspaces/hve-core/.github/prompts/security-planning": true,`
277	`"../hve-core/.github/prompts/ado": true,`
278	`"../hve-core/.github/prompts/design-thinking": true,`
279	`"../hve-core/.github/prompts/github": true,`
280	`"../hve-core/.github/prompts/hve-core": true,`
281	`"../hve-core/.github/prompts/security-planning": true`
282	`},`
283	`"chat.instructionsFilesLocations": {`
284	`"/workspaces/hve-core/.github/instructions/ado": true,`
285	`"/workspaces/hve-core/.github/instructions/coding-standards": true,`
286	`"/workspaces/hve-core/.github/instructions/design-thinking": true,`
287	`"/workspaces/hve-core/.github/instructions/github": true,`
288	`"/workspaces/hve-core/.github/instructions/hve-core": true,`
289	`"/workspaces/hve-core/.github/instructions/shared": true,`
290	`"../hve-core/.github/instructions/ado": true,`
291	`"../hve-core/.github/instructions/coding-standards": true,`
292	`"../hve-core/.github/instructions/design-thinking": true,`
293	`"../hve-core/.github/instructions/github": true,`
294	`"../hve-core/.github/instructions/hve-core": true,`
295	`"../hve-core/.github/instructions/shared": true`
296	`},`
297	`"chat.agentFilesLocations": {`
298	`"/workspaces/hve-core/.github/agents/ado": true,`
299	`"/workspaces/hve-core/.github/agents/data-science": true,`
300	`"/workspaces/hve-core/.github/agents/design-thinking": true,`
301	`"/workspaces/hve-core/.github/agents/github": true,`
302	`"/workspaces/hve-core/.github/agents/installer": true,`
303	`"/workspaces/hve-core/.github/agents/project-planning": true,`
304	`"/workspaces/hve-core/.github/agents/hve-core": true,`
305	`"/workspaces/hve-core/.github/agents/hve-core/subagents": true,`
306	`"/workspaces/hve-core/.github/agents/security-planning": true,`
307	`"../hve-core/.github/agents/ado": true,`
308	`"../hve-core/.github/agents/data-science": true,`
309	`"../hve-core/.github/agents/design-thinking": true,`
310	`"../hve-core/.github/agents/github": true,`
311	`"../hve-core/.github/agents/installer": true,`
312	`"../hve-core/.github/agents/project-planning": true,`
313	`"../hve-core/.github/agents/hve-core": true,`
314	`"../hve-core/.github/agents/hve-core/subagents": true,`
315	`"../hve-core/.github/agents/security-planning": true`
316	`},`
317	`"chat.agentSkillsLocations": {`
318	`"/workspaces/hve-core/.github/skills": true,`
319	`"/workspaces/hve-core/.github/skills/shared": true,`
320	`"../hve-core/.github/skills": true,`
321	`"../hve-core/.github/skills/shared": true`
322	`}`
323	`}`
324	`}`
325	`}`
326	`}`
327	```
328
329	`## Updating HVE-Core`
330
331	`### Manual Update`
332
333	```bash
334	`cd /workspaces/hve-core`
335	`git pull`
336	```
337
338	`### Auto-Update on Codespace Start`
339
340	Add `updateContentCommand` to your devcontainer.json:
341
342	```jsonc
343	`{`
344	`"updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null \|\| true"`
345	`}`
346	```
347
348	`This runs when the Codespace starts (not on every terminal open).`
349
350	`### Force Fresh Clone`
351
352	`To always get the latest version on rebuild:`
353
354	```jsonc
355	`{`
356	`"postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"`
357	`}`
358	```
359
360	`Warning: This removes any local changes on every rebuild.`
361
362	`## Troubleshooting`
363
364	`### Agents Not Appearing`
365
366	`Check HVE-Core was cloned:`
367
368	```bash
369	`ls /workspaces/hve-core/.github/agents`
370	```
371
372	`Check postCreateCommand ran:`
373
374	`Look at the Codespace creation log for clone output or errors.`
375
376	`### Clone Failed During Creation`
377
378	`Network issues: Try rebuilding the Codespace.`
379
380	`GitHub rate limiting: Ensure you're authenticated:`
381
382	```bash
383	`gh auth status`
384	```
385
386	`### Settings Not Applied`
387
388	`Check devcontainer.json paths:`
389
390	Settings must use absolute paths (`/workspaces/hve-core/...`).
391
392	`Verify settings in VS Code:`
393
394	1. Open Command Palette (`Ctrl+Shift+P`)
395	`2. Type "Preferences: Open User Settings (JSON)"`
396	`3. Check if settings are present`
397
398	`### Codespace Rebuild Doesn't Update HVE-Core`
399
400	`The clone command skips if the folder exists. Force update:`
401
402	```bash
403	`cd /workspaces/hve-core`
404	`git pull`
405	```
406
407	`Or modify postCreateCommand to always pull (see Auto-Update section).`
408
409	`## Limitations`
410
411	`\| Aspect \| Status \|`
412	`\|---------------------\|-------------------------------------------\|`
413	`\| Codespaces \| ✅ Designed for this \|`
414	`\| Local devcontainers \| ⚠️ Works but consider other methods \|`
415	`\| Team sharing \| ✅ Auto-setup for all contributors \|`
416	`\| Portable paths \| ⚠️ Absolute paths only \|`
417	`\| Version pinning \| ⚠️ Modify clone command for specific tag \|`
418	`\| Offline support \| ❌ Requires network during creation \|`
419	`\| Setup complexity \| ✅ Low (just devcontainer.json) \|`
420
421	`## Version Pinning`
422
423	`To pin to a specific version:`
424
425	```jsonc
426	`{`
427	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"`
428	`}`
429	```
430
431	Replace `v1.0.0` with your desired version tag.
432
433	`## Next Steps`
434
435	`* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task`
436	`* [Multi-Root Workspace](multi-root.md) - For dual local + Codespaces support`
437	`* [Submodule](submodule.md) - For team version control`
438
439	`---`
440
441	`<!-- markdownlint-disable MD036 -->`
442	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
443	`then carefully refined by our team of discerning human reviewers.*`
444	`<!-- markdownlint-enable MD036 -->`
445

microsoft/hve-core

Branches

Tags

Clone