Merge remote-tracking branch 'origin/main' into feature/azure-ai-projects/2.3.0

Author: dargilco

.github/skills/azsdk-common-prepare-release-plan/SKILL.md

@@ -23,6 +23,7 @@ DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedba
 - Do not display Azure DevOps work item URLs; only provide the Release Plan Link and ID.
 - Require an API spec PR link or a TypeSpec project path before creating or updating a plan.
 - Validate that the spec PR repository matches the requested API release type before creation.
+- Release plan tools accept **either** a Release Plan ID or an Azure DevOps work item ID — pass whichever the user provides. Each tool resolves the value automatically (trying it as a Release Plan ID first, then as a work item ID), so you do not need to call `azure-sdk-mcp:azsdk_get_release_plan` first just to translate one ID into the other.
 
 ## MCP Tools
 
@@ -116,10 +117,10 @@ DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedba
 
 **Steps**:
 
-1. **Identify Plan** — Get the release plan work item ID from the user.
+1. **Identify Plan** — Get the Release Plan ID or work item ID from the user (either is accepted).
 2. **Identify TypeSpec Project** — Get or confirm the TypeSpec project path.
 3. **Update** — Run `azure-sdk-mcp:azsdk_update_sdk_details_in_release_plan` with:
-   - `releasePlanWorkItemId` (required)
+   - `workItemId` (required — accepts either the Release Plan ID or the work item ID)
    - `typeSpecProjectPath` (required)
 
 **Tool**: `azure-sdk-mcp:azsdk_update_sdk_details_in_release_plan`
@@ -147,12 +148,12 @@ DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedba
 
 **Steps**:
 
-1. **Identify Plan** — Get the work item ID or release plan ID.
+1. **Identify Plan** — Get the Release Plan ID or work item ID from the user (either is accepted).
 2. **Collect PR Info** — Get the SDK pull request URL and language from the user.
 3. **Link** — Run `azure-sdk-mcp:azsdk_link_sdk_pull_request_to_release_plan` with:
    - `pullRequestUrl` (required)
    - `language` (required — e.g., ".NET", "Java", "JavaScript", "Python", "Go")
-   - `workItemId` or `releasePlanId`
+   - `workItemId` or `releasePlanId` (either accepts the Release Plan ID or the work item ID)
 4. **Repeat** — If multiple SDK PRs exist for different languages, repeat for each.
 
 **Tool**: `azure-sdk-mcp:azsdk_link_sdk_pull_request_to_release_plan`
@@ -174,5 +175,5 @@ DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedba
 
 - Requires `azure-sdk-mcp` server; no CLI fallback — prompt user to configure MCP if unavailable.
 - If creation fails, verify spec PR URL and Service Tree IDs.
-- If update fails, ensure the work item ID or release plan ID is correct and the plan is not already abandoned.
+- If update fails, ensure the Release Plan ID or work item ID is correct and the plan is not already abandoned.
 - If linking fails, verify the SDK PR URL is valid and the language matches a supported value.

.github/skills/azsdk-common-prepare-release-plan/evals/eval.yaml

@@ -39,6 +39,18 @@ stimuli:
         config:
           substring: "release plan"
 
+  # Regression for issue #15988: when the user provides a Release Plan ID, the
+  # agent can pass it directly to azsdk_update_sdk_details_in_release_plan. The
+  # tool resolves either a Release Plan ID or a work item ID, so the agent should
+  # NOT need a separate azsdk_get_release_plan call just to translate the ID.
+  - name: release-plan-resolve-work-item-id-001
+    prompt: "Update the SDK details in release plan 50001 for the TypeSpec project specification/contosowidgetmanager/Contoso.WidgetManager."
+    graders:
+      - type: tool-calls
+        config:
+          required:
+            - name: azure-sdk-mcp-azsdk_update_sdk_details_in_release_plan
+
   - name: release-plan-negative-001
     prompt: "Release the azure-mgmt-compute Python package to PyPI now."
     graders:

.github/skills/azsdk-common-prepare-release-plan/references/release-plan-details.md

@@ -2,6 +2,19 @@
 
 > **CRITICAL**: Do not mention or display Azure DevOps work item links/URLs. Only provide Release Plan Link and Release Plan ID to the user. All manual updates must be made through the Release Planner Tool (https://aka.ms/sdk-release-planner).
 
+## Release Plan ID vs Work Item ID
+
+A release plan has two distinct identifiers:
+
+- **Release Plan ID**: the value users typically refer to (e.g. in a prompt), shown in the Release Planner.
+- **Work Item ID**: the Azure DevOps work item backing the release plan.
+
+The release plan tools (update release plan, update SDK details, run SDK
+generation, link SDK PR) accept **either** value — pass whichever the user gives
+you. Each tool resolves the supplied number automatically, trying it as a
+Release Plan ID first and then as a work item ID, so you do **not** need to run
+`azsdk_get_release_plan` first just to translate one ID into the other.
+
 ## Required Information
 
 Collect these details (do not use temporary values):
@@ -25,7 +38,7 @@ If user provides an invalid combination, inform them of the correct pairing.
 
 To update SDK details in the release plan:
 
-- Run `azsdk_update_sdk_details_in_release_plan` with the release plan work item ID and TypeSpec project path
+- Run `azsdk_update_sdk_details_in_release_plan` with the `workItemId` (either the Release Plan ID or the work item ID is accepted) and TypeSpec project path.
 
 ## Namespace Approval (Management Plane Only)
 
@@ -40,4 +53,4 @@ For first release of management plane SDK:
 If SDK PRs exist:
 
 1. Ensure GitHub CLI authentication (`gh auth login`)
-2. Run `azsdk_link_sdk_pull_request_to_release_plan` for each PR
+2. Run `azsdk_link_sdk_pull_request_to_release_plan` for each PR, passing the Release Plan ID or work item ID as `workItemId` (or as `releasePlanId`) — either value is accepted.

.github/skills/create-package-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-package-skill
-description: 'Interactive wizard that walks service teams through creating a package-specific skill for their Azure SDK package. Scans the package, detects customization patterns, scaffolds a SKILL.md with references, validates with vally lint, and registers in find-package-skill. WHEN: create package skill; add service skill; bootstrap skill for package; new package skill; skill for my SDK package; write skill for search; write skill for cosmos.'
+description: 'Interactive wizard that walks service teams through creating a package-specific skill for their Azure SDK package. Scans the package, detects customization patterns, scaffolds a SKILL.md with references, and validates with vally lint. The skill is placed inside the package''s .github/skills/ directory so find-package-skill discovers it automatically. WHEN: create package skill; add service skill; bootstrap skill for package; new package skill; skill for my SDK package; write skill for search; write skill for cosmos.'
 ---
 
 # Create Package Skill Wizard
@@ -33,7 +33,7 @@ Run each phase in order. **Progressive loading:** Read only the current phase fi
 | **Phase 1** | 📝 Scaffold SKILL.md — generate skill with step-by-step post-regen workflow (Option A) or reference-manual structure (Option B) | [phases/01-scaffold-skill.md](phases/01-scaffold-skill.md) |
 | **Phase 2** | 📚 Generate References — create customizations.md (required) and optionally architecture.md | [phases/02-generate-references.md](phases/02-generate-references.md) |
 | **Phase 3** | Validate -- run vally lint | [phases/03-validate.md](phases/03-validate.md) |
-| **Phase 4** | 📋 Register — add to find-package-skill table | [phases/04-register.md](phases/04-register.md) |
+| **Phase 4** | 📋 Finalize — confirm discoverable location, summarize | [phases/04-finalize.md](phases/04-finalize.md) |
 
 ## Guardrails
 

.github/skills/create-package-skill/phases/03-validate.md

@@ -34,13 +34,13 @@ If over budget, split content into additional reference files (for example, brea
 ## Step 3 — DECIDE
 
 Present validation results. If all pass:
-Question: "Validation passed. Proceed to register the skill?"
+Question: "Validation passed. Proceed to finalize the skill?"
 
 If failures exist, present them and ask:
 Question: "These issues need fixing. Fix now, or skip validation?"
 
 📍 **Phase 3 complete** | Validation: pass/fail | Next: Phase 4
 
 ---
-## → Next: Phase 4 — Register
-Read [04-register.md](04-register.md) and begin immediately.
+## → Next: Phase 4 — Finalize
+Read [04-finalize.md](04-finalize.md) and begin immediately.

.github/skills/create-package-skill/phases/04-finalize.md

@@ -0,0 +1,47 @@
+# Phase 4: Finalize 📋
+
+> 📍 **Phase 4 — Finalize** | Confirm the skill is in its discoverable location and summarize.
+
+## Step 1 — Confirm discoverable location
+
+Package skills are discovered automatically by `find-package-skill`, which looks
+for a `.github/skills/` directory **inside the package directory**. There is no
+central registry to update — placement *is* registration.
+
+Verify the skill lives at:
+
+```
+sdk/<service>/<package-name>/.github/skills/<package-name>/SKILL.md
+```
+
+If it's there, it will be discovered for that package. No further wiring needed.
+
+## Step 2 — Summary
+
+Print a summary of everything created:
+
+📋 **Package Skill Created**
+
+| Item | Path | Status |
+|---|---|---|
+| SKILL.md | `sdk/<service>/<package-name>/.github/skills/<package-name>/SKILL.md` | Created |
+| architecture.md | `...references/architecture.md` | Created/Skipped |
+| customizations.md | `...references/customizations.md` | Created/Skipped |
+| find-package-skill | discovers automatically via package `.github/skills/` | No action |
+| vally lint | 3/3 checks | Passed |
+
+**Next steps for the service team:**
+1. Fill in any `<!-- TODO -->` sections with domain-specific knowledge.
+2. Test the skill by asking an agent to regenerate your package
+3. Iterate: agent gets something wrong → update skill → test again.
+4. Submit a PR.
+
+**Maintaining your skill:**
+- When your package's customizations change, update the skill.
+- Keep content static — no version numbers or release-specific info
+
+## Step 3 — CONFIRM
+
+Question: "The skill is in place and will be discovered automatically. Anything else to adjust?"
+
+📍 **Phase 4 complete** | Skill in place and discoverable | Wizard done 🎉

.github/skills/create-package-skill/phases/04-register.md

@@ -1,25 +1,31 @@
 ---
 name: find-package-skill
-description: '**UTILITY SKILL** — Must be consulted before making any changes to packages under sdk/. Provides package-specific domain knowledge that prevents common mistakes. WHEN: "add feature to package", "fix bug in package", "modify package code", "regenerate from typespec", "change client library".'
+description: '**UTILITY SKILL** — Must be consulted before making any changes to packages under sdk/. Discovers and loads package-specific domain knowledge that prevents common mistakes. WHEN: "add feature to package", "fix bug in package", "modify package code", "regenerate from typespec", "change client library".'
 ---
 
 # Find Package Skill
 
-Before modifying any SDK package in this monorepo, check this registry to see
-if a package-specific skill exists. Package skills contain tribal knowledge
-(architecture, data flows, type mappings, pitfalls) that prevents common mistakes.
+Some SDK packages in this monorepo have **package-specific skills** — tribal
+knowledge (architecture, data flows, type mappings, pitfalls) that prevents
+common mistakes. Before modifying any SDK package, check whether a skill exists
+for it using the steps below.
 
-Always check this registry before modifying any SDK package — even if you think
-you already know the package well.
+## How to Discover Package Skills
 
-## How to Use
+1. **Determine the package directory.** If you already know the file path you're
+   modifying, extract the package directory from it (e.g., a file at
+   `sdk/search/azure-search-documents/azure/search/documents/_search_client.py`
+   belongs to the package at `sdk/search/azure-search-documents/`). If you only
+   have a package name, search for a matching directory under `sdk/` (package
+   directories are named after the distribution package name, e.g.,
+   `azure-search-documents` → `sdk/search/azure-search-documents/`).
 
-1. Find the package you're modifying in the table below.
-2. Read the SKILL.md at the listed path using the Read tool. Then read all files under the `references/` directory next to it for additional context.
-3. If the package isn't listed, no package-specific skill exists yet — proceed normally.
+2. **Check for a `.github/skills/` directory** inside the package directory. For
+   example, check whether `sdk/search/azure-search-documents/.github/skills/` exists.
 
-## Package Skills
+3. **If it exists**, read every `SKILL.md` found under that directory. If a
+   `references/` subdirectory exists next to a `SKILL.md`, read all files in it
+   too for additional context.
 
-| Package                   | Path                                                                        |
-| ------------------------- | --------------------------------------------------------------------------- |
-| `azure-search-documents` | `sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md` |
+4. **If no `.github/skills/` directory exists** for the package, no
+   package-specific skill has been created yet — proceed normally.

.github/skills/find-package-skill/SKILL.md

@@ -106,27 +106,51 @@ $tempInstallDirectory = Join-Path $tmp "azsdk-install-$($guid)"
 
 # If already installed, use first class version mechanism
 $azsdkCmd = Get-Command -ErrorAction Ignore $packageName
+# Also check the default install directory (~/bin) in case it's not on PATH
+if (!$azsdkCmd -and !$InstallDirectory) {
+    $existingExe = Join-Path $toolInstallDirectory ($IsWindows ? "$packageName.exe" : $packageName)
+    if (Test-Path -PathType Leaf $existingExe) {
+        $azsdkCmd = Get-Command -ErrorAction Ignore $existingExe
+    }
+}
 if ($azsdkCmd -and !$InstallDirectory) {
-    $ErrorActionPreference = "Stop"
-    $upgrade = & $packageName upgrade --check --output json | out-string
-    if (!$LASTEXITCODE) {
-        $ErrorActionPreference = 'Ignore'
-        $localVersion = $upgrade | ConvertFrom-Json -AsHashtable
-        $ErrorActionPreference = 'Stop'
-        if ($localVersion -and $localVersion.old_version -and $localVersion.old_version -eq ($Version ? $Version : $localVersion.new_version)) {
-            log "Version up to date at $($localVersion.old_version)"
-            if ($Run) {
-                $proc = Start-Process -PassThru -WorkingDirectory $RunDirectory -FilePath $azsdkCmd.Path -ArgumentList 'mcp' -NoNewWindow -Wait
-                exit $proc.ExitCode
+    try {
+        $ErrorActionPreference = "Stop"
+        $upgrade = & $azsdkCmd.Path upgrade --check --output json | out-string
+        if (!$LASTEXITCODE) {
+            $ErrorActionPreference = 'Ignore'
+            $localVersion = $upgrade | ConvertFrom-Json -AsHashtable
+            $ErrorActionPreference = 'Stop'
+            if ($localVersion -and $localVersion.old_version -and $localVersion.old_version -eq ($Version ? $Version : $localVersion.new_version)) {
+                log "Version up to date at $($localVersion.old_version)"
+                if ($Run) {
+                    $proc = Start-Process -PassThru -WorkingDirectory $RunDirectory -FilePath $azsdkCmd.Path -ArgumentList 'mcp' -NoNewWindow -Wait
+                    exit $proc.ExitCode
+                }
+                exit 0
+            }
+            if ($localVersion) {
+                log "Version not up to date at " + $localVersion.old_version
+            } else {
+                log "Failed to parse version:"
+                log $upgrade
             }
-            exit 0
+        } elseif ($Run) {
+            # Upgrade check failed (e.g. network error, rate limit, timeout),
+            # but the binary already exists — fall back to running it as-is
+            # rather than attempting a fresh install that will likely also fail.
+            log -warn "Upgrade check failed, falling back to existing installation at '$($azsdkCmd.Path)'"
+            $proc = Start-Process -PassThru -WorkingDirectory $RunDirectory -FilePath $azsdkCmd.Path -ArgumentList 'mcp' -NoNewWindow -Wait
+            exit $proc.ExitCode
         }
-        if ($localVersion) {
-            log "Version not up to date at " + $localVersion.old_version
-        } else {
-            log "Failed to parse version:"
-            log $upgrade
+    }
+    catch {
+        if ($Run) {
+            log -warn "Upgrade check error: $($_.Exception.Message). Falling back to existing installation."
+            $proc = Start-Process -PassThru -WorkingDirectory $RunDirectory -FilePath $azsdkCmd.Path -ArgumentList 'mcp' -NoNewWindow -Wait
+            exit $proc.ExitCode
         }
+        throw
     }
 }
 
@@ -147,6 +171,14 @@ if ($mcpMode) {
     }
     catch {
         log -err $_
+        # If install failed but an existing binary is available, fall back to it
+        # instead of exiting (which causes the MCP client to respawn in a loop).
+        $existingExe = Join-Path $toolInstallDirectory ($IsWindows ? "$packageName.exe" : $packageName)
+        if ($Run -and (Test-Path -PathType Leaf $existingExe)) {
+            log -warn "Installation failed, falling back to existing installation at '$existingExe'"
+            $proc = Start-Process -PassThru -WorkingDirectory $RunDirectory -FilePath $existingExe -ArgumentList 'mcp' -NoNewWindow -Wait
+            exit $proc.ExitCode
+        }
         exit 1
     }
 }