Description

Distributed AI artifacts contained hardcoded hve-core paths, npm scripts, template references, and branding that broke or confused when installed via extension or plugin in consumer repositories. This PR applied a two-phase migration across 15 files: hve-core-specific content moved into copilot-instructions.md as the canonical reference, then hardcoded references in distributed artifacts were replaced with discovery-based patterns and template fallbacks.

The code-review-standards agent already demonstrated the correct fallback pattern after #1286 — this PR extended that model to the remaining artifacts identified in a portability audit.

copilot-instructions.md Expansion

Six new subsections were added to .github/copilot-instructions.md preserving hve-core-specific details removed from distributed artifacts. Documentation Templates catalogs all docs/templates/*.md files by consuming agent. Commit Message Scopes maps 14 scopes to repository directories. Frontmatter Schema Validation records schema paths and validation commands. PowerShell Conventions captures the copyright header script, CI helpers module, and test directory patterns. Documentation Operations defines doc-ops scanning targets and validation commands. These sections sit within the existing project-structure and script-operations comment boundaries.

Agent and Prompt Template Fallbacks

Six agent and prompt files received template fallback patterns following the code-review-standards model. Each file now checks template availability and provides a minimal but functional structure when the template is absent.

• code-review-full.agent.md added a best-effort fallback for the full-review-output-format.md template, annotating output with a "template not found" warning
• brd-builder.agent.md made the template path conditional and added a BRD skeleton fallback derived from the agent's own section structure
• adr-creation.agent.md removed the "for HVE Core" qualifier and added a minimal ADR fallback (Title, Status, Context, Decision, Consequences)
• system-architecture-reviewer.agent.md added template availability conditions with the same minimal ADR structure fallback
• ux-ui-designer.agent.md replaced relative template paths with generic docs/templates/ references and discovery-based fallbacks
• incident-response.prompt.md changed the RCA template reference to a conditional with a detailed Google SRE-format fallback structure

Instruction Discovery Patterns

Seven instruction files replaced hardcoded paths and commands with discovery-based guidance that works across any repository structure.

• doc-ops.agent.md underwent a major rewrite, replacing hardcoded directory scanning paths and npm script references with guidance to discover directories and validation commands from package.json
• pester.instructions.md replaced fixed test directory references with discovery patterns and made test execution flexible between npm runners and direct Pester invocation
• commit-message.instructions.md converted the fixed 14-item scope list to discovery-based guidance: "Derive the commit scope from the primary directory affected by the change"
• markdown.instructions.md generalized schema validation references and replaced HVE Core-specific example frontmatter with generic values
• powershell.instructions.md generalized the PSScriptAnalyzer configuration reference to discover .psd1 files rather than hardcoding a path
• bash.instructions.md generalized copyright validation to check package.json instead of referencing a specific npm command
• prompt-builder.instructions.md genericized the subagent path example to a {collection} placeholder and made collection system references conditional

RPI Agent Cleanup

Removed RPI Validator and Implementation Validator from the rpi-agent.agent.md agents frontmatter list in a separate commit. These subagents were never called by the RPI agent — they belong to task-reviewer.agent.md and were leftovers from a prior architecture where the RPI agent had a heavier review phase.

Related Issue(s)

Related to #741 — overlapping scope on hardcoded .github/ path references (tracked separately)
Related to #1286 — precursor fix establishing the template fallback pattern for code-review agents
Related to #643 — structural coordination with collection-based subdirectory reorganization
Closes #1334

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:

Install hve-core artifacts into a consumer repository via the VS Code extension. Then invoke the BRD Builder agent, ADR Creation agent, or incident-response prompt in a repository that does not have docs/templates/ files.

Execution Flow:

1. Agent attempts to read the referenced template file (e.g., docs/templates/brd-template.md).
2. Template not found — agent applies the fallback structure defined in its own instructions.
3. Agent generates the output using the fallback skeleton with a note indicating the template was unavailable.
4. For instruction files (commit-message, pester, etc.), the agent discovers available tools from package.json or repository structure rather than assuming specific npm scripts exist.

Output Artifacts:

Output varies by artifact. When templates are present, behavior is identical to before. When templates are absent, agents produce the same document types using embedded fallback structures. Instruction-driven agents discover available validation commands rather than failing on missing npm scripts.

Success Indicators:

• No "file not found" errors when template files are absent.
• hve-core agents resolve all paths via copilot-instructions.md with no behavior regression.
• Commit message instructions work in any repository by deriving scopes from directory structure.

Testing

• Diff-based analysis verified all 15 changed files match the portability transformation pattern.
• Confirmed all template fallback patterns follow the model from fix: Code Review Standards agent: skill loading and template references fail silently in plugin/extension context #1286 (code-review-standards.agent.md).
• Verified copilot-instructions.md preserves the hve-core-specific content removed from distributed artifacts.
• Security analysis: no sensitive data exposure, no dependency changes, no privilege escalation patterns detected.
• Commit message follows conventional commits format: feat(agents,instructions,prompts): ...
• 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 — markdown-only changes with no testable code)

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
• Docusaurus tests: npm run docs:test

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 scripts modified)

GHCP Artifact Maturity

GHCP Maturity Acknowledgment

• I acknowledge this PR includes non-stable GHCP artifacts
• Non-stable artifacts are intentional for this change