Summary

Distributed AI artifacts (agents, instructions, prompts) contain hve-core-specific references that break, confuse, or degrade when installed in consumer repositories via the VS Code extension or plugin system. A portability audit identified 8 categories of non-portable references across 30+ files, with a two-phase migration plan to fix them.

Related: #741 (covers workspace-root .github/ path references — a subset of this work)

Problem

When a developer installs hve-core artifacts via extension into a repos with React SPA, C# backend, or Python, or other repo, the following categories of references fail:

The code-review-standards agent already demonstrates the correct fallback pattern ("If the file is not found, apply a best-effort structure") after #1286 was fixed. This issue extends that pattern to remaining artifacts.

Proposed Solution

A two-phase migration ensures hve-core retains identical behavior while distributed artifacts become portable:

Phase 1: Add hve-core-specific content to copilot-instructions.md

Add ~54 lines across 6 new subsections to .github/copilot-instructions.md. These sections preserve hve-core-specific paths, npm scripts, and conventions that will be removed from distributed artifacts. Some content already exists in copilot-instructions.md (npm scripts, scripts organization, PowerShell testing) and only needs cross-referencing.

New subsections needed:

1. Documentation Templates — maps docs/templates/*.md files to their consuming agents
2. Documentation Output Conventions — maps PRDs to docs/prds/, BRDs to docs/brds/, etc.
3. Commit Message Scopes — maps scopes like (agents), (scripts), (extension) to directories
4. Frontmatter Schema Validation — records scripts/linting/schemas/ path and validation command
5. PowerShell Conventions — records copyright header script, CI helpers module, test directory patterns
6. Documentation Operations — records doc-ops scanning targets and validation commands

Phase 2: Replace hardcoded references in distributed artifacts with discoverable patterns

For each distributed artifact, replace hve-core-specific content with generic language:

Files to edit

Phase 1 (copilot-instructions.md only):

• .github/copilot-instructions.md — add 6 new subsections

Phase 2 (18 distributed artifact edits):

• .github/agents/coding-standards/code-review-full.agent.md — template fallback
• .github/agents/project-planning/brd-builder.agent.md — template fallback, output dir
• .github/agents/project-planning/ux-ui-designer.agent.md — template fallback
• .github/agents/project-planning/adr-creation.agent.md — template fallback, output dir, remove "for HVE Core"
• .github/agents/project-planning/system-architecture-reviewer.agent.md — template fallback, output dir
• .github/agents/project-planning/prd-builder.agent.md — output dir
• .github/agents/hve-core/doc-ops.agent.md — npm scripts, directory scanning, logs
• .github/instructions/coding-standards/powershell/pester.instructions.md — script paths, npm scripts
• .github/instructions/coding-standards/powershell/powershell.instructions.md — script paths, npm scripts
• .github/instructions/coding-standards/bash/bash.instructions.md — copyright script path
• .github/instructions/hve-core/commit-message.instructions.md — scope list
• .github/instructions/hve-core/markdown.instructions.md — schema paths, example text
• .github/instructions/hve-core/prompt-builder.instructions.md — collection manifest reference
• .github/prompts/security/incident-response.prompt.md — template fallback
• .github/prompts/security/risk-register.prompt.md — output dir

Acceptance Criteria

• Phase 1: copilot-instructions.md contains all 6 new subsections with hve-core-specific content
• Phase 2: No distributed artifact contains hardcoded hve-core scripts/ paths in runtime instructions
• Phase 2: No distributed artifact contains npm run commands without conditional/discoverable framing
• Phase 2: All agents that reference docs/templates/ files include a missing-file fallback
• Phase 2: Hardcoded output directories replaced with discoverable or configurable patterns
• Phase 2: Commit message scope list uses discoverable approach
• Validation: hve-core agents still resolve all paths via copilot-instructions.md (no behavior regression)
• Validation: npm run lint:md, npm run lint:frontmatter pass after all edits
• Validation: npm run plugin:generate and npm run plugin:validate pass

Out of Scope

• fix: Distributed AI artifacts reference hardcoded workspace-root paths that break in extension and peer-clone installs #741 workspace-root .github/ path-to-#file: conversions (tracked separately)
• SSSC Planner hve-core workflow references (intentional cross-repo reference design)