fix(extension): add workspace extension kind and script fallback patterns #399

katriendg · 2026-02-03T15:08:06Z

Description

This PR fixes script accessibility issues when using the HVE-Core extension by configuring the extension to run in workspace context and adding cross-platform script fallback patterns. Previously, AI artifacts could not locate scripts packaged with the extension because they only checked local repository paths. The fix ensures scripts are discoverable whether HVE-Core is installed as a repository clone or VS Code extension across Mac, Windows, and WSL environments.

Key Changes:

Extension Configuration: Added extensionKind: ["workspace", "ui"] to extension/package.json to ensure the extension runs on the same filesystem as terminal execution (WSL/remote/local)
- Why workspace kind? When the extension runs in workspace context, it installs at ~/.vscode-server/extensions/ (WSL) or ~/.vscode-remote/extensions/ (Codespaces) instead of Windows-side paths, eliminating path translation issues
- Solves the root cause: Extension files and workspace files are now on the same filesystem
- Addresses issue where Copilot couldn't read instruction files when repo was in WSL but extension on Windows
Script Fallback Patterns: Updated three AI artifacts with environment-specific fallback logic:
- pr-review.agent.md: Added bash and PowerShell fallback patterns for PR reference generation
- ado-create-pull-request.instructions.md: Added script path resolution section with cross-platform patterns
- ado-wit-discovery.instructions.md: Added environment-specific git context tooling
Cross-Platform Support: Fallback patterns use ~/.vscode*/extensions glob to automatically detect:
- ~/.vscode/extensions (local installation)
- ~/.vscode-server/extensions (WSL)
- ~/.vscode-remote/extensions (Codespaces)

Related Issue(s)

Fixes #397

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:

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)

Other:

Script/automation (.ps1, .sh, .py)
Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Select pr-review from the agent picker
"Generate a PR review for my current branch"

Execution Flow:

pr-review agent normalizes branch name
Creates tracking directory at .copilot-tracking/pr/review/{normalized_branch}
Detects environment (bash vs PowerShell)
Tries ./scripts/dev-tools/pr-ref-gen.sh first
Falls back to find ~/.vscode*/extensions -name "pr-ref-gen.sh" if local not found, or Powershell if running on Windows
Generates pr-reference.xml with git diff and commit history
Analyzes changes and creates review document

Output Artifacts:

.copilot-tracking/
  pr/
    review/
      fix-397-ai-scripts-access-extension/
        pr-reference.xml
        in-progress-review.md
        handoff.md

Success Indicators:

Script executes successfully from either local or extension location
pr-reference.xml is created with proper diff content
Works in WSL, local Mac/Windows, and Codespaces environments
No "command not found" or "file not found" errors

For detailed contribution requirements, see:

Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns

Testing

Manual Testing Required:

⚠️ CRITICAL: This extension release MUST be tested in Pre-Release mode first before stable release!

Test Scenarios with extension installed:

WSL Environment (Ubuntu on Windows):
- Install extension in Pre-Release mode
- Clone a test repository in WSL filesystem
- Select pr-review from the agent picker to trigger script fallback
- Verify script is found at ~/.vscode-server/extensions/ise-hve-essentials.hve-core-*/scripts/dev-tools/pr-ref-gen.sh
- Confirm pr-reference.xml is generated successfully
Local Windows (PowerShell):
- Install extension in Pre-Release mode
- Select pr-review from the agent picker
- Verify PowerShell fallback pattern executes correctly
- Confirm Generate-PrReference.ps1 is located and executed
Local Mac/Linux (bash):
- Install extension in Pre-Release mode
- Select pr-review from the agent picker
- Verify bash fallback pattern executes correctly
- Confirm pr-ref-gen.sh is located and executed
GitHub Codespaces:
- Open repository in Codespaces
- Install extension in Pre-Release mode
- Select pr-review from the agent picker
- Verify script is found at ~/.vscode-remote/extensions/
- Confirm successful execution
Repository Clone Method (existing behavior):
- Clone HVE-Core repository
- Verify local ./scripts/dev-tools/pr-ref-gen.sh is used first
- Confirm fallback is not triggered when local scripts exist

Validation Commands:

Before each test, verify extension installation location:

# WSL/Linux/Mac
find ~/.vscode*/extensions -name "pr-ref-gen.sh" 2>/dev/null

# PowerShell
Get-ChildItem -Path "$HOME/.vscode*/extensions" -Filter "Generate-PrReference.ps1" -Recurse

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)

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
Link validation: npm run lint:md-links
PowerShell analysis: npm run lint:ps

Security Considerations

This PR does not contain any sensitive or NDA information
Any new dependencies have been reviewed for security issues
Security-related scripts follow the principle of least privilege

Additional Notes

Why extensionKind: ["workspace", "ui"]?

The extensionKind configuration determines where the extension host process runs:

Kind	Install Location	Best For
`["ui"]`	Windows/Mac (client side)	Window management, decorations
`["workspace"]`	Remote/WSL (workspace side)	Filesystem access, terminals
`["workspace", "ui"]`	Prefers workspace, falls back to UI	Hybrid scenarios

Decision rationale:

Filesystem Alignment: When HVE-Core runs in workspace context, extension files are on the same filesystem as the workspace, eliminating Windows-to-WSL path translation issues
Terminal Execution: Scripts invoked via terminals execute in the workspace context, where the extension is also installed
Instruction File Access: Copilot can read .github/instructions/*.instructions.md files without cross-filesystem barriers
Backward Compatibility: Fallback to UI context ensures extension works in non-remote scenarios

Pre-Release Testing Plan

Why Pre-Release First:

Extension behavior changes when moving from UI-only to workspace-first execution
Script fallback patterns need validation across multiple environments
Potential side effects from extension host context switching

Release Sequence:

Merge this PR to main
Publish extension as Pre-Release v2.1.0-preview to VS Code Marketplace
Conduct testing across WSL, Mac, Windows, Codespaces (1-2 days)
Collect feedback via GitHub Discussions or issue [Task]: Ensure AI Artifacts Have Fallback Access to Packaged Extension Scripts #397
If successful, promote to stable release v2.2.0
If issues found, iterate on fixes and republish preview

Rollback Plan:

If critical issues emerge, revert to v2.0.1 stable and investigate. The repository clone installation method remains unaffected as a fallback.

…n behavior and update agent fallbacks - add fallback patterns to locate pr-ref-gen scripts in extensions - update pr-review agent with environment-specific script resolution - add script path fallback logic to ado-create-pull-request instructions - update ado-wit-discovery with cross-platform script location patterns - configure extension to run in workspace and UI contexts

… generation fallback

github-actions · 2026-02-03T15:08:22Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

codecov-commenter · 2026-02-03T15:09:54Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.38%. Comparing base (6e26282) to head (c65b0a8).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #399      +/-   ##
==========================================
- Coverage   61.41%   61.38%   -0.04%     
==========================================
  Files          17       17              
  Lines        3115     3115              
==========================================
- Hits         1913     1912       -1     
- Misses       1202     1203       +1

Flag	Coverage Δ
pester	`61.38% <ø> (-0.04%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR aims to fix script discoverability when HVE-Core is installed as a VS Code extension (including WSL/remote scenarios) by (1) preferring workspace-side extension execution and (2) adding fallback script path resolution guidance in key AI artifacts.

Changes:

Configure the extension to run in workspace context when available via extensionKind: ["workspace", "ui"].
Add cross-platform fallback patterns (local repo path first, then VS Code extensions folders) for locating PR reference generation scripts.
Update ADO instruction flows and the pr-review agent to reference the new fallback approach.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
extension/package.json	Adds `extensionKind` to prefer workspace-side execution for better filesystem alignment in remote/WSL.
.github/instructions/ado-wit-discovery.instructions.md	Adds bash/PowerShell fallback patterns for generating git diff XML when local scripts aren’t present.
.github/instructions/ado-create-pull-request.instructions.md	Adds a “Script path resolution” section and updates PR-reference generation guidance to use fallbacks.
.github/agents/pr-review.agent.md	Adds fallback logic to locate and run PR reference generation scripts across environments.

.github/agents/pr-review.agent.md

.github/instructions/ado-wit-discovery.instructions.md

.github/instructions/ado-create-pull-request.instructions.md

…or messages and fallback

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Copilot · 2026-02-03T19:29:15Z

.github/instructions/ado-create-pull-request.instructions.md


 Workspace utilities: `list_dir`, `read_file`, `grep_search`

+**Script path resolution**: Use environment-specific fallback patterns.


This file now introduces script fallback resolution below, but the earlier Tooling bullets still instruct running scripts/dev-tools/pr-ref-gen.sh ... directly. To avoid conflicting guidance, update the Tooling bullet list to reference the new script path resolution (or remove the direct-path bullet).

Suggested change

**Script path resolution**: Use environment-specific fallback patterns.

**Script path resolution**: Use environment-specific fallback patterns instead of hardcoding `scripts/dev-tools/pr-ref-gen.sh`. If earlier instructions mention running `scripts/dev-tools/pr-ref-gen.sh` directly, treat this section as the authoritative guidance and use the resolved `SCRIPT_PATH` variable instead.

Copilot · 2026-02-03T19:29:16Z

.github/agents/pr-review.agent.md

+  exit 1
+fi
+
+"$SCRIPT_PATH" --output "{{tracking_directory}}/pr-reference.xml"


{{tracking_directory}} is used as an output path placeholder here, but it is not defined anywhere else in the agent. Use the explicit tracking path (e.g., .copilot-tracking/pr/review/{{normalized_branch_name}}) or define tracking_directory earlier so this command resolves deterministically.

Suggested change

"$SCRIPT_PATH" --output "{{tracking_directory}}/pr-reference.xml"

"$SCRIPT_PATH" --output ".copilot-tracking/pr/review/{{normalized_branch_name}}/pr-reference.xml"

Copilot · 2026-02-03T19:29:16Z

.github/agents/pr-review.agent.md

+pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"
+
+# Move generated file to tracking directory
+Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination "{{tracking_directory}}/pr-reference.xml" -Force


{{tracking_directory}} is referenced in the Move-Item destination, but the agent never defines that placeholder/value. Use the explicit .copilot-tracking/pr/review/{{normalized_branch_name}} path (or define tracking_directory) so the generated pr-reference.xml is moved to the intended location.

Suggested change

Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination "{{tracking_directory}}/pr-reference.xml" -Force

Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination ".copilot-tracking/pr/review/{{normalized_branch_name}}/pr-reference.xml" -Force

Copilot · 2026-02-03T19:29:17Z

.github/agents/pr-review.agent.md

+}
+
+# Generate reference to default location
+pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"


This PowerShell snippet passes -BaseBranch "${input:baseBranch}", but this agent file does not declare any ${input:...} variables. As written, it will likely pass the literal string and fail branch resolution. Only pass -BaseBranch when the user explicitly provided one, otherwise omit it and rely on the script’s default base branch behavior; also quote $ScriptPath when invoking pwsh -File to avoid issues with spaces in paths.

Suggested change

pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"

pwsh -File "$ScriptPath"

Copilot · 2026-02-03T19:29:17Z

.github/instructions/ado-wit-discovery.instructions.md

+  }
+
+  # Generate reference to default location
+  pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"


pwsh -File $ScriptPath should quote $ScriptPath (or use & $ScriptPath) to handle extension install paths that include spaces (common on Windows). Without quoting, PowerShell can split the argument and fail to launch the script.

Suggested change

pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"

pwsh -File "$ScriptPath" -BaseBranch "${input:baseBranch}"

Copilot · 2026-02-03T19:29:17Z

.github/instructions/ado-create-pull-request.instructions.md

+}
+
+# Generate reference to default location
+pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"


pwsh -File $ScriptPath should quote $ScriptPath (or use & $ScriptPath) so the fallback path works when the user profile or extension install path contains spaces. This makes the copy-paste snippet reliable on Windows.

Suggested change

pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"

pwsh -File "$ScriptPath" -BaseBranch "${input:baseBranch}"

Copilot · 2026-02-03T19:29:18Z

.github/instructions/ado-create-pull-request.instructions.md

+  exit 1
+fi
+
+"$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output pr-reference.xml


The bash fallback snippet writes the output to pr-reference.xml in the current working directory. Later phases expect pr-reference.xml to exist inside the planning directory under .copilot-tracking/pr/new/<normalized-branch-name>/, so this will be missed unless the terminal happens to be in that folder. Update the --output path to target the planning directory path used by the workflow.

Suggested change

"$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output pr-reference.xml

OUTPUT_DIR=".copilot-tracking/pr/new/${input:normalizedBranchName}"

mkdir -p "$OUTPUT_DIR"

"$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output "$OUTPUT_DIR/pr-reference.xml"

katriendg added 2 commits February 3, 2026 15:21

fix(instructions): update script path resolution for pr-reference.xml…

f93adc1

… generation fallback

katriendg requested a review from a team as a code owner February 3, 2026 15:08

Copilot AI review requested due to automatic review settings February 3, 2026 15:08

Copilot started reviewing on behalf of katriendg February 3, 2026 15:08 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

chore(instructions): address PR review comments to ensure correct err…

3a01960

…or messages and fallback

nguyena2 approved these changes Feb 3, 2026

View reviewed changes

Merge branch 'main' into fix/397-ai-scripts-access-extension

c65b0a8

Copilot AI review requested due to automatic review settings February 3, 2026 19:22

Copilot started reviewing on behalf of WilliamBerryiii February 3, 2026 19:22 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes


		Workspace utilities: `list_dir`, `read_file`, `grep_search`

		Script path resolution: Use environment-specific fallback patterns.

	"$SCRIPT_PATH" --output "{{tracking_directory}}/pr-reference.xml"
	"$SCRIPT_PATH" --output ".copilot-tracking/pr/review/{{normalized_branch_name}}/pr-reference.xml"

	Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination "{{tracking_directory}}/pr-reference.xml" -Force
	Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination ".copilot-tracking/pr/review/{{normalized_branch_name}}/pr-reference.xml" -Force

	pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"
	pwsh -File "$ScriptPath"

	pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"
	pwsh -File "$ScriptPath" -BaseBranch "${input:baseBranch}"

-"$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output pr-reference.xml
+OUTPUT_DIR=".copilot-tracking/pr/new/${input:normalizedBranchName}"
+mkdir -p "$OUTPUT_DIR"
+"$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output "$OUTPUT_DIR/pr-reference.xml"

fix(extension): add workspace extension kind and script fallback patterns #399

Are you sure you want to change the base?

fix(extension): add workspace extension kind and script fallback patterns #399

Conversation

katriendg commented Feb 3, 2026

Description

Related Issue(s)

Type of Change

Sample Prompts (for AI Artifact Contributions)

Testing

Checklist

Required Checks

AI Artifact Contributions

Required Automated Checks

Security Considerations

Additional Notes

Why extensionKind: ["workspace", "ui"]?

Pre-Release Testing Plan

Uh oh!

github-actions bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

Uh oh!

codecov-commenter commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Feb 3, 2026 •

edited

Loading

codecov-commenter commented Feb 3, 2026 •

edited

Loading