microsoft / microsoft/hve-core
fix: Distributed AI artifacts reference hardcoded workspace-root paths that break in extension and peer-clone installs
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Summary
AI artifacts (agents, instructions, prompts, skills) contain bare `.github/` workspace-root-relative paths in their prose body text. These paths assume the hve-core repository IS the workspace root and break when artifacts load from a VS Code extension install path, a peer clone, or a CLI plugin directory.
The `prompt-builder.instructions.md` portability rules currently cover only `#file:` directives (§ Path Portability) and skill-internal paths (§ File References). **Neither rule covers bare `.github/` path references in prose text** — the pattern responsible for the majority of distribution failures. This gap means new artifacts pass all convention checks while introducing non-portable paths.
## Problem
Artifacts instruct the AI to read or reference files using paths anchored at the workspace root:
```text
Read `.github/instructions/design-thinking/dt-coaching-identity.instructions.md`
```
When installed via extension, the file's actual disk location is:
```text
~/.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 the artifact's disk location, so the referenced file is not found. The `hve-core-location.instructions.md` fallback exists but is not reliably followed when a literal path is present.
## Scope
Full inventory across distributed artifact types:
| Artifact type | Files | Instances | Examples |
|---|---|---|---|
| Agents | 20 | ~60 | dt-coach, rpi-agent, task-implementor, security-planner, rai-planner, sssc-planner, doc-ops, pr-review |
| Instructions | 8 | ~12 | dt-canonical-deck, security/identity, pull-request, jira-backlog-* |
| Prompts | 3 | ~9 | dt-canonical-deck, dt-method-next, github-add-issue |
| Skills | 2 | ~7 | customer-card-render, powerpoint (excluding installer which is compliant by design) |
| **Total** | **33** | **~88** | |
Affected agents (20 files)
- `.github/agents/design-thinking/dt-coach.agent.md` — 10 instances
- `.github/agents/hve-core/task-implementor.agent.md` — 4
- `.github/agents/hve-core/rpi-agent.agent.md` — 5
- `.github/agents/hve-core/task-planner.agent.md` — 2
- `.github/agents/hve-core/task-researcher.agent.md` — 2
- `.github/agents/hve-core/task-reviewer.agent.md` — 1
- `.github/agents/hve-core/doc-ops.agent.md` — 8
- `.github/agents/hve-core/pr-review.agent.md` — 1
- `.github/agents/hve-core/subagents/prompt-updater.agent.md` — 2
- `.github/agents/hve-core/subagents/prompt-evaluator.agent.md` — 2
- `.github/agents/hve-core/subagents/researcher-subagent.agent.md` — 1
- `.github/agents/hve-core/subagents/phase-implementor.agent.md` — 1
- `.github/agents/hve-core/subagents/implementation-validator.agent.md` — 1
- `.github/agents/security/security-planner.agent.md` — 8
- `.github/agents/security/sssc-planner.agent.md` — 7
- `.github/agents/security/security-reviewer.agent.md` — 4
- `.github/agents/rai-planning/rai-planner.agent.md` — 9
- `.github/agents/project-planning/system-architecture-reviewer.agent.md` — 2
- `.github/agents/jira/jira-prd-to-wit.agent.md` — 4
- `.github/agents/jira/jira-backlog-manager.agent.md` — 2
- `.github/agents/coding-standards/code-review-standards.agent.md` — 1
- `.github/agents/project-planning/adr-creation.agent.md` — (PR #1554)
Affected instructions (8 files)
- `.github/instructions/design-thinking/dt-canonical-deck.instructions.md` — 2
- `.github/instructions/security/identity.instructions.md` — 1
- `.github/instructions/hve-core/pull-request.instructions.md` — 3
- `.github/instructions/jira/jira-backlog-planning.instructions.md` — 1
- `.github/instructions/jira/jira-wit-planning.instructions.md` — 1
- `.github/instructions/jira/jira-backlog-discovery.instructions.md` — 1
- `.github/instructions/jira/jira-backlog-update.instructions.md` — 1
- `.github/instructions/github/github-backlog-triage.instructions.md` — 1
Affected prompts (3 files)
- `.github/prompts/design-thinking/dt-canonical-deck.prompt.md` — 7
- `.github/prompts/design-thinking/dt-method-next.prompt.md` — 1
- `.github/prompts/github/github-add-issue.prompt.md` — 1
Affected skills (2 files, excluding installer)
- `.github/skills/experimental/customer-card-render/SKILL.md` — 6
- `.github/skills/experimental/powerpoint/SKILL.md` — 1
## Convention Gap in prompt-builder.instructions.md
The **Path Portability** section (line ~473) covers only `#file:` directive syntax:
> Never use absolute paths or `.github/` prefix in `#file:` references.
The **Skill File References** section (line ~325) adds a skill-specific rule:
> All paths within a skill must be relative to the skill root, never repo-root-relative.
**Missing rule**: No convention prohibits bare `.github/` paths in agent, instruction, or prompt prose text where the AI is expected to resolve and read the referenced file. This gap allows new artifacts to pass all checks while introducing non-portable references. The rule should apply to all distributed artifact types, not just skills and `#file:` directives.
## Proposed Solution
1. **Update `prompt-builder.instructions.md`** — Add a prose-path portability rule to the Path Portability section covering all artifact types. Bare `.github/` paths are acceptable only as descriptive documentation (e.g., explaining directory structure); they must not appear as operational references the AI is expected to resolve as file reads.
2. **Convert operational `.github/` paths** across 33 files using one of:
- `#file:` relative directives (preferred for cross-file loads)
- Relative `../` paths from the artifact's location
- Semantic skill invocation (for script paths — describe intent, let skill matching handle resolution)
- Descriptive text (when referencing conventions rather than requesting file reads)
3. **Evaluate `hve-core-location.instructions.md`** for strengthening or replacement as a fallback mechanism.
## Exclusions
These patterns are **not** portability violations and should remain as-is:
| Pattern | Reason |
|---|---|
| `applyTo` frontmatter globs | Glob patterns, not file references |
| Regex patterns | Pattern matching, not path resolution |
| Documentation tables describing directory structure | Informational, not operational |
| Relative markdown links (`../../../`) | Already resolve correctly |
| Diff header examples | Git output examples |
| Installer skill `.github/` references | Target-path references by design |
## Related Issues
- #1334 (closed) — Comprehensive portability audit for `scripts/`, `npm run`, `docs/templates/` paths (parent of #1336–#1339)
- #742 (closed) — Broken `#file:` directives after collection directory reorg
- #767 (closed) — Standardized script path references in SKILL.md files
- #1286 (closed) — Code Review Standards silent failures in plugin/extension context
- #785 (open) — Frontmatter formatter error in Copilot CLI
- #1300 (open) — Documentation needs updating after agent path resolution change
- #698 (closed) — Generated `.copilot-tracking` files with broken relative paths
- PR #1554 — ADR Creation agent review that surfaced the scope of this issue
## Acceptance Criteria
- [ ] `prompt-builder.instructions.md` includes a rule prohibiting bare `.github/` operational paths in all distributed artifact types (agents, instructions, prompts, skills)
- [ ] No distributed artifact uses a bare `.github/` path where the AI is expected to resolve it as a file read
- [ ] All operational file references use file-relative paths, `#file:` directives, or semantic skill invocation
- [ ] `hve-core-location.instructions.md` is evaluated for strengthening or replacement
- [ ] Installer skill references are explicitly excluded from the convention (target-path by design)
Contributor guide
Assessment
This issue has not been assessed yet.