Merge branch 'main' into user/jameslim/aci-azmi-api-2026-05-01

Author: MicroJamesLim

.github/skills/azure-typespec-author/SKILL.md

@@ -4,8 +4,7 @@ license: MIT
 metadata:
   version: "1.0.0"
 description: "Authors and modifies Azure TypeSpec (.tsp) API specifications. USE FOR: any TypeSpec/tsp change — api versions (add, bump, preview, stable, promote), resources, operations, models, properties, decorators, visibility, constraints, breaking changes, LRO, suppressions, operationId, spread model. Covers ARM resource-manager and data-plane services. DO NOT USE FOR: SDK generation, releasing SDK packages, or single MCP tool calls. INVOKES: azure-sdk-mcp:azsdk_typespec_generate_authoring_plan, azure-sdk-mcp:azsdk_run_typespec_validation."
-compatibility:
-  requires: "azure-sdk-mcp server with azsdk_typespec_generate_authoring_plan and azsdk_run_typespec_validation tools"
+compatibility: "azure-sdk-mcp server with azsdk_typespec_generate_authoring_plan and azsdk_run_typespec_validation tools"
 ---
 
 # Azure TypeSpec Author
@@ -19,6 +18,16 @@ compatibility:
 
 **Prerequisite:** `azure-sdk-mcp` server must be running.
 
+# When to invoke the azure-typespec-author skill
+
+The `azure-typespec-author` skill **must** be invoked immediately in all modes (including plan mode) for any task that involves creating and modifying TypeSpec (`.tsp`) files except for `client.tsp` under the specification directory in this repository. This includes but is not limited to:
+
+- Adding, bumping, or promoting API versions (preview, stable)
+- Adding or modifying resources, operations, models, properties, or decorators
+- Changing visibility, constraints, breaking changes, LRO patterns, or suppressions
+- Defining or updating operationId, spread models, or extension resources
+- Converting Swagger to TypeSpec (post-conversion edits)
+
 ## Constraints
 
 - **Always follow the full workflow** — even seemingly simple changes (e.g. adding a default value) can require complex versioning decorator changes. Never skip steps.
@@ -28,96 +37,54 @@ compatibility:
 - **Always cite references** — provide links that justify the approach.
 - **Follow the authoring plan exactly** — code changes in Step 4 MUST follow the authoring plan generated in Step 3. Do not deviate by referring to existing code patterns in the TypeSpec project; the authoring plan is the single source of truth for what to change.
 
----
-
 ## Workflow
 
-> Classify → Intake → Plan → Apply → Validate
-
-### Progress Checklist
-
-Copy and update as you progress:
+> Analyze → Intake → Plan → Apply → Validate → Output reference links
 
-- [ ] Step 1: Analyzed project & classified as: \_\_\_
-- [ ] Step 2: Collected intake inputs
-- [ ] Step 3: Retrieved authoring plan
-- [ ] Step 4: Applied changes
-- [ ] Step 5: Validated with TypeSpec validation and `tsp compile .`
+- [ ] Step 1 — Analyze project
+- [ ] Step 2 — Intake
+- [ ] Step 3 — Build authoring plan
+- [ ] Step 4 — Apply changes
+- [ ] Step 5 — Validate
+- [ ] Step 6 — Output reference links
 
-### Step 1: Analyze & Classify
+### Step 1: Analyze Project
 
-Follow [analyze project & classify task](references/analyze-project-and-classify-task.md).
-
-Classify as exactly one:
-
-| Task Type                 | When                                                                              | `azsdk_typespec_generate_authoring_plan` |
-| ------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------- |
-| **API Version Evolution** | Adding a new preview or stable API version to an existing ARM service. (ARM only) | **MUST NOT** call                        |
-| **General Authoring**     | Any other `.tsp` change (resources, operations, models, properties, etc.)         | **MUST** call                            |
-
-State your classification explicitly before proceeding.
-
----
+See [analyze-project.md](references/analyze-project.md).
 
 ### Step 2: Intake
 
-Collect inputs needed for the change. Branch by task type:
-
-- **API Version Evolution** → Follow [API version evolution reference — Step 2](references/api-version-evolution.md#step-2-intake).
-- **General Authoring** → Follow [intake guide](references/general-authoring-intake.md).
+See [intake.md](references/intake.md).
 
----
+### Step 3: Build Authoring Plan
 
-### Step 3: Retrieve Authoring Plan
-
-Check your classification from Step 1, then branch:
-
-- **API Version Evolution** → Follow [API version evolution reference — Step 3](references/api-version-evolution.md#step-3-retrieve-authoring-plan). **MUST NOT** call `azsdk_typespec_generate_authoring_plan`.
-- **General Authoring** → **MUST** invoke `azure-sdk-mcp:azsdk_typespec_generate_authoring_plan` with:
-
-  | Parameter                 | Value                                                                                                                                                                       |
-  | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-  | `request`                 | User request (verbatim)                                                                                                                                                     |
-  | `additionalInformation`   | All content gathered from Steps 1–2 (intake analysis, user answers, relevant `.tsp` code read from the project), **including any case-specific Defaults noted in Step 2.2** |
-  | `typeSpecProjectRootPath` | TypeSpec project root path                                                                                                                                                  |
-
-  Do not proceed without an authoring plan from this tool.
-
----
+See [authoring-plan.md](references/authoring-plan.md).
 
 ### Step 4: Apply Changes
 
-Confirm uncertainties with the user, then make minimal `.tsp` edits.
-
-- **API Version Evolution** → Apply the plan from Step 3.
-- **General Authoring** → Apply the authoring plan from Step 3.
-
----
+Make minimal `.tsp` edits following the plan from Step 3. Confirm uncertainties with the user first.
 
 ### Step 5: Validate
 
-See [validation guide](references/validation.md) for sub-steps. You must run TypeSpec validation (5.1), `tsp compile .` (5.2), and example verification (5.3, API Version Evolution only).
+See [validation.md](references/validation.md). Run 5.1 (TypeSpec validation) and 5.2 (`tsp compile .`) always; 5.3 (example verification) for API version evolution only.
 
----
+### Step 6: Output Reference Links
+
+Output all referenced document URLs from Step 3. This gives the user direct links to the documentation that informed the changes.
 
 ## Reference Files
 
-| File                                                                                    | Purpose                                   |
-| --------------------------------------------------------------------------------------- | ----------------------------------------- |
-| [analyze-project-and-classify-task.md](references/analyze-project-and-classify-task.md) | Step 1: project analysis + classification |
-| [api-version-evolution.md](references/api-version-evolution.md)                         | Steps 2–4 for API Version Evolution tasks |
-| [general-authoring-intake.md](references/general-authoring-intake.md)                   | Step 2 for General Authoring tasks        |
-| [agentic-search.md](references/agentic-search.md)                                       | Procedure for fetching external docs      |
-| [validation.md](references/validation.md)                                               | Step 5: validation sub-steps              |
+| File                                                                  | Purpose                                     |
+| --------------------------------------------------------------------- | ------------------------------------------- |
+| [analyze-project.md](references/analyze-project.md)                   | Step 1: project analysis                    |
+| [intake.md](references/intake.md)                                     | Step 2: general + case-specific intake      |
+| [authoring-plan.md](references/authoring-plan.md)                     | Step 3: build authoring plan (Option A + B) |
+| [agentic-search.md](references/agentic-search.md)                     | Procedure: fetch URLs → extract guidance    |
+| [reference-document-links.md](references/reference-document-links.md) | Catalog of external guide URLs              |
+| [validation.md](references/validation.md)                             | Step 5: validate → compile → verify         |
 
 ## Examples
 
 - "Add a new preview API version 2026-01-01-preview for widget resource manager"
-- "Bump to stable version 2026-01-01 for Microsoft.Widget"
 - "Add an ARM resource named Asset with CRUD operations"
 - "Add a new property to the Widget model"
-
-## Troubleshooting
-
-- **TypeSpec validation fails** — display all errors, provide fix suggestions, re-run validation.
-- **API Version Evolution** — use the versioning guide URLs in the [version evolution reference](references/api-version-evolution.md); do not call the authoring plan tool.

.github/skills/azure-typespec-author/references/agentic-search.md

@@ -1,15 +1,14 @@
 # Agentic Search
 
-Procedure for fetching external documentation and extracting actionable guidance.
-
 ## Input
 
-A set of document URLs to fetch (provided by the caller).
+- **Step 1 result** — project analysis output from [analyze-project.md](analyze-project.md): service type, existing API versions, latest version, intent, target resource/interface, and constraints.
+- **User request** — the user's stated goal for this session.
 
 ## Procedure
 
-1. **Fetch documents** — use `web_fetch` to download each URL. Extract the page content as markdown.
-2. **Search content** — read the downloaded content and identify instructions, code examples, and patterns relevant to the current task.
-3. **Build authoring plan** — synthesize the extracted content into a concrete authoring plan grounded in the fetched material.
-
-> Do not proceed without an authoring plan grounded in the fetched reference material.
+1. **Select URLs** — read [reference-document-links.md](reference-document-links.md). Select only the URLs relevant to the user's request and Step 1 result. If unsure, select all.
+2. **Fetch** — `web_fetch` each selected URL. Extract content as markdown.
+3. **Search** — find content matching a query derived from the user's request and Step 1 result. Choose the most effective local search tool available.
+4. **Iterate** — if initial results are insufficient, refine the query or fetch additional pages/URLs until the information satisfies the query.
+5. **Return** — provide the extracted guidance to the caller.

.github/skills/azure-typespec-author/references/analyze-project-and-classify-task.md

@@ -0,0 +1,31 @@
+# Analyze Project
+
+Collect the inputs below from the TypeSpec project. Ask **up to 6 concise questions** for any that are missing.
+
+| #   | Input                       | Example                                                          |
+| --- | --------------------------- | ---------------------------------------------------------------- |
+| 1   | TypeSpec project root       | `/specification/widget/resource-manager/Microsoft.Widget/Widget` |
+| 2   | Path to `tspconfig.yaml`    | `<spec-root>/tspconfig.yaml`                                     |
+| 3   | Service type                | ARM / data-plane                                                 |
+| 4   | Existing API versions       | `2024-01-01 (stable)`, `2024-06-01-preview`                      |
+| 5   | Latest API version          | Most recent entry in the `Versions` enum                         |
+| 6   | Current working API version | The version being added or modified this session                 |
+| 7   | Intent                      | add / modify / fix                                               |
+| 8   | Target resource/interface   | Resource or operation name (if known)                            |
+| 9   | Constraints                 | Breaking-change limits, naming rules, emitter targets, etc.      |
+
+## Output
+
+Display the results before proceeding to Step 2:
+
+```
+TypeSpec project root: /path/to/project
+tspconfig.yaml:  /path/to/project/tspconfig.yaml
+Service Type:    ARM/Dataplane
+API Versions:    2024-01-01 (stable), 2024-06-01-preview (preview)
+Latest Version:  2024-06-01-preview
+Working Version: [TBD]
+Intent:          [add/modify/fix]
+Target:          [resource/operation if known]
+Constraints:     [if any]
+```

.github/skills/azure-typespec-author/references/analyze-project.md

@@ -0,0 +1,25 @@
+# Build Authoring Plan
+
+> Prerequisite: Steps 1 (Analyze Project) and 2 (Intake) must be complete.
+
+## 3.1 General (All Cases)
+
+Use **both** tools to build an authoring plan, if the retrieved results have conflict, rely on agentic search.
+
+1. **MCP Tool** — call `azsdk_typespec_generate_authoring_plan` with:
+   - `request`: user request (verbatim)
+   - `additionalInformation`: all context from Steps 1–2
+   - `typeSpecProjectRootPath`: project root path
+
+2. **Agentic Search** — run [agentic search](agentic-search.md) with URLs from [reference-document-links.md](reference-document-links.md) and a query from the user's request. Synthesize extracted content into a concrete plan.
+
+---
+
+## 3.2 Case-Specific Authoring Plan
+
+### Case 3 — API Version Evolution
+
+> **Must** use Agentic Search (option 2 above) to build the plan — do not call the MCP tool.
+
+1. Copy `.json` files from latest version's `examples/` into new version's `examples/`. Update `api-version` in each file. Delete old version's example folder if old version is no longer existed.
+2. Update `readme.md`.