Issue #1085: Prefer AZD pattern modules first, fallback to AVM modules

plugin/skills/azure-deploy/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: azure-deploy
-description: "Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/plan.md from azure-prepare and validated status from azure-validate. WHEN: \"run azd up\", \"run azd deploy\", \"execute deployment\", \"push to production\", \"push to cloud\", \"go live\", \"ship it\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"launch on Azure\". DO NOT USE WHEN: \"create and deploy\", \"build and deploy\", \"create a new app\", \"set up infrastructure\", \"create and deploy to Azure using Terraform\" — use azure-prepare for these."
-license: MIT
-metadata:
-  author: Microsoft
-  version: "1.0.2"
+description: "Deploy validated applications to Azure via azd, Bicep, or Terraform execution steps. WHEN: \"run azd up\", \"run azd deploy\", \"deploy to Azure\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"go live\"."
 ---
 
 # Azure Deploy
@@ -34,14 +30,14 @@ metadata:
 ## Triggers
 
 Activate this skill when user wants to:
-- Execute deployment of an already-prepared application (azure.yaml and infra/ exist)
-- Push updates to an existing Azure deployment
-- Run `azd up`, `azd deploy`, or `az deployment` on a prepared project
-- Ship already-built code to production
+- Deploy their application to Azure
+- Publish, host, or launch their app
+- Push updates to existing deployment
+- Run `azd up` or `az deployment`
+- Ship code to production
+- Deploy Azure Functions to the cloud
 - Deploy an application that already includes API Management (APIM) gateway infrastructure
 
-> **Scope**: This skill executes deployments. It does not create applications, generate infrastructure code, or scaffold projects. For those tasks, use **azure-prepare**.
-
 > **APIM / AI Gateway**: Use this skill to deploy applications whose APIM/AI gateway infrastructure was already created during **azure-prepare**. For creating or changing APIM resources, see [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). For AI governance policies, invoke **azure-aigateway** skill.
 
 ## Rules
@@ -50,7 +46,6 @@ Activate this skill when user wants to:
 2. `.azure/plan.md` must exist with status `Validated`
 3. **Pre-deploy checklist required** — [Pre-Deploy Checklist](references/pre-deploy-checklist.md)
 4. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md)
-5. **Scope: deployment execution only** — This skill owns execution of `azd up`, `azd deploy`, `terraform apply`, and `az deployment` commands. These commands are run through this skill's error recovery and verification pipeline.
 
 ---
 
@@ -64,7 +59,7 @@ Activate this skill when user wants to:
 | 4 | **Execute Deploy** — Follow recipe steps | Recipe README |
 | 5 | **Post-Deploy** — Configure SQL managed identity and apply EF migrations if applicable | [Post-Deployment](references/recipes/azd/post-deployment.md) |
 | 6 | **Handle Errors** — See recipe's `errors.md` | — |
-| 7 | **Verify Success** — Confirm deployment completed and endpoints are accessible | [Verification](references/recipes/azd/verify.md) |
+| 7 | **Verify Success** — Confirm deployment completed and endpoints are accessible | [Verify](references/recipes/azd/verify.md) |
 
 > **⛔ VALIDATION PROOF CHECK**
 >
@@ -86,4 +81,4 @@ Activate this skill when user wants to:
 ## References
 
 - [Troubleshooting](references/troubleshooting.md) - Common issues and solutions
-- [Post-Deployment Steps](references/recipes/azd/post-deployment.md) - SQL + EF Core setup
+- [Post-Deployment Steps](references/recipes/azd/post-deployment.md) - SQL + EF Core setup

plugin/skills/azure-deploy/references/recipes/bicep/README.md

@@ -77,6 +77,16 @@ az deployment sub show \
 | `mcp_bicep_get_az_resource_type_schema` | Resource schemas |
 | `mcp_bicep_list_avm_metadata` | Azure Verified Modules |
 
+## AVM Verification Before Deploy
+
+Before running deployment commands, verify generated templates followed AVM-first module selection:
+
+1. AVM Bicep Pattern Modules (prefer AVM+AZD patterns)
+2. AVM Bicep Resource Modules
+3. AVM Bicep Utility Modules
+
+If no AVM+AZD pattern module is available, fallback must remain within AVM modules (resource -> utility).
+
 ## Cleanup (DESTRUCTIVE)
 
 ```bash

plugin/skills/azure-prepare/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: azure-prepare
-description: "Prepare Azure apps for deployment (infra Bicep/Terraform, azure.yaml, Dockerfiles). Use for create/modernize or create+deploy; not cross-cloud migration (use azure-cloud-migrate). WHEN: \"create app\", \"build web app\", \"create API\", \"create serverless HTTP API\", \"create frontend\", \"create back end\", \"build a service\", \"modernize application\", \"update application\", \"add authentication\", \"add caching\", \"host on Azure\", \"create and deploy\", \"deploy to Azure\", \"deploy to Azure using Terraform\", \"deploy to Azure App Service\", \"deploy to Azure App Service using Terraform\", \"deploy to Azure Container Apps\", \"deploy to Azure Container Apps using Terraform\", \"generate Terraform\", \"generate Bicep\", \"function app\", \"timer trigger\", \"service bus trigger\", \"event-driven function\", \"containerized Node.js app\", \"social media app\", \"static portfolio website\", \"todo list with frontend and API\", \"prepare my Azure application to use Key Vault\", \"managed identity\"."
-license: MIT
-metadata:
-  author: Microsoft
-  version: "1.0.1"
+description: "Prepare applications for Azure deployment, except cross-cloud scenarios (use azure-cloud-migrate). Generates or updates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles. WHEN: \"prepare app for Azure\", \"build web app and host on Azure\", \"move on-premises application to Azure\", \"configure Azure hosting\", \"create Azure app\", \"add Azure service\", \"modernize app for Azure\", \"generate azure.yaml\", \"generate Bicep\", \"generate Terraform\", \"create Azure Functions app\"."
 ---
 
 # Azure Prepare
@@ -21,10 +17,9 @@ Activate this skill when user wants to:
 - Create a new application
 - Add services or components to an existing app
 - Make updates or changes to existing application
-- Modernize or migrate an application
+- Modernize an application
 - Set up Azure infrastructure
 - Deploy to Azure or host on Azure
-- Create and deploy to Azure (including Terraform-based deployment requests)
 
 ## Rules
 
@@ -34,12 +29,11 @@ Activate this skill when user wants to:
 4. **Update plan progressively** — Mark steps complete as you go
 5. **Validate before deploy** — Invoke azure-validate before azure-deploy
 6. **Confirm Azure context** — Use `ask_user` for subscription and location per [Azure Context](references/azure-context.md)
-7. ❌ **Destructive actions require `ask_user`** — [Global Rules](references/global-rules.md)
-8. **Scope: preparation only** — This skill generates infrastructure code and configuration files. Deployment execution (`azd up`, `azd deploy`, `terraform apply`) is handled by the **azure-deploy** skill, which provides built-in error recovery and deployment verification.
+7. ⛔ **Destructive actions require `ask_user`** — [Global Rules](references/global-rules.md)
 
 ---
 
-## ❌ PLAN-FIRST WORKFLOW — MANDATORY
+## ⛔ PLAN-FIRST WORKFLOW — MANDATORY
 
 > **YOU MUST CREATE A PLAN BEFORE DOING ANY WORK**
 >
@@ -52,13 +46,12 @@ Activate this skill when user wants to:
 
 ---
 
-## ❌ STEP 0: Specialized Technology Check — MANDATORY FIRST ACTION
+## ⛔ STEP 0: Specialized Technology Check — MANDATORY FIRST ACTION
 
 **BEFORE starting Phase 1**, check if the user's prompt mentions a specialized technology that has a dedicated skill with tested templates. If matched, **invoke that skill FIRST** — then resume azure-prepare for validation and deployment.
 
 | Prompt keywords | Invoke FIRST |
 |----------------|-------------|
-| Lambda, AWS Lambda, migrate AWS, migrate GCP, Lambda to Functions, migrate from AWS, migrate from GCP | **azure-cloud-migrate** |
 | copilot SDK, copilot app, copilot-powered, @github/copilot-sdk, CopilotClient | **azure-hosted-copilot-sdk** |
 | Azure Functions, function app, serverless function, timer trigger, HTTP trigger, func new | Stay in **azure-prepare** — prefer Azure Functions templates in Step 4 |
 | APIM, API Management, API gateway, deploy APIM | Stay in **azure-prepare** — see [APIM Deployment Guide](references/apim.md) |
@@ -76,7 +69,7 @@ Create `.azure/plan.md` by completing these steps. Do NOT generate any artifacts
 
 | # | Action | Reference |
 |---|--------|-----------|
-| 0 | **❌ Check Prompt for Specialized Tech** — If user mentions copilot SDK, Azure Functions, etc., invoke that skill first | [specialized-routing.md](references/specialized-routing.md) |
+| 0 | **⛔ Check Prompt for Specialized Tech** — If user mentions copilot SDK, Azure Functions, etc., invoke that skill first | [specialized-routing.md](references/specialized-routing.md) |
 | 1 | **Analyze Workspace** — Determine mode: NEW, MODIFY, or MODERNIZE | [analyze.md](references/analyze.md) |
 | 2 | **Gather Requirements** — Classification, scale, budget | [requirements.md](references/requirements.md) |
 | 3 | **Scan Codebase** — Identify components, technologies, dependencies | [scan.md](references/scan.md) |
@@ -88,7 +81,7 @@ Create `.azure/plan.md` by completing these steps. Do NOT generate any artifacts
 
 ---
 
-> **❌ STOP HERE** — Do NOT proceed to Phase 2 until the user approves the plan.
+> **⛔ STOP HERE** — Do NOT proceed to Phase 2 until the user approves the plan.
 
 ---
 
@@ -103,7 +96,7 @@ Execute the approved plan. Update `.azure/plan.md` status after each step.
 | 3 | **Generate Artifacts** — Create infrastructure and configuration files | [generate.md](references/generate.md) |
 | 4 | **Harden Security** — Apply security best practices | [security.md](references/security.md) |
 | 5 | **Update Plan** — Mark steps complete, set status to `Ready for Validation` | `.azure/plan.md` |
-| 6 | **⚠️ Hand Off** — Invoke **azure-validate** skill. Your preparation work is done. Deployment execution is handled by azure-deploy. | — |
+| 6 | **Validate** — Invoke **azure-validate** skill | — |
 
 ---
 

plugin/skills/azure-prepare/references/recipes/azcli/README.md

@@ -17,7 +17,7 @@ Azure CLI workflow for imperative Azure deployments.
 | Artifact | Research Action |
 |----------|-----------------|
 | Bicep files | Call `mcp_bicep_get_bicep_best_practices` |
-| Bicep modules | Call `mcp_bicep_list_avm_metadata` for Azure Verified Modules |
+| Bicep modules | Call `mcp_bicep_list_avm_metadata` and follow [AVM module order](../azd/iac-rules.md#avm-module-selection-order-mandatory) |
 | Azure CLI commands | Call `activate_azure_cli_management_tools` |
 | Azure best practices | Call `mcp_azure_mcp_get_bestpractices` |
 

plugin/skills/azure-prepare/references/recipes/azd/README.md

@@ -46,7 +46,7 @@ Azure Developer CLI workflow for preparing Azure deployments.
 | Azure Functions templates | [Templates](../../services/functions/templates/README.md) |
 | Bicep best practices | `mcp_bicep_get_bicep_best_practices` |
 | Bicep resource schema | `mcp_bicep_get_az_resource_type_schema` |
-| Azure Verified Modules | `mcp_bicep_list_avm_metadata` |
+| Azure Verified Modules | `mcp_bicep_list_avm_metadata` + [AVM module order](iac-rules.md#avm-module-selection-order-mandatory) |
 | Terraform best practices | `mcp_azure_mcp_azureterraformbestpractices` |
 | Dockerfiles | [Docker Guide](docker.md) |
 

plugin/skills/azure-prepare/references/recipes/azd/iac-rules.md

@@ -1,6 +1,37 @@
 # AZD IAC Rules
 
-Bicep rules for AZD projects. **Additive** — apply `mcp_bicep_get_bicep_best_practices`, `mcp_bicep_list_avm_metadata`, and `mcp_bicep_get_az_resource_type_schema` first, then these azd-specific rules.
+IaC rules for AZD projects. **Additive** — for Bicep, apply `mcp_bicep_get_bicep_best_practices`, `mcp_bicep_list_avm_metadata`, and `mcp_bicep_get_az_resource_type_schema` first; for Terraform, apply `mcp_azure_mcp_azureterraformbestpractices` first; then apply these azd-specific rules.
+
+## AVM Module Selection Order (MANDATORY)
+
+Always prefer modules in provider-specific order:
+
+For **Bicep**:
+1. AVM Bicep Pattern Modules (AVM+AZD first when available)
+2. AVM Bicep Resource Modules
+3. AVM Bicep Utility Modules
+
+For **Terraform**:
+1. AVM Terraform Pattern Modules
+2. AVM Terraform Resource Modules
+3. AVM Terraform Utility Modules
+
+If no pattern module exists for the active provider, default immediately to AVM modules in the same provider order (resource, then utility) instead of using non-AVM modules.
+
+## Retrieval Strategy (Hybrid: azure-documentation MCP + Context7)
+
+- **Primary (authoritative):** Use `mcp_azure_mcp_documentation` (`azure-documentation`) for current Azure guidance and AVM integration documentation.
+- **Primary (module catalog):** Use `mcp_bicep_list_avm_metadata` plus official AVM indexes to select concrete modules.
+- **Secondary (supplemental):** Use Context7 only for implementation examples when `mcp_azure_mcp_documentation` does not provide enough detail.
+
+## Validation Plan
+
+Before finalizing generated guidance:
+
+1. Verify the selected module path uses the required AVM order above.
+2. Verify AVM+AZD pattern modules were checked first, and fallback moved to AVM resource/utility modules when no pattern module exists.
+3. Verify Terraform guidance follows pattern -> resource -> utility ordering.
+4. Include selected module names and source links in the plan/output for traceability.
 
 ## File Structure
 

plugin/skills/azure-prepare/references/recipes/azd/terraform.md

@@ -274,6 +274,16 @@ When preparing a new azd+Terraform project:
    - Hosting resources: `azd-service-name` (matches azure.yaml services)
 4. **Research best practices** - Call `mcp_azure_mcp_azureterraformbestpractices`
 
+## AVM Terraform Module Priority
+
+For Terraform module selection, enforce this order:
+
+1. AVM Terraform Pattern Modules
+2. AVM Terraform Resource Modules
+3. AVM Terraform Utility Modules
+
+Use `mcp_azure_mcp_documentation` (`azure-documentation`) for current guidance and AVM context first, then use Context7 only as supplemental examples if required.
+
 ## Migration from Pure Terraform
 
 Converting existing Terraform project to use azd:

plugin/skills/azure-prepare/references/recipes/bicep/README.md

@@ -17,7 +17,7 @@ Standalone Bicep workflow (without AZD).
 | Artifact | Research Action |
 |----------|-----------------|
 | Bicep files | Call `mcp_bicep_get_bicep_best_practices` |
-| Bicep modules | Call `mcp_bicep_list_avm_metadata` for Azure Verified Modules |
+| Bicep modules | Call `mcp_bicep_list_avm_metadata` and follow [AVM module order](../azd/iac-rules.md#avm-module-selection-order-mandatory) |
 | Resource schemas | Use `activate_azure_resource_schema_tools` if needed |
 
 ## Generation Steps

tests/README.md

@@ -166,6 +166,7 @@ go install github.com/microsoft/waza/cmd/waza@latest
 
 **Committed eval suites** (⬢ customized graders, fixtures, and assertions):
 - `azure-prepare` — template selection, recipe composition, plan-first workflow
+- `azure-deploy` — deploy routing and AVM+AZD module-priority/fallback guidance
 
 **Auto-generated** (⬡ from SKILL.md frontmatter): all other skills
 

tests/azure-deploy/__snapshots__/triggers.test.ts.snap

@@ -2,116 +2,50 @@
 
 exports[`azure-deploy - Trigger Tests Trigger Keywords Snapshot skill description triggers match snapshot 1`] = `
 {
-  "description": "Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.",
+  "description": "Deploy validated applications to Azure via azd, Bicep, or Terraform execution steps. WHEN: "run azd up", "run azd deploy", "deploy to Azure", "bicep deploy", "terraform apply", "publish to Azure", "go live".",
   "extractedKeywords": [
-    "already-prepared",
-    "application",
     "applications",
     "apply",
-    "asks",
     "azure",
-    "azure-prepare",
-    "azure-validate",
     "bicep",
-    "build",
-    "built-in",
     "cli",
-    "cloud",
-    "commands",
-    "create",
     "deploy",
-    "deployment",
-    "deployments",
-    "error",
-    "execute",
-    "existing",
-    "files",
-    "from",
-    "have",
+    "execution",
+    "function",
     "identity",
-    "infrastructure",
-    "instead",
-    "launch",
     "live",
     "mcp",
-    "plan",
-    "production",
     "publish",
-    "push",
-    "recovery",
-    "requires",
-    "runs",
-    "ship",
-    "skill",
     "sql",
-    "status",
+    "steps",
     "terraform",
-    "that",
-    "these",
-    "this",
-    "user",
-    "using",
     "validated",
     "validation",
     "when",
-    "with",
   ],
   "name": "azure-deploy",
 }
 `;
 
 exports[`azure-deploy - Trigger Tests Trigger Keywords Snapshot skill keywords match snapshot 1`] = `
 [
-  "already-prepared",
-  "application",
   "applications",
   "apply",
-  "asks",
   "azure",
-  "azure-prepare",
-  "azure-validate",
   "bicep",
-  "build",
-  "built-in",
   "cli",
-  "cloud",
-  "commands",
-  "create",
   "deploy",
-  "deployment",
-  "deployments",
-  "error",
-  "execute",
-  "existing",
-  "files",
-  "from",
-  "have",
+  "execution",
+  "function",
   "identity",
-  "infrastructure",
-  "instead",
-  "launch",
   "live",
   "mcp",
-  "plan",
-  "production",
   "publish",
-  "push",
-  "recovery",
-  "requires",
-  "runs",
-  "ship",
-  "skill",
   "sql",
-  "status",
+  "steps",
   "terraform",
-  "that",
-  "these",
-  "this",
-  "user",
-  "using",
   "validated",
   "validation",
   "when",
-  "with",
 ]
 `;