Summary

Multiple AI artifacts (agents, instructions, prompts) contain hardcoded workspace-root-relative paths in their prose body text — paths like .github/instructions/design-thinking/dt-coaching-identity.instructions.md. These paths assume the hve-core repository IS the workspace root.

When artifacts are loaded from a VS Code extension install path (~/.vscode-server-insiders/data/User/globalStorage/ise-hve-essentials.hve-core/.github/...), a peer clone (../hve-core/.github/...), or any non-workspace-root installation, the AI follows these literal paths and fails to find the referenced files. The hve-core-location.instructions.md fallback guidance exists but is not reliably followed by the AI when a literal path is present.

Note: docs/templates/ are correctly packaged in the VSIX extension. References to those files using file-relative paths (e.g., ../../docs/templates/brd-template.md) resolve correctly and do not need changes (both in extension packaging and plugin folder distribution).

Problem

Artifacts instruct the AI to read or reference files using paths anchored at the workspace root:

Read `.github/instructions/design-thinking/dt-coaching-identity.instructions.md`

When installed via extension, the file's actual disk location is something like:

/home/user/.vscode-server-insiders/data/User/globalStorage/ise-hve-essentials.hve-core/.github/agents/design-thinking/dt-coach.agent.md

The AI resolves .github/instructions/... relative to the workspace root, not to the artifact's location on disk, so the file is not found.

Affected Files

These files contain workspace-root-anchored paths in prose (e.g., .github/instructions/...) rather than file-relative paths. Files using correct relative paths like ../../docs/templates/... or ../../instructions/... are not affected.

Proposed Solution

Replace prose paths with #file: directives. VS Code resolves #file: relative to the file's disk location, so the reference works regardless of installation method. Convert:

<!-- Before -->
Read `.github/instructions/design-thinking/dt-coaching-identity.instructions.md`
<!-- After -->
Read #file:../../instructions/design-thinking/dt-coaching-identity.instructions.md

Related Issues

• fix: AI generated .copilot-tracking files produce broken relative paths flooding VS Code Problems tab #698 — Generated .copilot-tracking files produce broken relative paths (symptom-level sibling)
• feat: Reorganize agents, instructions, prompts, and skills into collection-based subdirectories #643 — Reorganize artifacts into collection-based subdirectories (structural coordination)
• feat(extension): Update extension packaging to distribute skills #251 — Extension packaging to distribute skills (same distribution concern)
• fix: Broken #file: directives and markdown links after collection directory reorg #742 — Broken #file: directives and markdown links after collection directory reorg (related path fixes)

Acceptance Criteria

• No AI artifact in a distributed collection uses a hardcoded workspace-root .github/ path in prose text where the AI is expected to resolve it as a file reference, when used in prose the .github/ is acceptable as regex search can retrieve the file, but not when using #file vs code directive
• All file references use file-relative paths (resolving from the artifact's own disk location) or are converted to descriptive text, unless in prose
• hve-core-location.instructions.md is evaluated for strengthening or replacement