fix(docs): replace parent-directory VS Code settings paths with per-subdirectory enumeration

[WilliamBerryiii]

Description

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:

• 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)
• 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)
• 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.
• 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 and 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 - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: 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

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• 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

• 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:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate

Security Considerations

• 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.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[katriendg]

Thanks, nice to have this covered now.