fix: Distributed AI artifacts reference hardcoded workspace-root paths that break in extension and peer-clone installs

[katriendg]

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:

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

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

~/.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 feat(agents): upgrade ADR Planner with phased identity and adr-author skill #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

• fix(agents,instructions): make distributed artifacts portable by replacing hve-core-specific references with discoverable patterns #1334 (closed) — Comprehensive portability audit for scripts/, npm run, docs/templates/ paths (parent of fix: Add portability context subsections to .github/copilot-instructions.md #1336–fix: Replace hardcoded hve-core paths in distributed prompt files for cross-repo portability #1339)
• fix: Broken #file: directives and markdown links after collection directory reorg #742 (closed) — Broken #file: directives after collection directory reorg
• chore(skills): standardize script path references in SKILL.md files #767 (closed) — Standardized script path references in SKILL.md files
• fix: Code Review Standards agent: skill loading and template references fail silently in plugin/extension context #1286 (closed) — Code Review Standards silent failures in plugin/extension context
• fix: Frontmatter formatter error using hve-core agents in Copilot CLI #785 (open) — Frontmatter formatter error in Copilot CLI
• docs: update language-skills.md skill loading description after agent path resolution change #1300 (open) — Documentation needs updating after agent path resolution change
• fix: AI generated .copilot-tracking files produce broken relative paths flooding VS Code Problems tab #698 (closed) — Generated .copilot-tracking files with broken relative paths
• PR feat(agents): upgrade ADR Planner with phased identity and adr-author skill #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)

[babadriskobaba-boop]

Hey everyone