microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

3a3a0fdf923d96a9e8a9ac734c73f24433b525e8

Find a branch or tag

Branches

3a3a0fdf923d96a9e8a9ac734c73f24433b525e8

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/submodule.md

276lines · modecode

Raw Download

Latest commit unavailable.

unknown

1	`---`
2	`title: Git Submodule Installation`
3	`description: Set up HVE-Core as a git submodule for version-controlled team consumption`
4	`sidebar_position: 7`
5	`author: Microsoft`
6	`ms.date: 2026-03-10`
7	`ms.topic: how-to`
8	`keywords:`
9	`- git submodule`
10	`- installation`
11	`- github copilot`
12	`- version control`
13	`- teams`
14	`estimated_reading_time: 7`
15	`---`
16
17	`Git submodules provide version-controlled, reproducible HVE-Core consumption. Every team member gets the exact same version, and updates are explicit commits.`
18
19	`## When to Use This Method`
20
21	`✅ Use this when:`
22
23	`* Your team needs reproducible setups (same version for everyone)`
24	`* You want to pin HVE-Core to a specific version`
25	`* Updates should be deliberate, reviewed commits`
26	`* HVE-Core dependency should be tracked in version control`
27
28	`❌ Consider alternatives when:`
29
30	`* You want automatic updates → [Multi-Root Workspace](multi-root.md)`
31	`* You're a solo developer without version pinning needs → [Multi-Root Workspace](multi-root.md)`
32
33	`## How It Works`
34
35	A git submodule embeds HVE-Core as a nested repository within your project. The `.gitmodules` file tracks the repository URL, and your project's git history tracks the exact commit.
36
37	```text
38	`your-project/`
39	`├── .gitmodules ← Defines submodule URL`
40	`├── lib/`
41	`│ └── hve-core/ ← Submodule (points to specific commit)`
42	`│ └── .github/`
43	`│ ├── agents/`
44	`│ ├── prompts/`
45	`│ └── instructions/`
46	`└── .vscode/`
47	`└── settings.json ← Points to lib/hve-core paths`
48	```
49
50	`## Quick Start`
51
52	`Install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) for the fastest setup. For guided setup with installation method selection and MCP configuration, install the [HVE Core Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer) extension and ask any agent "help me customize hve-core installation". Use the manual steps below for direct configuration.`
53
54	`## Manual Setup`
55
56	`### Step 1: Add the Submodule`
57
58	```bash
59	`# From your project root`
60	`git submodule add https://github.com/microsoft/hve-core.git lib/hve-core`
61	`git commit -m "Add HVE-Core as submodule"`
62	```
63
64	This creates a `.gitmodules` file:
65
66	```ini
67	`[submodule "lib/hve-core"]`
68	`path = lib/hve-core`
69	`url = https://github.com/microsoft/hve-core.git`
70	`branch = main`
71	```
72
73	`### Step 2: Configure VS Code Settings`
74
75	Create or update `.vscode/settings.json`:
76
77	```jsonc
78	`{`
79	`"chat.agentFilesLocations": {`
80	`"lib/hve-core/.github/agents/ado": true,`
81	`"lib/hve-core/.github/agents/data-science": true,`
82	`"lib/hve-core/.github/agents/design-thinking": true,`
83	`"lib/hve-core/.github/agents/github": true,`
84	`"lib/hve-core/.github/agents/project-planning": true,`
85	`"lib/hve-core/.github/agents/hve-core": true,`
86	`"lib/hve-core/.github/agents/hve-core/subagents": true,`
87	`"lib/hve-core/.github/agents/security": true,`
88	`".github/agents": true`
89	`},`
90	`"chat.promptFilesLocations": {`
91	`"lib/hve-core/.github/prompts/ado": true,`
92	`"lib/hve-core/.github/prompts/design-thinking": true,`
93	`"lib/hve-core/.github/prompts/github": true,`
94	`"lib/hve-core/.github/prompts/hve-core": true,`
95	`"lib/hve-core/.github/prompts/security": true,`
96	`".github/prompts": true`
97	`},`
98	`"chat.instructionsFilesLocations": {`
99	`"lib/hve-core/.github/instructions/ado": true,`
100	`"lib/hve-core/.github/instructions/coding-standards": true,`
101	`"lib/hve-core/.github/instructions/design-thinking": true,`
102	`"lib/hve-core/.github/instructions/github": true,`
103	`"lib/hve-core/.github/instructions/hve-core": true,`
104	`"lib/hve-core/.github/instructions/shared": true,`
105	`".github/instructions": true`
106	`},`
107	`"chat.agentSkillsLocations": {`
108	`"lib/hve-core/.github/skills": true,`
109	`"lib/hve-core/.github/skills/shared": true,`
110	`".github/skills": true`
111	`}`
112	`}`
113	```
114
115	`### Step 3: Configure Devcontainer (Codespaces)`
116
117	Update `.devcontainer/devcontainer.json` to initialize submodules automatically:
118
119	```jsonc
120	`{`
121	`"name": "My Project with HVE-Core",`
122	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
123
124	`"onCreateCommand": "git submodule update --init --recursive",`
125
126	`"customizations": {`
127	`"vscode": {`
128	`"extensions": [`
129	`"github.copilot",`
130	`"github.copilot-chat"`
131	`]`
132	`}`
133	`}`
134	`}`
135	```
136
137	`## Team Member Onboarding`
138
139	`When team members clone your project, they need to initialize submodules.`
140
141	`### Option A: Clone with submodules (recommended)`
142
143	```bash
144	`git clone --recurse-submodules https://github.com/your-org/your-project.git`
145	```
146
147	`### Option B: Initialize after clone`
148
149	```bash
150	`git clone https://github.com/your-org/your-project.git`
151	`cd your-project`
152	`git submodule update --init --recursive`
153	```
154
155	`### Option C: Configure git to auto-recurse`
156
157	```bash
158	`git config --global submodule.recurse true`
159	`# Now all git operations auto-update submodules`
160	```
161
162	`## Updating HVE-Core`
163
164	`\| Task \| Command \|`
165	`\|------------------------\|-----------------------------------------------------------------------\|`
166	\| Check for updates \| `cd lib/hve-core && git fetch && git log HEAD..origin/main --oneline` \|
167	\| Update to latest \| `git submodule update --remote lib/hve-core` \|
168	\| Pin to specific commit \| `cd lib/hve-core && git checkout <sha>` \|
169	\| Track different branch \| `git config submodule.lib/hve-core.branch develop` \|
170
171	`### After updating, commit the change`
172
173	```bash
174	`git add lib/hve-core`
175	`git commit -m "Update HVE-Core submodule to latest"`
176	```
177
178	`### Auto-Update on Container Rebuild`
179
180	`To update HVE-Core when rebuilding your devcontainer:`
181
182	```jsonc
183	`{`
184	`"updateContentCommand": "git submodule update --remote lib/hve-core \|\| true"`
185	`}`
186	```
187
188	`## Version Pinning`
189
190	`Submodules pin to a specific commit by default. To verify or change the pinned version:`
191
192	`### Check current version`
193
194	```bash
195	`cd lib/hve-core`
196	`git log -1 --oneline`
197	```
198
199	`### Pin to a specific tag or commit`
200
201	```bash
202	`cd lib/hve-core`
203	`git checkout v1.2.0 # or a specific commit SHA`
204	`cd ..`
205	`git add lib/hve-core`
206	`git commit -m "Pin HVE-Core to v1.2.0"`
207	```
208
209	`## Verification`
210
211	`After setup, verify HVE-Core is working:`
212
213	1. Check `lib/hve-core/` contains the HVE-Core repository
214	2. Open Copilot Chat (`Ctrl+Alt+I`)
215	`3. Click the agent picker dropdown`
216	`4. Verify HVE-Core agents appear (task-planner, task-researcher, etc.)`
217
218	`## Troubleshooting`
219
220	`### Submodule folder is empty`
221
222	`The submodule wasn't initialized:`
223
224	```bash
225	`git submodule update --init --recursive`
226	```
227
228	`### Agents not appearing`
229
230	* Verify `.vscode/settings.json` paths match submodule location
231	* Reload the window with `Ctrl+Shift+P` → "Developer: Reload Window"
232	* Confirm submodule content exists with `ls lib/hve-core/.github/agents/`
233
234	`### "Detached HEAD" warning in submodule`
235
236	`This is normal for submodules. The submodule points to a specific commit, not a branch. To work on the submodule:`
237
238	```bash
239	`cd lib/hve-core`
240	`git checkout main`
241	```
242
243	`### Merge conflicts in submodule pointer`
244
245	`When multiple team members update the submodule:`
246
247	```bash
248	`git checkout --theirs lib/hve-core # Accept their version`
249	`# OR`
250	`git checkout --ours lib/hve-core # Keep your version`
251	`git add lib/hve-core`
252	`git commit`
253	```
254
255	`## Comparison with Other Methods`
256
257	`\| Aspect \| Submodule \| Multi-Root \| Clone \|`
258	`\|----------------------\|---------------------\|-------------------\|---------------\|`
259	`\| Version controlled \| ✅ Yes \| ⚠️ Partial \| ❌ No \|`
260	`\| Team reproducibility \| ✅ Same version \| ⚠️ May vary \| ⚠️ May vary \|`
261	`\| Update control \| ✅ Explicit commits \| ⚠️ Automatic \| ⚠️ Automatic \|`
262	`\| In workspace \| ✅ Subfolder \| ✅ Workspace root \| ❌ External \|`
263	`\| Initial setup \| 🟡 Medium \| 🟡 Medium \| 🟢 Easy \|`
264
265	`## Next Steps`
266
267	`* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task`
268	`* [RPI Workflow](../../rpi/) - Research, Plan, Implement methodology`
269	`* [Back to Installation Guide](../install.md) - Compare other methods`
270
271	`---`
272
273	`<!-- markdownlint-disable MD036 -->`
274	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
275	`then carefully refined by our team of discerning human reviewers.*`
276	`<!-- markdownlint-enable MD036 -->`

microsoft/hve-core

Branches

Tags

Clone