Skip to content

Commit 1cf04b1

Browse files
WilliamBerryiiikatriendg
WilliamBerryiii
and
katriendg
authored
fix(docs): replace parent-directory VS Code settings paths with per-subdirectory enumeration (#732)
All six getting-started method docs and the installer agent template used single parent-directory glob entries for `chat.agentFilesLocations`, `chat.promptFilesLocations`, and `chat.instructionsFilesLocations`. These entries failed to resolve correctly in VS Code, preventing Copilot from discovering agents, prompts, and instructions. > Parent-directory paths like `".github/agents": true` do not match the way VS Code resolves these settings. Per-subdirectory enumeration aligns with the canonical `.vscode/settings.json` structure. Each parent-directory entry was replaced with explicit per-subdirectory entries matching the canonical configuration. The previously missing `chat.agentSkillsLocations` setting was added to every settings block, closing a gap in skills discovery. ### Getting-Started Method Docs Six method docs received the same transformation, each preserving its method-specific path prefix: - Expanded **`chat.agentFilesLocations`** from 1 parent-directory entry to 9 subdirectory entries: *ado*, *data-science*, *design-thinking*, *github*, *installer*, *project-planning*, *hve-core*, *hve-core/subagents*, *security-planning* - Expanded **`chat.promptFilesLocations`** from 1 entry to 5 subdirectory entries: *ado*, *design-thinking*, *github*, *hve-core*, *security-planning* - Expanded **`chat.instructionsFilesLocations`** from 1 entry to 6 subdirectory entries: *ado*, *coding-standards*, *design-thinking*, *github*, *hve-core*, *shared* - Added **`chat.agentSkillsLocations`** with `.github/skills` and `.github/skills/shared` entries Files updated: *codespaces.md*, *git-ignored.md*, *mounted.md*, *multi-root.md*, *peer-clone.md*, *submodule.md*. Local project override entries in *submodule.md*, *codespaces.md*, and *multi-root.md* were preserved unchanged. ### Installer Agent Template - Added **`chat.agentSkillsLocations`** to both the generic `<PREFIX>` template block and the devcontainer example block in *hve-core-installer.agent.md* - Existing per-subdirectory entries for the other three settings were already correct and left unchanged ## Related Issue(s) Fixes #710 ## Type of Change Select all that apply: **Code & Documentation:** - [x] Bug fix (non-breaking change fixing an issue) - [ ] New feature (non-breaking change adding functionality) - [ ] Breaking change (fix or feature causing existing functionality to change) - [x] Documentation update **Infrastructure & Configuration:** - [ ] GitHub Actions workflow - [ ] Linting configuration (markdown, PowerShell, etc.) - [ ] Security configuration - [ ] DevContainer configuration - [ ] Dependency update **AI Artifacts:** - [ ] Reviewed contribution with `prompt-builder` agent and addressed all feedback - [ ] Copilot instructions (`.github/instructions/*.instructions.md`) - [ ] Copilot prompt (`.github/prompts/*.prompt.md`) - [x] Copilot agent (`.github/agents/*.agent.md`) - [ ] Copilot skill (`.github/skills/*/SKILL.md`) > **Note for AI Artifact Contributors**: > > - **Agents**: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review `.github/agents/` before creating new ones. > - **Skills**: Must include both bash and PowerShell scripts. See [Skills](../docs/contributing/skills.md). > - **Model Versions**: Only contributions targeting the **latest Anthropic and OpenAI models** will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected. > - See [Agents Not Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements). **Other:** - [ ] Script/automation (`.ps1`, `.sh`, `.py`) - [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) **User Request:** Use the installer agent to set up HVE-Core in a new project. The updated agent template now includes `chat.agentSkillsLocations` entries so skills are discoverable after installation. **Execution Flow:** 1. User invokes the installer agent for any supported method (peer-clone, submodule, codespace, etc.) 2. Agent generates VS Code settings JSON that includes all four `chat.*` location settings 3. `chat.agentSkillsLocations` entries point to `.github/skills` and `.github/skills/shared` under the appropriate prefix **Output Artifacts:** Generated `.vscode/settings.json` or devcontainer customization block containing the four location settings with per-subdirectory entries. **Success Indicators:** Copilot discovers agents, prompts, instructions, and skills from HVE-Core after applying the generated settings. The `chat.agentSkillsLocations` entries appear in the output alongside the other three location settings. > [!NOTE] > Human review is recommended for agent-populated Sample Prompts content. For detailed contribution requirements, see: - **Common Standards**: [docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md) - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing - **Agents**: [docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md) - Agent configurations with tools and behavior patterns - **Prompts**: [docs/contributing/prompts.md](../docs/contributing/prompts.md) - Workflow-specific guidance with template variables - **Instructions**: [docs/contributing/instructions.md](../docs/contributing/instructions.md) - Technology-specific standards with glob patterns - **Skills**: [docs/contributing/skills.md](../docs/contributing/skills.md) - Task execution utilities with cross-platform scripts ## Testing Automated validation performed: - `npm run lint:md`: Passed (zero errors across all changed files) - Content verification: Confirmed `chat.agentSkillsLocations` present in all 7 changed files - Regression check: Confirmed no parent-directory glob patterns remain in any changed file - Cross-file consistency: Verified subdirectory lists match across all method docs and installer agent - Manual testing was not performed ## Checklist ### Required Checks - [x] Documentation is updated (if applicable) - [x] Files follow existing naming conventions - [x] Changes are backwards compatible (if applicable) - [ ] Tests added for new functionality (if applicable) (N/A — documentation and template corrections, no new testable functionality) ### AI Artifact Contributions <!-- If contributing an agent, prompt, instruction, or skill, complete these checks --> - [ ] Used `/prompt-analyze` to review contribution - [ ] Addressed all feedback from `prompt-builder` review - [ ] Verified contribution follows common standards and type-specific requirements ### Required Automated Checks The following validation commands must pass before merging: - [x] Markdown linting: `npm run lint:md` - [x] Spell checking: `npm run spell-check` - [x] Frontmatter validation: `npm run lint:frontmatter` - [x] Skill structure validation: `npm run validate:skills` - [x] Link validation: `npm run lint:md-links` - [x] PowerShell analysis: `npm run lint:ps` - [x] Plugin freshness: `npm run plugin:generate` ## Security Considerations <!-- ⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data --> - [x] This PR does not contain any sensitive or NDA information - [ ] Any new dependencies have been reviewed for security issues (N/A — no dependency changes) - [ ] Security-related scripts follow the principle of least privilege (N/A — no security script changes) ## Additional Notes All seven files now align with the canonical `.vscode/settings.json` structure. The per-subdirectory enumeration pattern ensures VS Code correctly discovers HVE-Core artifacts across all supported installation methods. Co-authored-by: Katrien De Graeve <katriendg@users.noreply.github.com>
1 parent 69caa84 commit 1cf04b1

File tree

7 files changed

+369
-39
lines changed

7 files changed

+369
-39
lines changed

‎.github/agents/installer/hve-core-installer.agent.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -533,6 +533,10 @@ Enumerate each collection subdirectory under `.github/agents/`, `.github/prompts
533533
"<PREFIX>/.github/instructions/github": true,
534534
"<PREFIX>/.github/instructions/hve-core": true,
535535
"<PREFIX>/.github/instructions/shared": true
536+
},
537+
"chat.agentSkillsLocations": {
538+
"<PREFIX>/.github/skills": true,
539+
"<PREFIX>/.github/skills/shared": true
536540
}
537541
}
538542
```
@@ -618,6 +622,10 @@ Add to devcontainer.json:
618622
"/workspaces/hve-core/.github/instructions/github": true,
619623
"/workspaces/hve-core/.github/instructions/hve-core": true,
620624
"/workspaces/hve-core/.github/instructions/shared": true
625+
},
626+
"chat.agentSkillsLocations": {
627+
"/workspaces/hve-core/.github/skills": true,
628+
"/workspaces/hve-core/.github/skills/shared": true
621629
}
622630
}
623631
}

‎docs/getting-started/methods/codespaces.md‎

Lines changed: 131 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -80,9 +80,36 @@ Add the clone command and VS Code settings:
8080
"customizations": {
8181
"vscode": {
8282
"settings": {
83-
"chat.agentFilesLocations": { "/workspaces/hve-core/.github/agents": true },
84-
"chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },
85-
"chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": true }
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+
}
86113
}
87114
}
88115
}
@@ -122,9 +149,36 @@ git push
122149
"customizations": {
123150
"vscode": {
124151
"settings": {
125-
"chat.agentFilesLocations": { "/workspaces/hve-core/.github/agents": true },
126-
"chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },
127-
"chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": true }
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+
}
128182
}
129183
}
130184
}
@@ -154,16 +208,38 @@ git push
154208
"vscode": {
155209
"settings": {
156210
"chat.promptFilesLocations": {
157-
"/workspaces/hve-core/.github/prompts": true,
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,
158216
".github/prompts": true
159217
},
160218
"chat.instructionsFilesLocations": {
161-
"/workspaces/hve-core/.github/instructions": true,
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,
162225
".github/instructions": true
163226
},
164227
"chat.agentFilesLocations": {
165-
"/workspaces/hve-core/.github/agents": true,
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,
166237
".github/agents": true
238+
},
239+
"chat.agentSkillsLocations": {
240+
"/workspaces/hve-core/.github/skills": true,
241+
"/workspaces/hve-core/.github/skills/shared": true,
242+
".github/skills": true
167243
}
168244
}
169245
}
@@ -193,16 +269,56 @@ For projects needing HVE-Core in both local devcontainers and Codespaces:
193269
"settings": {
194270
// Both paths - VS Code ignores non-existent paths
195271
"chat.promptFilesLocations": {
196-
"/workspaces/hve-core/.github/prompts": true,
197-
"../hve-core/.github/prompts": true
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
198282
},
199283
"chat.instructionsFilesLocations": {
200-
"/workspaces/hve-core/.github/instructions": true,
201-
"../hve-core/.github/instructions": true
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
202296
},
203297
"chat.agentFilesLocations": {
204-
"/workspaces/hve-core/.github/agents": true,
205-
"../hve-core/.github/agents": true
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
206322
}
207323
}
208324
}

‎docs/getting-started/methods/git-ignored.md‎

Lines changed: 60 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -99,9 +99,36 @@ Create or update `.vscode/settings.json`:
9999

100100
```json
101101
{
102-
"chat.agentFilesLocations": { ".hve-core/.github/agents": true },
103-
"chat.promptFilesLocations": { ".hve-core/.github/prompts": true },
104-
"chat.instructionsFilesLocations": { ".hve-core/.github/instructions": true }
102+
"chat.agentFilesLocations": {
103+
".hve-core/.github/agents/ado": true,
104+
".hve-core/.github/agents/data-science": true,
105+
".hve-core/.github/agents/design-thinking": true,
106+
".hve-core/.github/agents/github": true,
107+
".hve-core/.github/agents/installer": true,
108+
".hve-core/.github/agents/project-planning": true,
109+
".hve-core/.github/agents/hve-core": true,
110+
".hve-core/.github/agents/hve-core/subagents": true,
111+
".hve-core/.github/agents/security-planning": true
112+
},
113+
"chat.promptFilesLocations": {
114+
".hve-core/.github/prompts/ado": true,
115+
".hve-core/.github/prompts/design-thinking": true,
116+
".hve-core/.github/prompts/github": true,
117+
".hve-core/.github/prompts/hve-core": true,
118+
".hve-core/.github/prompts/security-planning": true
119+
},
120+
"chat.instructionsFilesLocations": {
121+
".hve-core/.github/instructions/ado": true,
122+
".hve-core/.github/instructions/coding-standards": true,
123+
".hve-core/.github/instructions/design-thinking": true,
124+
".hve-core/.github/instructions/github": true,
125+
".hve-core/.github/instructions/hve-core": true,
126+
".hve-core/.github/instructions/shared": true
127+
},
128+
"chat.agentSkillsLocations": {
129+
".hve-core/.github/skills": true,
130+
".hve-core/.github/skills/shared": true
131+
}
105132
}
106133
```
107134

@@ -136,9 +163,36 @@ Add to `.devcontainer/devcontainer.json` so HVE-Core is cloned on container crea
136163
"customizations": {
137164
"vscode": {
138165
"settings": {
139-
"chat.agentFilesLocations": { ".hve-core/.github/agents": true },
140-
"chat.promptFilesLocations": { ".hve-core/.github/prompts": true },
141-
"chat.instructionsFilesLocations": { ".hve-core/.github/instructions": true }
166+
"chat.agentFilesLocations": {
167+
".hve-core/.github/agents/ado": true,
168+
".hve-core/.github/agents/data-science": true,
169+
".hve-core/.github/agents/design-thinking": true,
170+
".hve-core/.github/agents/github": true,
171+
".hve-core/.github/agents/installer": true,
172+
".hve-core/.github/agents/project-planning": true,
173+
".hve-core/.github/agents/hve-core": true,
174+
".hve-core/.github/agents/hve-core/subagents": true,
175+
".hve-core/.github/agents/security-planning": true
176+
},
177+
"chat.promptFilesLocations": {
178+
".hve-core/.github/prompts/ado": true,
179+
".hve-core/.github/prompts/design-thinking": true,
180+
".hve-core/.github/prompts/github": true,
181+
".hve-core/.github/prompts/hve-core": true,
182+
".hve-core/.github/prompts/security-planning": true
183+
},
184+
"chat.instructionsFilesLocations": {
185+
".hve-core/.github/instructions/ado": true,
186+
".hve-core/.github/instructions/coding-standards": true,
187+
".hve-core/.github/instructions/design-thinking": true,
188+
".hve-core/.github/instructions/github": true,
189+
".hve-core/.github/instructions/hve-core": true,
190+
".hve-core/.github/instructions/shared": true
191+
},
192+
"chat.agentSkillsLocations": {
193+
".hve-core/.github/skills": true,
194+
".hve-core/.github/skills/shared": true
195+
}
142196
}
143197
}
144198
}

0 commit comments

Comments
 (0)