microsoft/hve-core

Public

mirrored from https://github.com/microsoft/hve-coreAvailable

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v2.3.9

Find a branch or tag

Branches

hve-core-v2.3.9

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/codespaces.md

328lines · modeblame

Raw Download

Latest commit unavailable.

unknown

`6329fc0d`Bill Berry6 months ago	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": {`
`67fb2ab0`Copilot4 months ago	83	`"chat.agentFilesLocations": { "/workspaces/hve-core/.github/agents": true },`
`6329fc0d`Bill Berry6 months ago	84	`"chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },`
	85	`"chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": true }`
	86	`}`
	87	`}`
	88	`}`
	89	`}`
	90	```
	91
	92	`### Step 2: Commit and Push`
	93
	94	```bash
	95	`git add .devcontainer/devcontainer.json`
	96	`git commit -m "feat: add HVE-Core support for Codespaces"`
	97	`git push`
	98	```
	99
	100	`### Step 3: Create or Rebuild Codespace`
	101
	102	`* New Codespace: Create from the updated branch`
	103	* Existing Codespace: Rebuild (`Ctrl+Shift+P` → "Codespaces: Rebuild Container")
	104
	105	`### Step 4: Validate Installation`
	106
	107	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
	108	`2. Click the agent picker dropdown`
	109	`3. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder)`
	110
	111	`## Complete Configuration Examples`
	112
	113	`### Minimal Configuration`
	114
	115	```jsonc
	116	`{`
	117	`"name": "HVE-Core Enabled",`
	118	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
	119
	120	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
	121
	122	`"customizations": {`
	123	`"vscode": {`
	124	`"settings": {`
`67fb2ab0`Copilot4 months ago	125	`"chat.agentFilesLocations": { "/workspaces/hve-core/.github/agents": true },`
`6329fc0d`Bill Berry6 months ago	126	`"chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },`
	127	`"chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": true }`
	128	`}`
	129	`}`
	130	`}`
	131	`}`
	132	```
	133
	134	`### Full-Featured Configuration`
	135
	136	```jsonc
	137	`{`
	138	`"name": "HVE-Core Development Environment",`
	139	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
	140
	141	`"features": {`
	142	`"ghcr.io/devcontainers/features/git:1": {},`
	143	`"ghcr.io/devcontainers/features/github-cli:1": {}`
	144	`},`
	145
	146	`"postCreateCommand": {`
	147	`"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",`
`712b0b7b`Allen Greaves5 months ago	148	`"verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' \|\| echo '⚠️ Missing'"`
`6329fc0d`Bill Berry6 months ago	149	`},`
	150
	151	`"updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null \|\| echo 'Update skipped'",`
	152
	153	`"customizations": {`
	154	`"vscode": {`
	155	`"settings": {`
	156	`"chat.promptFilesLocations": {`
	157	`"/workspaces/hve-core/.github/prompts": true,`
	158	`".github/prompts": true`
	159	`},`
	160	`"chat.instructionsFilesLocations": {`
	161	`"/workspaces/hve-core/.github/instructions": true,`
	162	`".github/instructions": true`
	163	`},`
`67fb2ab0`Copilot4 months ago	164	`"chat.agentFilesLocations": {`
`712b0b7b`Allen Greaves5 months ago	165	`"/workspaces/hve-core/.github/agents": true,`
`712b0b7b`Allen Greaves5 months ago	166	`".github/agents": true`
`6329fc0d`Bill Berry6 months ago	167	`}`
	168	`}`
	169	`}`
	170	`}`
	171	`}`
	172	```
	173
	174	`### Dual-Environment (Local + Codespaces)`
	175
	176	`For projects needing HVE-Core in both local devcontainers and Codespaces:`
	177
	178	```jsonc
	179	`{`
	180	`"name": "HVE-Core (Local + Codespaces)",`
	181	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
	182
	183	`// Clone if not already present (Codespaces path)`
	184	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
	185
	186	`// Local only: mount peer directory (silently fails in Codespaces)`
	187	`"mounts": [`
	188	`"source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"`
	189	`],`
	190
	191	`"customizations": {`
	192	`"vscode": {`
	193	`"settings": {`
	194	`// Both paths - VS Code ignores non-existent paths`
	195	`"chat.promptFilesLocations": {`
	196	`"/workspaces/hve-core/.github/prompts": true,`
	197	`"../hve-core/.github/prompts": true`
	198	`},`
	199	`"chat.instructionsFilesLocations": {`
	200	`"/workspaces/hve-core/.github/instructions": true,`
	201	`"../hve-core/.github/instructions": true`
	202	`},`
`67fb2ab0`Copilot4 months ago	203	`"chat.agentFilesLocations": {`
`712b0b7b`Allen Greaves5 months ago	204	`"/workspaces/hve-core/.github/agents": true,`
`712b0b7b`Allen Greaves5 months ago	205	`"../hve-core/.github/agents": true`
`6329fc0d`Bill Berry6 months ago	206	`}`
	207	`}`
	208	`}`
	209	`}`
	210	`}`
	211	```
	212
	213	`## Updating HVE-Core`
	214
	215	`### Manual Update`
	216
	217	```bash
	218	`cd /workspaces/hve-core`
	219	`git pull`
	220	```
	221
	222	`### Auto-Update on Codespace Start`
	223
	224	Add `updateContentCommand` to your devcontainer.json:
	225
	226	```jsonc
	227	`{`
	228	`"updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null \|\| true"`
	229	`}`
	230	```
	231
	232	`This runs when the Codespace starts (not on every terminal open).`
	233
	234	`### Force Fresh Clone`
	235
	236	`To always get the latest version on rebuild:`
	237
	238	```jsonc
	239	`{`
	240	`"postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"`
	241	`}`
	242	```
	243
	244	`Warning: This removes any local changes on every rebuild.`
	245
	246	`## Troubleshooting`
	247
	248	`### Agents Not Appearing`
	249
	250	`Check HVE-Core was cloned:`
	251
	252	```bash
`712b0b7b`Allen Greaves5 months ago	253	`ls /workspaces/hve-core/.github/agents`
`6329fc0d`Bill Berry6 months ago	254	```
	255
	256	`Check postCreateCommand ran:`
	257
	258	`Look at the Codespace creation log for clone output or errors.`
	259
	260	`### Clone Failed During Creation`
	261
	262	`Network issues: Try rebuilding the Codespace.`
	263
	264	`GitHub rate limiting: Ensure you're authenticated:`
	265
	266	```bash
	267	`gh auth status`
	268	```
	269
	270	`### Settings Not Applied`
	271
	272	`Check devcontainer.json paths:`
	273
	274	Settings must use absolute paths (`/workspaces/hve-core/...`).
	275
	276	`Verify settings in VS Code:`
	277
	278	1. Open Command Palette (`Ctrl+Shift+P`)
	279	`2. Type "Preferences: Open User Settings (JSON)"`
	280	`3. Check if settings are present`
	281
	282	`### Codespace Rebuild Doesn't Update HVE-Core`
	283
	284	`The clone command skips if the folder exists. Force update:`
	285
	286	```bash
	287	`cd /workspaces/hve-core`
	288	`git pull`
	289	```
	290
	291	`Or modify postCreateCommand to always pull (see Auto-Update section).`
	292
	293	`## Limitations`
	294
`5113e3ba`Allen Greaves5 months ago	295	`\| Aspect \| Status \|`
	296	`\|---------------------\|-------------------------------------------\|`
	297	`\| Codespaces \| ✅ Designed for this \|`
	298	`\| Local devcontainers \| ⚠️ Works but consider other methods \|`
	299	`\| Team sharing \| ✅ Auto-setup for all contributors \|`
	300	`\| Portable paths \| ⚠️ Absolute paths only \|`
	301	`\| Version pinning \| ⚠️ Modify clone command for specific tag \|`
	302	`\| Offline support \| ❌ Requires network during creation \|`
	303	`\| Setup complexity \| ✅ Low (just devcontainer.json) \|`
`6329fc0d`Bill Berry6 months ago	304
	305	`## Version Pinning`
	306
	307	`To pin to a specific version:`
	308
	309	```jsonc
	310	`{`
	311	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"`
	312	`}`
	313	```
	314
	315	Replace `v1.0.0` with your desired version tag.
	316
	317	`## Next Steps`
	318
	319	`* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task`
	320	`* [Multi-Root Workspace](multi-root.md) - For dual local + Codespaces support`
	321	`* [Submodule](submodule.md) - For team version control`
	322
	323	`---`
	324
	325	`<!-- markdownlint-disable MD036 -->`
`b4e75565`Bill Berry5 months ago	326	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
`6329fc0d`Bill Berry6 months ago	327	`then carefully refined by our team of discerning human reviewers.*`
`6329fc0d`Bill Berry6 months ago	328	`<!-- markdownlint-enable MD036 -->`

microsoft/hve-core

Branches

Tags

Clone