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-v3.1.46

Find a branch or tag

Branches

hve-core-v3.1.46

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/codespaces.md

445lines · modeblame

Raw Download

Latest commit unavailable.

unknown

`6329fc0d`Bill Berry7 months ago	1	`---`
	2	`title: GitHub Codespaces Installation`
	3	`description: Install HVE-Core in GitHub Codespaces using postCreateCommand`
`569721b9`Jordan Knight4 months ago	4	`sidebar_position: 8`
`6329fc0d`Bill Berry7 months ago	5	`author: Microsoft`
	6	`ms.date: 2025-12-03`
	7	`ms.topic: how-to`
	8	`keywords:`
	9	`- codespaces`
	10	`- installation`
	11	`- github copilot`
	12	`- postCreateCommand`
	13	`- cloud development`
	14	`estimated_reading_time: 7`
	15	`---`
	16
	17	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.
	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
`5bcea1dd`Francisco Beltrao4 months ago	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] \|`
`6329fc0d`Bill Berry7 months ago	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
	46	`Codespaces 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
	57	The `postCreateCommand` clones HVE-Core into `/workspaces/hve-core` where it persists across Codespace sessions.
	58
	59	`## Quick Start`
	60
	61	Use the `hve-core-installer` agent:
	62
	63	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
	64	2. Select `hve-core-installer` from the agent picker
	65	`3. Say: "Install HVE-Core for Codespaces"`
	66	`4. Follow the guided setup`
	67
	68	`## Manual Setup`
	69
	70	`### Step 1: Update devcontainer.json`
	71
	72	`Add 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": {`
`1cf04b17`Bill Berry4 months ago	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	`}`
`6329fc0d`Bill Berry7 months ago	114	`}`
	115	`}`
	116	`}`
	117	`}`
	118	```
	119
	120	`### Step 2: Commit and Push`
	121
	122	```bash
	123	`git add .devcontainer/devcontainer.json`
	124	`git commit -m "feat: add HVE-Core support for Codespaces"`
	125	`git push`
	126	```
	127
	128	`### Step 3: Create or Rebuild Codespace`
	129
	130	`* New Codespace: Create from the updated branch`
	131	* Existing Codespace: Rebuild (`Ctrl+Shift+P` → "Codespaces: Rebuild Container")
	132
	133	`### Step 4: Validate Installation`
	134
	135	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
	136	`2. Click the agent picker dropdown`
	137	`3. 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": {`
`1cf04b17`Bill Berry4 months ago	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	`}`
`6329fc0d`Bill Berry7 months ago	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",`
`712b0b7b`Allen Greaves5 months ago	203	`"verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' \|\| echo '⚠️ Missing'"`
`6329fc0d`Bill Berry7 months ago	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": {`
`1cf04b17`Bill Berry4 months ago	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,`
`6329fc0d`Bill Berry7 months ago	217	`".github/prompts": true`
	218	`},`
	219	`"chat.instructionsFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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,`
`6329fc0d`Bill Berry7 months ago	226	`".github/instructions": true`
`6329fc0d`Bill Berry7 months ago	227	`},`
`67fb2ab0`Copilot5 months ago	228	`"chat.agentFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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,`
`712b0b7b`Allen Greaves5 months ago	238	`".github/agents": true`
`1cf04b17`Bill Berry4 months ago	239	`},`
	240	`"chat.agentSkillsLocations": {`
	241	`"/workspaces/hve-core/.github/skills": true,`
	242	`"/workspaces/hve-core/.github/skills/shared": true,`
	243	`".github/skills": true`
`6329fc0d`Bill Berry7 months ago	244	`}`
	245	`}`
	246	`}`
	247	`}`
	248	`}`
	249	```
	250
	251	`### Dual-Environment (Local + Codespaces)`
	252
	253	`For 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": {`
`1cf04b17`Bill Berry4 months ago	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`
`6329fc0d`Bill Berry7 months ago	283	`},`
`6329fc0d`Bill Berry7 months ago	284	`"chat.instructionsFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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`
`6329fc0d`Bill Berry7 months ago	297	`},`
`67fb2ab0`Copilot5 months ago	298	`"chat.agentFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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`
`6329fc0d`Bill Berry7 months ago	323	`}`
	324	`}`
	325	`}`
	326	`}`
	327	`}`
	328	```
	329
	330	`## Updating HVE-Core`
	331
	332	`### Manual Update`
	333
	334	```bash
	335	`cd /workspaces/hve-core`
	336	`git pull`
	337	```
	338
	339	`### Auto-Update on Codespace Start`
	340
	341	Add `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
	349	`This runs when the Codespace starts (not on every terminal open).`
	350
	351	`### Force Fresh Clone`
	352
	353	`To 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
`712b0b7b`Allen Greaves5 months ago	370	`ls /workspaces/hve-core/.github/agents`
`6329fc0d`Bill Berry7 months ago	371	```
	372
	373	`Check postCreateCommand ran:`
	374
	375	`Look 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
	384	`gh auth status`
	385	```
	386
	387	`### Settings Not Applied`
	388
	389	`Check devcontainer.json paths:`
	390
	391	Settings must use absolute paths (`/workspaces/hve-core/...`).
	392
	393	`Verify settings in VS Code:`
	394
	395	1. Open Command Palette (`Ctrl+Shift+P`)
	396	`2. Type "Preferences: Open User Settings (JSON)"`
	397	`3. Check if settings are present`
	398
	399	`### Codespace Rebuild Doesn't Update HVE-Core`
	400
	401	`The clone command skips if the folder exists. Force update:`
	402
	403	```bash
	404	`cd /workspaces/hve-core`
	405	`git pull`
	406	```
	407
	408	`Or modify postCreateCommand to always pull (see Auto-Update section).`
	409
	410	`## Limitations`
	411
`5113e3ba`Allen Greaves6 months ago	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) \|`
`6329fc0d`Bill Berry7 months ago	421
	422	`## Version Pinning`
	423
	424	`To 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
	432	Replace `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 -->`
`b4e75565`Bill Berry5 months ago	443	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
`6329fc0d`Bill Berry7 months ago	444	`then carefully refined by our team of discerning human reviewers.*`
`6329fc0d`Bill Berry7 months ago	445	`<!-- markdownlint-enable MD036 -->`

microsoft/hve-core

Branches

Tags

Clone