microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

b3fcbb5d710029cb4fe91fca91c5ebf46bfb362e

Find a branch or tag

Branches

b3fcbb5d710029cb4fe91fca91c5ebf46bfb362e

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/codespaces.md

444lines · 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
`5bcea1dd`Francisco Beltrao4 months ago	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] \|`
`6329fc0d`Bill Berry6 months ago	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": {`
`1cf04b17`Bill Berry4 months ago	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	`}`
`6329fc0d`Bill Berry6 months ago	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": {`
`1cf04b17`Bill Berry4 months ago	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	`}`
`6329fc0d`Bill Berry6 months ago	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",`
`712b0b7b`Allen Greaves5 months ago	202	`"verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' \|\| echo '⚠️ Missing'"`
`6329fc0d`Bill Berry6 months ago	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": {`
`1cf04b17`Bill Berry4 months ago	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,`
`6329fc0d`Bill Berry6 months ago	216	`".github/prompts": true`
	217	`},`
	218	`"chat.instructionsFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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,`
`6329fc0d`Bill Berry6 months ago	225	`".github/instructions": true`
`6329fc0d`Bill Berry6 months ago	226	`},`
`67fb2ab0`Copilot4 months ago	227	`"chat.agentFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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,`
`712b0b7b`Allen Greaves5 months ago	237	`".github/agents": true`
`1cf04b17`Bill Berry4 months ago	238	`},`
	239	`"chat.agentSkillsLocations": {`
	240	`"/workspaces/hve-core/.github/skills": true,`
	241	`"/workspaces/hve-core/.github/skills/shared": true,`
	242	`".github/skills": true`
`6329fc0d`Bill Berry6 months ago	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": {`
`1cf04b17`Bill Berry4 months ago	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`
`6329fc0d`Bill Berry6 months ago	282	`},`
`6329fc0d`Bill Berry6 months ago	283	`"chat.instructionsFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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`
`6329fc0d`Bill Berry6 months ago	296	`},`
`67fb2ab0`Copilot4 months ago	297	`"chat.agentFilesLocations": {`
`1cf04b17`Bill Berry4 months ago	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`
`6329fc0d`Bill Berry6 months ago	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
`712b0b7b`Allen Greaves5 months ago	369	`ls /workspaces/hve-core/.github/agents`
`6329fc0d`Bill Berry6 months ago	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
`5113e3ba`Allen Greaves5 months ago	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) \|`
`6329fc0d`Bill Berry6 months ago	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 -->`
`b4e75565`Bill Berry5 months ago	442	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
`6329fc0d`Bill Berry6 months ago	443	`then carefully refined by our team of discerning human reviewers.*`
`6329fc0d`Bill Berry6 months ago	444	`<!-- markdownlint-enable MD036 -->`

microsoft/hve-core

Branches

Tags

Clone