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

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

@@ -43,7 +43,7 @@ All PR review tracking artifacts reside in `.copilot-tracking/pr/review/{{normal
     review/
       {{normalized_branch_name}}/
         in-progress-review.md      # Living PR review document
-        pr-reference.xml           # Generated via scripts/dev-tools/pr-ref-gen.sh
+        pr-reference.xml           # Generated via pr-ref-gen.sh (see script location in Phase 1)
         handoff.md                 # Finalized PR comments and decisions
 ```
 
@@ -148,7 +148,7 @@ Repeat phases as needed when new information or user direction warrants deeper a
 
 ### Phase 1: Initialize Review
 
-Key tools: `git`, `scripts/dev-tools/pr-ref-gen.sh`, workspace file operations
+Key tools: `git`, `pr-ref-gen.sh` (with fallback resolution), workspace file operations
 
 #### Step 1: Normalize Branch Name
 
@@ -160,7 +160,47 @@ Create the PR tracking directory `.copilot-tracking/pr/review/{{normalized_branc
 
 #### Step 3: Generate PR Reference
 
-Generate `pr-reference.xml` using `./scripts/dev-tools/pr-ref-gen.sh --output "{{tracking_directory}}/pr-reference.xml"`. Pass additional flags such as `--base` when the user specifies one.
+Locate and execute the PR reference script using environment-specific fallback patterns.
+
+**For Unix-like shells (bash/zsh)**:
+
+```bash
+# Try local first, then extension
+SCRIPT_PATH="./scripts/dev-tools/pr-ref-gen.sh"
+if [ ! -f "$SCRIPT_PATH" ]; then
+  SCRIPT_PATH=$(find ~/.vscode*/extensions -name "pr-ref-gen.sh" 2>/dev/null | head -1)
+fi
+
+if [ -z "$SCRIPT_PATH" ] || [ ! -f "$SCRIPT_PATH" ]; then
+  echo "Error: pr-ref-gen.sh not found. Checked ./scripts/dev-tools and VS Code extensions under ~/.vscode*/extensions." >&2
+  exit 1
+fi
+
+"$SCRIPT_PATH" --output "{{tracking_directory}}/pr-reference.xml"
+```
+
+**For Windows PowerShell**:
+
+```powershell
+# Try local first, then extension
+$ScriptPath = "./scripts/dev-tools/Generate-PrReference.ps1"
+if (-not (Test-Path $ScriptPath)) {
+  $ScriptPath = Get-ChildItem -Path "$HOME/.vscode*/extensions" -Filter "Generate-PrReference.ps1" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+}
+
+if (-not $ScriptPath) {
+  Write-Error "Error: Generate-PrReference.ps1 not found. Checked ./scripts/dev-tools and VS Code extensions under ~/.vscode*/extensions."
+  exit 1
+}
+
+# Generate reference to default location
+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
+```
+
+Pass additional flags such as `--base-branch` (bash) or `-BaseBranch` (PowerShell) when the user specifies one.
 
 #### Step 4: Seed Tracking Document
 

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

@@ -60,6 +60,46 @@ Git operations via `run_in_terminal`:
 
 Workspace utilities: `list_dir`, `read_file`, `grep_search`
 
+**Script path resolution**: Use environment-specific fallback patterns.
+
+**For Unix-like shells (bash/zsh)**:
+
+```bash
+# Try local first, then extension
+SCRIPT_PATH="./scripts/dev-tools/pr-ref-gen.sh"
+if [ ! -f "$SCRIPT_PATH" ]; then
+  SCRIPT_PATH=$(find ~/.vscode*/extensions -name "pr-ref-gen.sh" 2>/dev/null | head -1)
+fi
+
+if [ -z "$SCRIPT_PATH" ] || [ ! -f "$SCRIPT_PATH" ]; then
+  echo "Error: pr-ref-gen.sh not found. Checked ./scripts/dev-tools and VS Code extensions under ~/.vscode*/extensions." >&2
+  exit 1
+fi
+
+"$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output pr-reference.xml
+```
+
+**For Windows PowerShell**:
+
+```powershell
+# Try local first, then extension
+$ScriptPath = "./scripts/dev-tools/Generate-PrReference.ps1"
+if (-not (Test-Path $ScriptPath)) {
+  $ScriptPath = Get-ChildItem -Path "$HOME/.vscode*/extensions" -Filter "Generate-PrReference.ps1" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+}
+
+if (-not $ScriptPath) {
+  Write-Error "Error: Generate-PrReference.ps1 not found. Checked ./scripts/dev-tools and VS Code extensions under ~/.vscode*/extensions."
+  exit 1
+}
+
+# Generate reference to default location
+pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"
+
+# Move generated file to PR planning directory
+Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination ".copilot-tracking/pr/new/{{normalized branch name}}/pr-reference.xml" -Force
+```
+
 Persist all tool output into planning files per ado-wit-planning.instructions.md.
 
 ## Tracking Directory Structure
@@ -367,7 +407,7 @@ Execute without presenting details to user:
 3. Initialize `planning-log.md` with Phase-1 status.
 4. Check if `pr-reference.xml` exists:
    * If exists: Use existing file silently.
-   * If not exists: Generate using `scripts/dev-tools/pr-ref-gen.sh` with optional `--no-md-diff` flag if `${input:includeMarkdown}` is false.
+   * If not exists: Generate using script path resolution with fallback patterns (see Tooling section) with optional `--no-md-diff` flag if `${input:includeMarkdown}` is false.
 5. Read complete `pr-reference.xml`. For files exceeding 2000 lines, read in 1000-2000 line chunks, capturing complete commit boundaries before advancing to the next chunk.
 6. Log artifact in `planning-log.md` with status `Complete`.
 

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

@@ -64,8 +64,46 @@ Add an **External References** section to work item descriptions when authoritat
 
 **Git context** (when `${input:includeBranchChanges}` is `true` and no documents exist):
 
-* `run_in_terminal`: Generate diff XML via `scripts/dev-tools/pr-ref-gen.sh --base-branch "${input:baseBranch}" --output "<planning-folder>/git-branch-diff.xml"`
 * Sync remote first: `git fetch <remote> <branch> --prune`
+* `run_in_terminal`: Generate diff XML using environment-specific fallback patterns:
+
+  **For Unix-like shells (bash/zsh)**:
+
+  ```bash
+  # Try local first, then extension
+  SCRIPT_PATH="./scripts/dev-tools/pr-ref-gen.sh"
+  if [ ! -f "$SCRIPT_PATH" ]; then
+    SCRIPT_PATH=$(find ~/.vscode*/extensions -name "pr-ref-gen.sh" 2>/dev/null | head -1)
+  fi
+
+  if [ -z "$SCRIPT_PATH" ] || [ ! -f "$SCRIPT_PATH" ]; then
+    echo "Error: pr-ref-gen.sh not found. Checked ./scripts/dev-tools and VS Code extensions under ~/.vscode*/extensions." >&2
+    exit 1
+  fi
+
+  "$SCRIPT_PATH" --base-branch "${input:baseBranch}" --output "<planning-folder>/git-branch-diff.xml"
+  ```
+
+  **For Windows PowerShell**:
+
+  ```powershell
+  # Try local first, then extension
+  $ScriptPath = "./scripts/dev-tools/Generate-PrReference.ps1"
+  if (-not (Test-Path $ScriptPath)) {
+    $ScriptPath = Get-ChildItem -Path "$HOME/.vscode*/extensions" -Filter "Generate-PrReference.ps1" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+  }
+
+  if (-not $ScriptPath) {
+    Write-Error "Error: Generate-PrReference.ps1 not found. Checked ./scripts/dev-tools and VS Code extensions under ~/.vscode*/extensions."
+    exit 1
+  }
+
+  # Generate reference to default location
+  pwsh -File $ScriptPath -BaseBranch "${input:baseBranch}"
+
+  # Move generated file to planning folder
+  Move-Item -Path ".copilot-tracking/pr/pr-reference.xml" -Destination "<planning-folder>/git-branch-diff.xml" -Force
+  ```
 
 **Workspace utilities**: `list_dir`, `read_file`, `grep_search` for artifact location.
 

extension/PACKAGING.md

@@ -23,6 +23,22 @@ extension/
 └── PACKAGING.md          # This file
 ```
 
+## Extension Configuration
+
+### Extension Kind
+
+The extension is configured with `"extensionKind": ["workspace", "ui"]` in `package.json` to support multiple execution contexts:
+
+* **Workspace mode**: Extension runs in the workspace extension host with access to local workspace files, including scripts in `.github/` and `scripts/dev-tools/`
+* **UI mode**: Extension runs in the UI extension host for scenarios where workspace access is restricted
+
+This dual-mode configuration enables script fallback patterns where:
+
+1. Local workspace scripts (e.g., `./scripts/dev-tools/pr-ref-gen.sh`) are used when available
+2. Extension-bundled scripts fall back when workspace access is unavailable (e.g., remote development scenarios)
+
+The configuration ensures the extension works correctly in local workspaces, devcontainers, Codespaces, and other VS Code environments.
+
 ## Prerequisites
 
 Install the VS Code Extension Manager CLI:
@@ -65,11 +81,11 @@ npm run extension:prepare
 
 The preparation script automatically:
 
-- Discovers and registers all chat agents from `.github/agents/`
-- Discovers and registers all prompts from `.github/prompts/`
-- Discovers and registers all instruction files from `.github/instructions/`
-- Updates `package.json` with discovered components
-- Uses existing version from `package.json` (does not modify it)
+* Discovers and registers all chat agents from `.github/agents/`
+* Discovers and registers all prompts from `.github/prompts/`
+* Discovers and registers all instruction files from `.github/instructions/`
+* Updates `package.json` with discovered components
+* Uses existing version from `package.json` (does not modify it)
 
 #### Step 2: Package the Extension
 
@@ -94,13 +110,13 @@ pwsh ./scripts/extension/Package-Extension.ps1 -Version "1.1.0" -DevPatchNumber
 
 The packaging script automatically:
 
-- Uses version from `package.json` (or specified version)
-- Optionally appends dev patch number for pre-release builds
-- Copies required `.github` directory
-- Copies `scripts/dev-tools` directory (developer utilities)
-- Packages the extension using `vsce`
-- Cleans up temporary files
-- Restores original `package.json` version if temporarily modified
+* Uses version from `package.json` (or specified version)
+* Optionally appends dev patch number for pre-release builds
+* Copies required `.github` directory
+* Copies `scripts/dev-tools` directory (developer utilities)
+* Packages the extension using `vsce`
+* Cleans up temporary files
+* Restores original `package.json` version if temporarily modified
 
 ### Manual Packaging (Legacy)
 
@@ -145,15 +161,15 @@ vsce publish --packagePath "$VSIX_FILE"
 
 The `extension/.vscodeignore` file controls what gets packaged. Currently included:
 
-- `.github/agents/**` - All custom agent definitions
-- `.github/prompts/**` - All prompt templates
-- `.github/instructions/**` - All instruction files
-- `docs/templates/**` - Document templates used by agents (ADR, BRD, Security Plan)
-- `scripts/dev-tools/**` - Developer utilities (PR reference generation)
-- `package.json` - Extension manifest
-- `README.md` - Extension description
-- `LICENSE` - License file
-- `CHANGELOG.md` - Version history
+* `.github/agents/**` - All custom agent definitions
+* `.github/prompts/**` - All prompt templates
+* `.github/instructions/**` - All instruction files
+* `docs/templates/**` - Document templates used by agents (ADR, BRD, Security Plan)
+* `scripts/dev-tools/**` - Developer utilities (PR reference generation)
+* `package.json` - Extension manifest
+* `README.md` - Extension description
+* `LICENSE` - License file
+* `CHANGELOG.md` - Version history
 
 ## Testing Locally
 
@@ -243,11 +259,11 @@ See [Agent Maturity Levels](../docs/contributing/ai-artifacts-common.md#maturity
 
 ## Notes
 
-- The `.github`, `docs/templates`, and `scripts/dev-tools` folders are temporarily copied during packaging (not permanently stored)
-- `LICENSE` and `CHANGELOG.md` are copied from root during packaging and excluded from git
-- Only essential extension files are included (agents, prompts, instructions, templates, dev-tools)
-- Non-essential files are excluded (workflows, issue templates, agent installer, etc.)
-- The root `package.json` contains development scripts for the repository
+* The `.github`, `docs/templates`, and `scripts/dev-tools` folders are temporarily copied during packaging (not permanently stored)
+* `LICENSE` and `CHANGELOG.md` are copied from root during packaging and excluded from git
+* Only essential extension files are included (agents, prompts, instructions, templates, dev-tools)
+* Non-essential files are excluded (workflows, issue templates, agent installer, etc.)
+* The root `package.json` contains development scripts for the repository
 
 ---
 

extension/package.json

@@ -1,6 +1,7 @@
 {
   "name": "hve-core",
   "displayName": "HVE Core",
+  "extensionKind": ["workspace", "ui"],
   "version": "2.0.1",
   "description": "AI-powered chat agents, prompts, and instructions for hybrid virtual environments",
   "publisher": "ise-hve-essentials",