Replace symlink-based local dev with build + --plugin-dir workflow

- Rewrite CONTRIBUTING.md: npm install && npm run build + copilot --plugin-dir ./output
- Delete scripts/src/local/ (setup, verify, test commands) and verify-local.ts
- Update script entries in package.json and scripts/package.json
- Add local dev note to README.md sovereign cloud section
- Update docs/spec/azure-hosted-copilot-sdk.md to reflect removal

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: tmeschter

CONTRIBUTING.md

@@ -46,9 +46,7 @@ Install the Azure plugin:
 
 ## Local Development Setup
 
-To develop and test skills locally, you'll need to link your cloned repository to the installed plugins folder. This allows you to make changes and see them reflected immediately without reinstalling the plugin.
-
-> **Important:** Do NOT run `/plugin install azure@azure-skills` when developing locally. The symlink setup below IS the installation. Running the install command would create a nested copy that shadows your local changes.
+To develop and test skills locally, you build the plugin from source and point Copilot CLI at the build output.
 
 ### 1. Fork and Clone the Repository
 
@@ -58,151 +56,77 @@ git clone https://github.com/YOUR-USERNAME/GitHub-Copilot-for-Azure.git
 cd GitHub-Copilot-for-Azure
 ```
 
-### 2. Install Dependencies
-
-```bash
-cd scripts
-npm install
-cd ..
-```
-
-### 3. Set Up Local Development (Recommended)
+### 2. Build the Plugin
 
-The easiest way to set up local development is using the provided scripts:
+Install dependencies and run the build. This copies the plugin source files into `output/`, stamping version numbers automatically via [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning).
 
 ```bash
-# From the repository root
-cd scripts
-
-# Create the symlink
-npm run local setup
-
-# Verify the setup is correct
-npm run local verify
-```
-
-The setup script will:
-- Create a symlink from `~/.copilot/installed-plugins/azure-skills` to your local `plugin/` folder
-- Handle Windows junction fallback if admin privileges aren't available
-
-The verify script will:
-- Check for nested plugin installs (which shadow your local changes)
-- Test that file changes propagate correctly via the symlink
-- Compare file contents between local and installed locations
-
-Use `npm run local verify --fix` to automatically fix common issues.
-
-### 3b. Manual Symlink Setup (Alternative)
-
-If you prefer to create the symlink manually:
-
-#### Windows (Command Prompt - Run as Administrator)
-
-```cmd
-mklink /J "%USERPROFILE%\.copilot\installed-plugins\azure-skills\azure" "C:\path\to\GitHub-Copilot-for-Azure\plugin"
+npm install
+npm run build
 ```
 
-#### Windows (PowerShell - Run as Administrator)
+The `output/` directory now contains the fully built plugin, ready for use.
 
-```powershell
-New-Item -ItemType Junction -Path "$env:USERPROFILE\.copilot\installed-plugins\azure-skills\azure" -Target "C:\path\to\GitHub-Copilot-for-Azure\plugin"
-```
+### 3. Run Copilot CLI with the Local Plugin
 
-#### macOS / Linux
+Use the `--plugin-dir` flag to point Copilot CLI at your build output:
 
 ```bash
-ln -s ~/path/to/GitHub-Copilot-for-Azure/plugin ~/.copilot/installed-plugins/azure-skills/azure
+copilot --plugin-dir ./output
 ```
 
-> **Note:** Replace the paths above with your actual cloned repository location.
+This loads the locally built plugin instead of any marketplace-installed version.
 
 ### 4. Reloading Skills After Changes
 
-After making changes to skills:
+After making changes to skill files under `plugin/`:
+
+1. **Rebuild** the plugin to update the `output/` directory:
+   ```bash
+   npm run build
+   ```
 
-1. **In an active Copilot CLI session**, run:
+2. **In an active Copilot CLI session**, run:
    ```
    /skills reload
    ```
    This reloads all skills without restarting the CLI.
 
-2. **Alternatively**, restart the GitHub Copilot CLI to pick up changes.
+3. **Alternatively**, restart the Copilot CLI to pick up changes.
 
-> **Tip:** Use `/skills reload` for faster iteration during development.
+> **Tip:** Use `/skills reload` after rebuilding for faster iteration during development.
 
-### 5. Verify the Symlink
+### 5. Testing Pull Requests Locally
 
-Verify that the symlink was created correctly:
-
-```bash
-# Using the verify script (recommended)
-cd scripts
-npm run local verify
-
-# Or manually:
-# Windows (PowerShell)
-Get-ChildItem "$env:USERPROFILE\.copilot\installed-plugins" | Format-List
-
-# macOS / Linux
-ls -la ~/.copilot/installed-plugins/
-```
-
-You should see `azure-skills` pointing to your cloned repository's `plugin` folder.
-
-### 6. Remove an Existing Symlink (If Needed)
-
-If you need to remove or recreate a symlink:
-
-#### Windows (Command Prompt - Run as Administrator)
-```cmd
-rmdir "%USERPROFILE%\.copilot\installed-plugins\azure-skills"
-```
-
-#### Windows (PowerShell - Run as Administrator)
-```powershell
-Remove-Item "$env:USERPROFILE\.copilot\installed-plugins\azure-skills" -Force
-```
-
-#### macOS / Linux
-```bash
-rm ~/.copilot/installed-plugins/azure-skills
-```
-
-### 7. Testing Pull Requests Locally
-
-Once your symlink is set up, you can quickly test any open pull request by checking out its branch. This is especially useful during code review to verify changes work as expected.
+You can quickly test any open pull request by checking out its branch and building. This is especially useful during code review to verify changes work as expected.
 
 #### Using GitHub CLI
 
 Install the [GitHub CLI](https://cli.github.com/) if you haven't already, then run:
 
 ```bash
 gh pr checkout <PR-NUMBER>
+npm run build
+copilot --plugin-dir ./output
 ```
 
 For example, to test PR #42:
 
 ```bash
 gh pr checkout 42
+npm run build
+copilot --plugin-dir ./output
 ```
 
-This automatically:
-1. Fetches the PR branch from the contributor's fork
-2. Creates a local branch tracking the PR
-3. Updates your symlinked plugin folder with the PR's changes
-
-After checking out, run `/skills reload` in your Copilot CLI session (or restart the CLI) to pick up the changes and test the skill or feature.
-
 #### Switching Back
 
 To return to the main branch after testing:
 
 ```bash
 git checkout main
+npm run build
 ```
 
-> **Tip:** You can also use `gh pr checkout <PR-NUMBER> --force` to discard any local changes and switch to the PR branch.
-
 ---
 
 ## Contributing Skills
@@ -445,11 +369,11 @@ For feature requests, include:
 
 After making changes to a skill:
 
-1. Run `/skills reload` in your Copilot CLI session to reload all skills
-2. Test the skill by asking relevant questions
-3. Verify all referenced documentation and examples work
-
-> **Tip:** Use `/skills reload` instead of restarting the CLI for faster iteration during development.
+1. Rebuild the plugin: `npm run build`
+2. Start Copilot CLI with `copilot --plugin-dir ./output`
+3. Run `/skills reload` if you already have a session open
+4. Test the skill by asking relevant questions
+5. Verify all referenced documentation and examples work
 
 ### Debugging
 

README.md

@@ -74,7 +74,9 @@ By default, the Azure MCP server connects to the Azure Public Cloud. If you use
 
 ### Copilot CLI
 
-After installing the plugin, the skills are installed in `~/.copilot/installed-plugins/` on macOS/Linux (or `%USERPROFILE%\.copilot\installed-plugins\` on Windows). Edit the `<skill_installation_dir>/azure-skills/azure/.mcp.json` file in the installed plugin directory to add the `--cloud` argument:
+After installing the plugin from the marketplace, the skills are installed in `~/.copilot/installed-plugins/` on macOS/Linux (or `%USERPROFILE%\.copilot\installed-plugins\` on Windows). Edit the `<skill_installation_dir>/azure-skills/azure/.mcp.json` file in the installed plugin directory to add the `--cloud` argument:
+
+> **Note:** If you are developing locally using `copilot --plugin-dir ./output`, edit `output/.mcp.json` in your local build output instead.
 
 **Azure China Cloud:**
 

docs/spec/azure-hosted-copilot-sdk.md

@@ -56,14 +56,9 @@ The `azure-hosted-copilot-sdk` skill enables users to build, deploy, and configu
 | `tests/utils/regression-detectors.ts` | Regression detectors (secrets, ACR spirals, port confusion, etc.) | ✅ |
 | `tests/_template/unit.test.ts` | Unit test template for new skills | ✅ |
 
-### Local Dev Tooling — ✅ Complete
+### Local Dev Tooling — 🔄 Replaced
 
-| File | Purpose | Status |
-|------|---------|--------|
-| `scripts/src/local/cli.ts` | Local development CLI (`npm run local`) | ✅ |
-| `scripts/src/local/commands/setup.ts` | Plugin + MCP server registration | ✅ |
-| `scripts/src/local/commands/verify.ts` | Health checks for plugin and MCP servers | ✅ |
-| `scripts/src/local/commands/test.ts` | Live validation of the local plugin | ✅ |
+The local development scripts (`scripts/src/local/`) have been replaced by the Gulp build system. Developers now run `npm run build` at the repo root and use `copilot --plugin-dir ./output` to test locally.
 
 ### What Changed in This PR
 

package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "build": "gulp",
     "tokens": "cd scripts && npm run tokens --",
-    "verify-local": "cd scripts && npm run verify-local",
+    "verify-local": "echo 'Removed: use npm run build + copilot --plugin-dir ./output instead'",
     "test": "cd scripts && npm test",
     "test:skills": "cd tests && npm test --",
     "test:skills:integration": "cd tests && npm run test:integration --",

scripts/package.json

@@ -8,10 +8,10 @@
     "checkCopilotCliCharBudget": "node --import tsx src/copilot-cli-char-budget.ts",
     "checkPluginVersionPr": "node --import tsx src/check-plugin-version-pr.ts",
     "tokens": "node --import tsx src/tokens/cli.ts",
-    "local": "node --import tsx src/local/cli.ts",
+    "local": "echo 'Removed: use npm run build at repo root + copilot --plugin-dir ./output instead'",
     "references": "node --import tsx src/references/cli.ts",
     "frontmatter": "node --import tsx src/frontmatter/cli.ts",
-    "verify-local": "node --import tsx src/verify-local.ts",
+    "verify-local": "echo 'Removed: use npm run build at repo root + copilot --plugin-dir ./output instead'",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",