Sync eng/common directory with azure-sdk-tools for PR 11477 (#36699)

* place prompts in common place

* Update eng/common/instructions/azsdk-tools/create-sdk-locally.prompt.md

Co-authored-by: Copilot <[email protected]>

* Update eng/common/instructions/azsdk-tools/verify-namespace-approval.prompt.md

Co-authored-by: Copilot <[email protected]>

* Update eng/common/instructions/azsdk-tools/typespec-to-sdk.prompt.md

Co-authored-by: Copilot <[email protected]>

* Update eng/common/instructions/azsdk-tools/typespec-to-sdk.prompt.md

Co-authored-by: Copilot <[email protected]>

* rename to .instructions.md

* remove uneeded headers

* change to .instructions

* fix

* run to refer to

* relative links fix

---------

Co-authored-by: Juan Ospina <[email protected]>
Co-authored-by: Copilot <[email protected]>

eng/common/instructions/azsdk-tools/check-api-readiness.instructions.md

@@ -0,0 +1,5 @@
+---
+description: 'Check API Readiness for SDK Generation'
+---
+Your goal is to check if API spec pull request is ready for SDK generation. Identify the next action required from user  based on the comments on spec pull request if spec is not ready and notify the user.
+Before running, get spec pull request link for current branch or from user if not available in current context. If pull request has APIView links, then highlight them to user.

eng/common/instructions/azsdk-tools/check-package-readiness.instructions.md

@@ -0,0 +1,34 @@
+---
+description: 'This prompt is designed to check the release readiness of a SDK package.'
+---
+## Goal
+Check the release readiness of an SDK package by collecting the required information from the user and executing the readiness check.
+
+## Instructions
+1. **Collect Required Information**:
+    - Prompt the user for the exact package name
+    - Prompt the user to select the programming language from the following options (case sensitive):
+      - Python
+      - Java
+      - JavaScript
+      - .NET
+      - Go
+
+2. **Execute Readiness Check**:
+    - Use the `CheckPackageReleaseReadiness` tool with the provided package name and selected language
+    - Do not check for existing pull requests to run this step.
+    - Do not ask the user to create a release plan to run this step.
+
+3. **Present Results**:
+    - If the package is ready for release, highlight and provide the link to the release pipeline
+    - If the package is not ready, display the specific issues that need to be resolved
+
+4. **Follow-up Actions**:
+    - Provide clear next steps based on the readiness status
+    - If issues are found, offer guidance on how to resolve them
+
+## Expected User Interaction Flow
+1. Ask: "What is the exact name of the package you want to check for release readiness?"
+2. Ask: "Please select the programming language for this package: Python, Java, JavaScript, .NET, or Go"
+3. Execute the readiness check using the provided information
+4. Display results and next steps

eng/common/instructions/azsdk-tools/create-release-plan.instructions.md

@@ -0,0 +1,55 @@
+# Release Plan Creation Process
+You goal is to create a valid release plan. You must prompt user to provide all required information and all input must match the format and requirement mentioned in step 3 below.
+Follow these steps in order to create or manage a release plan for an API specification pull request:
+
+## Step 1: Validate Prerequisites
+- Check if an API spec pull request is available in the current context
+- If no pull request is available, prompt the user to provide the API spec pull request link
+- Validate that the provided pull request link is accessible and valid
+
+## Step 2: Check Existing Release Plan
+- Use `GetReleasePlanForPullRequest` to check if a release plan already exists for the API spec pull request
+- If a release plan exists:
+    - Display the existing release plan details to the user
+    - Skip to Step 5 (Link SDK Pull Requests)
+- If no release plan exists, proceed to Step 3
+
+## Step 3: Gather Release Plan Information
+Collect the following required information from the user. Do not create a release plan with temporary values. Confirm the values with the user before proceeding to create the release plan.
+If any details are missing, prompt the user accordingly:
+
+- **API Lifecycle Stage**: Must be one of:
+    - Private Preview
+    - Public Preview  
+    - GA (Generally Available)
+- **Service Tree ID**: GUID format identifier for the service in Service Tree. Before creating release plan, always show the value to user and ask them to confirm it's a valid value in service tree.
+- **Product Service Tree ID**: GUID format identifier for the product in Service Tree. Before creating release plan, always show the value to user and ask them to confirm it's a valid value in service tree.
+- **Expected Release Timeline**: Format must be in "Month YYYY"
+- **API Version**: The version of the API being released
+- **SDK Release Type**: Value must be beta or stable.
+    - "beta" for preview API versions
+    - "stable" for GA API versions
+
+## Step 4: Create Release Plan
+- If the user doesn't know the required details, direct them to create a release plan using the release planner
+- Provide this resource: [Release Plan Creation Guide](https://eng.ms/docs/products/azure-developer-experience/plan/release-plan-create)
+- Once all information is gathered, use `CreateReleasePlan` to create the release plan
+- Display the newly created release plan details to the user for confirmation
+- Refer to #file:sdk-details-in-release-plan.instructions.md to identify languages configured in the TypeSpec project and add them to the release plan
+
+## Step 5: Update SDK Details in Release Plan
+- Refer to #file:sdk-details-in-release-plan.instructions.md to add languages and package names to the release plan
+- If the TypeSpec project is for a management plane, refer to #file:verify-namespace-approval.instructions.md if this is first release of SDK.
+
+## Step 6: Link SDK Pull Requests (if applicable)
+- Ask the user if they have already created SDK pull requests locally for any programming language
+- If SDK pull requests exist:
+    - Collect the pull request links from the user
+    - Use `LinkSdkPullRequestToReleasePlan` to link each SDK pull request to the release plan
+    - Confirm successful linking for each SDK pull request
+
+## Step 7: Summary
+- Display a summary of the completed actions:
+    - Release plan status (created or existing)
+    - Linked SDK pull requests (if any)
+    - Next steps or recommendations for the user

eng/common/instructions/azsdk-tools/create-sdk-locally.instructions.md

@@ -0,0 +1,32 @@
+Your goal is to help guide the user to create SDK locally for TypeSpec changes. This is currently supported for **Python** only. User can generate SDK for other languages using SDK generation pipeline.
+## Steps to create Python SDK locally from TypeSpec
+### Step 1: Check for existing azure-sdk-for-python repository
+- Prompt the user to provide the path to their cloned azure-sdk-for-python repository.
+### Step 2: Validate repository path
+- If the user provides a path to the azure-sdk-for-python repository:
+    - Check if the repository exists at the specified path.
+    - If the repository exists, proceed to Step 5.
+### Step 3: Guide user to set up azure-sdk-for-python repository (if not found)
+- If the user does not have the repository or the path is invalid:
+    - Go to parent directory of current repo root path.
+    - Provide instructions to fork https://github.com/Azure/azure-sdk-for-python repository to the user's GitHub account.
+    - Provide instructions to clone the forked repository to the local machine:
+        ```bash
+        git clone https://github.com/<github-username>/azure-sdk-for-python.git
+        ```
+### Step 4: Set repository path
+- Consider the cloned path as the path to the azure-sdk-for-python repository.
+### Step 5: Open azure-sdk-for-python repository in VSCode
+- Do not ask the user to run tsp compile.
+- Prompt user to open the azure-sdk-for-python repository in VSCode.
+### Step 6: Provide SDK generation instructions
+- Inform user to use the following prompt to start SDK generation using GitHub Copilot agent:
+    ```
+    "Help me generate SDK for Python from TypeSpec API specification for project <path to TypeSpec project root>."
+    ```
+### Step 7: Inform user about SDK generation       
+- Inform user to provide link to SDK pull request if they generate SDK locally and created a pull request for it. SDK generation
+step below will skip it for the language and reuse the pull request link provided by the user.
+- In some cases, user will come back and make more changes to TypeSpec so start the process from step 1 again.
+- If user provides a link to SDK pull request then link SDK pull request to release plan if a release plan already exists and skip SDK generation for that language.
+- If a release plan does not exits then link the SDK pull request when release plan is created.

eng/common/instructions/azsdk-tools/create-spec-pullrequest.instructions.md

@@ -0,0 +1,3 @@
+Your goal is to identify modified TypeSpec project in current branch and create a pull request for it.
+Check if a pull request already exists using GetPullRequestForCurrentBranch. If a pull request exists, inform the user and show the pull request details. If no pull request exists, create a new pull request using CreatePullRequest.
+

eng/common/instructions/azsdk-tools/run-sdk-gen-pipeline.instructions.md

@@ -0,0 +1,43 @@
+---
+description: 'Generate SDKs from TypeSpec using pipeline'
+---
+Your goal is to generate SDKs from the TypeSpec spec pull request. Get API spec pull request link for current branch or from user if not available in current context.
+Provide links to SDK pull request when generated for each language.
+
+## Steps for SDK Generation
+
+### Step 1: Check for Existing SDK Pull Requests
+- Check if SDK pull requests exist from local SDK generation for any languages
+- If SDK pull request exists for a language, skip SDK generation for that language
+- Link existing SDK pull request to release plan
+
+### Step 2: Retrieve and Validate Release Plan
+- Retrieve the release plan for the API spec
+- If API Lifecycle Stage is `Private Preview` then inform user that SDK generation is not supported for this stage and complete the workflow.
+- Check if SDK generation has already occurred for each language
+- Verify if SDK pull requests exist for each language:
+    - If an SDK pull request exists, display its details
+    - If no pull request exists or regeneration is needed, proceed to next step
+
+### Step 3: Execute SDK Generation Pipeline
+- Run SDK generation for each required language: Python, .NET, JavaScript, Java, and Go
+- Execute the SDK generation pipeline with the following required parameters:
+    - TypeSpec project root path
+    - Pull request number (if the API spec is not merged to the main branch)
+    - API version
+    - SDK release type (beta for preview API versions, stable otherwise)
+    - Language options: `Python`, `.NET`, `JavaScript`, `Java`, `Go`
+    - Release plan work item ID
+
+### Step 4: Monitor Pipeline Status
+- Check the status of SDK generation pipeline every 2 minutes
+- Continue monitoring until pipeline succeeds or fails
+- Get SDK pull request link from pipeline once available
+
+### Step 5: Display Results
+- Show all pipeline details once pipeline is in completed status
+- Highlight the language name for each SDK generation task when displaying details
+- Once SDK pull request URL is available:
+    - Inform the user of successful SDK generation
+    - Display the pull request details for each language
+    - Provide links to each generated SDK pull request

eng/common/instructions/azsdk-tools/sdk-details-in-release-plan.instructions.md

@@ -0,0 +1,39 @@
+---
+description: 'Identify languages configured in the TypeSpec project and add it to release plan'
+---
+# Step 1: Find the list of languages and package names
+**Goal**: Identify languages configured in the TypeSpec project and generate the json object with language and package name.
+1. Identify the language emitter configuration in the `tspconfig.yaml` file in the TypeSpec project root.
+2. Identify the package name or namespace for each language emitter.
+3. Map the language name in emitter to one of the following in Pascal case(except .NET):
+   - .NET
+   - Java
+   - Python
+   - JavaScript
+   - Go
+4. Remove `github.com/Azure/azure-sdk-for-go/` from Go package name.
+4. Create a JSON array object with the following structure:
+   ```json
+   [
+           {
+               "language": "<LanguageName>",
+               "packageName": "<PackageName>"
+           },
+           ...
+    ]
+   ```
+5. If no languages are configured, inform the user: "No languages configured in TypeSpec project. Please add at least one language emitter in tspconfig.yaml."
+**Success Criteria**: JSON object with languages and package names created.
+
+# Step 2: Check if release plan exists
+**Goal**: Determine if a release plan exists for the API spec pull request or work item Id or release plan Id in current context.
+1. Get release plan
+2. If no release plan exists, inform the user: "No release plan exists for the API spec pull request. Please create a release plan first."
+3. If a release plan exists, proceed to Step 3.
+**Success Criteria**: Release plan exists or user informed to create one.
+
+# Step 3: Update Release Plan with SDK Information
+**Goal**: Update the release plan with the languages and package names identified in Step 1.
+1. Use `UpdateReleasePlanSDKInfo` to update the release plan work item with the JSON object created in Step 1.
+2. Confirm successful update of the release plan with the SDK information and summary of languages and package names.
+**Success Criteria**: Release plan updated with languages and package names.

eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md

@@ -0,0 +1,114 @@
+---
+description: 'Generate SDKs from TypeSpec'
+---
+Your goal is to guide user through the process of generating SDKs from TypeSpec projects. Show all the high level steps to the user to ensure they understand the flow. Use the provided tools to perform actions and gather information as needed.
+
+## Pre-Flight Check
+- Verify ${workspaceFolder} is not on main branch
+- If on main branch, prompt user: "You are currently on the main branch. Please create a new branch using `git checkout -b <branch-name>` before proceeding."
+- Wait for user confirmation before continuing
+
+## Step 1: Identify TypeSpec Project
+**Goal**: Locate the TypeSpec project root path
+**Actions**:
+1. Check if `tspconfig.yaml` or `main.tsp` files are open in editor
+2. If found, use the parent directory as project root
+3. If not found, prompt user: "Please provide the path to your TypeSpec project root directory"
+4. Validate the provided path contains required TypeSpec files
+**Success Criteria**: Valid TypeSpec project path identified
+
+## Step 2: Validate TypeSpec Specification
+**Goal**: Ensure TypeSpec specification compiles without errors
+**Actions**:
+1. Refer to #file:validate-typespec.instructions.md
+2. If validation succeeds, proceed to Step 3
+3. If validation fails:
+    - Display all compilation errors to user
+    - Prompt: "Please fix the TypeSpec compilation errors before proceeding"
+    - Wait for user to fix errors and re-run validation
+**Success Criteria**: TypeSpec compilation passes without errors
+
+## Step 3: Verify Authentication and Repository Status
+**Goal**: Ensure user is authenticated and working in correct repository
+**Actions**:
+1. Run `GetGitHubUserDetails` to verify login status
+2. If not logged in, prompt: "Please login to GitHub using `gh auth login`"
+3. Once logged in, display user details to confirm identity
+4. Run `CheckIfSpecInPublicRepo` to verify repository
+5. If not in public repo, inform: "Please make spec changes in Azure/azure-rest-api-specs public repo to generate SDKs"
+**Success Criteria**: User authenticated and working in public Azure repo
+
+## Step 4: Review and Commit Changes
+**Goal**: Stage and commit TypeSpec modifications
+**Actions**:
+1. Run `GetModifiedTypeSpecProjects` to identify changes
+2. If no changes found, inform: "No TypeSpec projects were modified in current branch"
+3. Display all modified files (excluding `.github` and `.vscode` folders)
+4. Prompt user: "Please review the modified files. Do you want to commit these changes? (yes/no)"
+5. If yes:
+    - Verify current branch is not "main"
+    - Run `git add <modified-files>`
+    - Prompt for commit message
+    - Run `git commit -m "<user-provided-message>"`
+    - Run `git push -u origin <current-branch-name>`
+**Success Criteria**: Changes committed and pushed to remote branch
+
+## Step 5: Choose SDK Generation Method
+**Goal**: Determine how to generate SDKs
+**Actions**:
+1. Present options: "How would you like to generate SDKs?"
+    - Option A: "Generate SDK locally". This is currently supported only for Python. Do not recommend this for other languages.
+    - Option B: "Use SDK generation pipeline"
+2. Based on selection:
+    - If Option A: Refer to #file:create-sdk-locally.instructions.md and then proceed to Step 6
+    - If Option B: Continue to Step 6
+**Success Criteria**: SDK generation method selected
+
+## Step 6: Create Specification Pull Request
+**Goal**: Create PR for TypeSpec changes if not already created
+**Actions**:
+1. Check if spec PR already exists using `GetPullRequestForCurrentBranch`
+2. If PR exists, display PR details and proceed to Step 7
+3. If no PR exists:
+    - Refer to #file:create-spec-pullrequest.instructions.md
+    - Wait for PR creation confirmation
+    - Display created PR details
+**Success Criteria**: Specification pull request exists
+
+## Step 7: Generate SDKs via Pipeline
+**Goal**: Create release plan and generate SDKs
+**Actions**:
+1. Refer to #file:create-release-plan.instructions.md
+2. If SDK PRs exist, link them to the release plan
+3. Refer to #file:sdk-details-in-release-plan.instructions.md to add languages and package names to the release plan
+4. If TypeSpec project is for management plane, refer to #file:verify-namespace-approval.instructions.md to check package namespace approval.
+5. Refer to #file:run-sdk-gen-pipeline.instructions.md with the spec PR
+6. Monitor pipeline status and provide updates
+7. Display generated SDK PR links when available
+**Success Criteria**: SDK generation pipeline initiated and SDKs generated
+
+## Step 8: Show Generated SDK PRs
+**Goal**: Display all created SDK pull requests
+**Actions**:
+1. Run `GetSDKPullRequestDetails` to fetch generated SDK PR info.
+
+## Step 9: Create release plan
+**Goal**: Create a release plan for the generated SDKs
+**Actions**:
+1. Refer to #file:create-release-plan.instructions.md to create a release plan using the spec pull request.
+2. If the release plan already exists, display the existing plan details.
+
+## Step 10: Mark Spec PR as Ready for Review
+**Goal**: Update spec PR to ready for review status
+**Actions**:
+1. Prompt user to change spec PR to ready for review: "Please change the spec pull request to ready for review status"
+2. Get approval and merge the spec PR
+
+## Step 11: Release SDK Package
+**Goal**: Release the SDK package using the release plan
+**Actions**:
+1. Run `ReleaseSdkPackage` to release the SDK package.
+2. Inform user to approve the package release using release pipeline.
+
+## Process Complete
+Display summary of all created PRs and next steps for user.

eng/common/instructions/azsdk-tools/validate-typespec.instructions.md

@@ -0,0 +1,6 @@
+---
+description: 'Validate TypeSpec'
+---
+Your goal is identify the TypeSpec project root if not available in current context and validate TypeSpec project.
+Before running, inform user that TypeSpec validation takes around 20 - 30 seconds. Provide complete summary after 
+running the tool and highlight any errors and help user fix them.

eng/common/instructions/azsdk-tools/verify-namespace-approval.instructions.md

@@ -0,0 +1,22 @@
+---
+description: 'Verify SDK namespace approval for management plane'
+---
+This task is required only for management plane API spec and only if a release plan exists for the API spec pull request.
+
+## Step 1: Check if release plan exists and it is for management plane SDK
+**Goal**: Determine if a release plan exists for the API spec pull request or work item Id or release plan Id in current context.
+**Actions**:
+1. Get release plan and check if it is for management plane SDK
+2. If not, inform user: "This task is only applicable for management plane SDKs. No action required."
+3. Check if release plan already has namespace approval issue. Also prompt user to check if this is the first release of SDK.
+4. If namespace approval issue exists, inform user: "Namespace approval issue already exists for this release plan.". Prompt user to
+check if they want to link a different namespace approval issue to the release plan. Show namespace approval status.
+5. Move to Step 2 if namespace approval issue does not exist or user wants to link a different namespace approval issue.
+
+## Step 2: Gather Namespace Approval Information
+**Goal**: Link namespace approval issue to the release plan.
+**Actions**:
+1. Collect GitHub issue created in Azure/azure-sdk repo for namespace approval. Do not use any other repo name.
+2. Run `LinkNameSpaceApprovalIssue` to link the issue to the release plan work item id.
+3. Confirm successful linking of the namespace approval issue to the release plan.
+**Success Criteria**: Namespace approval issue linked to the release plan or confirmed as already linked.