GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

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

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
1a96b7384cd85a53b6036e7275d391fcb75cd11d

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/codespaces.md

445lines · modecode

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