feat(agents): Use Azure MCP azureterraform for Terraform lookup

.devcontainer/configure-mcp.mjs

@@ -15,7 +15,7 @@ const defaults = {
   "azure-mcp": {
     type: "stdio",
     command: "npx",
-    args: ["-y", "@azure/mcp@2.0.5", "server", "start"],
+    args: ["-y", "@azure/mcp@3.0.0", "server", "start"],
     env: { NPM_CONFIG_ALLOW_REMOTE: "all" },
   },
 };

.github/agents/05-iac-planner.agent.md

@@ -153,8 +153,8 @@ and the saved checkpoint; read only the predecessor sections the current phase n
 ## IaC Track Detection
 
 Run `apex-recall show <project> --json` and check `decisions.iac_tool`; ask the user when it is unset.
-`"Bicep"` uses the Bicep AVM metadata tools and patterns. `"Terraform"` uses the public Terraform Registry API
-and Terraform patterns; no Terraform MCP server is required.
+`"Bicep"` uses Bicep AVM metadata tools and patterns. `"Terraform"` uses Azure MCP `azureterraform` lookup
+with the public Terraform Registry API as fallback and the AVM module index for existence; plus Terraform patterns.
 
 ## Read Skills First
 

.github/agents/06t-terraform-codegen.agent.md

@@ -322,15 +322,17 @@ For EACH resource in `04-iac-contract.json#resources[]` (canonical
 source; `04-implementation-plan.md` is the prose mirror):
 
 1. Read the approved source and exact version from `04-iac-contract.json#modules.terraform[]`.
-2. Query the public Terraform Registry API for that pinned module version;
-  inspect inputs, outputs, and linked source. No Terraform MCP server is required.
+2. Retrieve the pinned module version's README with the Azure MCP `azureterraform` `avm get` command
+  (`--module-name`, `--module-version`); fall back to the public Terraform Registry API when the tool is
+  unavailable. Inspect inputs, outputs, and linked source.
 3. Cross-check the approved pins and parameter types against the retrieved schema;
   flag mismatches using the AVM Known Pitfalls in the Terraform patterns skill.
 4. Preserve the approved exact `X.Y.Z` module version. Do not replace it with
   a version range or select a newer release. An unavailable pin or required
   version change returns to the Planner under the existing plan-lock contract.
-5. For non-AVM resources, verify arguments against the pinned provider's official
-  Registry documentation and `terraform providers schema -json` after isolated
+5. For non-AVM resources, verify arguments against the pinned provider's documentation (Azure MCP
+  `azureterraform` `azurerm get` or `azapi get`, else the official Registry docs) and
+  `terraform providers schema -json` after isolated
   `terraform init -backend=false -input=false`. Do not infer missing schemas from memory.
 6. Check region limitations
 7. Save to `agent-output/{project}/04-preflight-check.md`

.github/instructions/iac-terraform-best-practices.instructions.md

@@ -92,7 +92,7 @@ once, passed everywhere.
 | `>= 3.0` provider version range | Use `~> 4.0` major-series constraint |
 | Raw `azurerm_*` when AVM exists | Use AVM-TF modules or get approval |
 | `connection_string` auth        | Use managed identity RBAC          |
-| AVM-TF `version = "~> X.Y"`     | Use exact semver `version = "X.Y.Z"` — resolved live from `registry.terraform.io` at plan time |
+| AVM-TF `version = "~> X.Y"`     | Use exact semver `version = "X.Y.Z"` — resolved live from the AVM registry at plan time |
 
 ## Validation
 

.github/skills/apex-azure-compliance/references/azure-quick-review.md

@@ -8,6 +8,7 @@ This skill enables comprehensive Azure compliance assessments using Azure Quick
 
 - **Azure authentication** - Logged in via Azure CLI (`az login`) or using Service Principal/Managed Identity
 - **Reader permissions** - Minimum Reader role on target subscription or management group
+- **azqr 3.0.0 or later on `PATH`** - Azure MCP 3.0.0 lists `extension_azqr` only when azqr is installed locally; without it, run `azqr scan --subscription <id>` directly
 
 ## Assessment Workflow
 

.github/skills/apex-azure-cost-optimization/references/azure-quick-review.md

@@ -25,7 +25,7 @@ excludeSections:
 Execute the scan using Azure MCP or CLI:
 
 ```powershell
-# Via Azure MCP (preferred if available)
+# Via Azure MCP (only listed when azqr 3.0.0 or later is installed locally)
 # Use the extension_azqr tool with subscription and optional resource-group parameters
 
 # Or via direct CLI:

.github/skills/apex-azure-defaults/references/avm-modules.md

@@ -7,10 +7,17 @@
 >
 > - **Bicep:** `curl -sf https://mcr.microsoft.com/v2/bicep/avm/res/{path}/tags/list`
 >   → highest non-prerelease semver in `tags[]`.
-> - **Terraform:** `curl -sf https://registry.terraform.io/v1/modules/Azure/avm-res-{path}/azurerm/versions`
->   → first entry in `modules[0].versions[]`.
-> - **Guidance:** Azure MCP provides Azure Terraform documentation and best
->   practices; Registry metadata still comes from the public registry APIs.
+> - **Terraform:** Azure MCP `azureterraform avm versions --module-name avm-res-{path}` lists versions; or
+>   `curl -sf https://registry.terraform.io/v1/modules/Azure/avm-res-{path}/azurerm/versions`
+>   → highest stable exact semver in `modules[0].versions[]` (the API is not sorted).
+> - **Guidance:** Azure MCP provides Azure Terraform documentation, best practices,
+>   AVM module READMEs (`avm get`) and provider docs (`azurerm get`, `azapi get`). Use it
+>   only for modules the index lists as published. `avm versions` reports a module absent from the AVM list
+>   as `status: 400` with `results.type: "ArgumentException"` and "not found in available modules"; only that
+>   response means "unpublished". Any other status or error is a verification failure — stop and escalate,
+>   do not emit a raw-resource exception. `avm get` on an unknown version returns `status: 422` (HTTP 404), and
+>   `azurerm get` returns `status: 200` even for unknown types: empty `arguments` plus a "Documentation not
+>   found" `summary` means the resource type does not exist.
 > - **Validator:** `npm run validate:avm-versions:freeze` (planner agents
 >   MUST call this before `apex-recall complete-step 4`).
 >

.github/skills/apex-azure-defaults/references/terraform-conventions.md

@@ -9,25 +9,26 @@ Use one source for each concern:
 | Need | Source |
 | --- | --- |
 | Azure Terraform guidance | Azure MCP documentation and best-practice tools |
-| Provider/module search and versions | Public Terraform Registry API |
+| Provider docs and AVM module READMEs | Azure MCP `azureterraform` (`azurerm get`, `azapi get`, `avm get`) |
+| Module versions | Azure MCP `azureterraform avm versions`, or the public Terraform Registry API |
+| Provider versions and search | Public Terraform Registry API |
 | Initialized provider resource schemas | `terraform providers schema -json` |
 | Existing Azure resource IDs | Azure MCP resource tools or Azure CLI |
 
-Resolve an AVM-TF module version directly from the Registry API:
+Resolve an AVM-TF module version with the Azure MCP `azureterraform avm versions` command, or directly from
+the Registry API:
 
 ```bash
 curl -sf https://registry.terraform.io/v1/modules/Azure/avm-res-{path}/azurerm/versions \
   | jq -r '[.modules[0].versions[].version | select(test("^[0-9]+\\.[0-9]+\\.[0-9]+$"))]
            | sort_by(split(".") | map(tonumber)) | last'
 ```
 
-The API does not return versions newest-first; always sort as above.
-
-Use `https://registry.terraform.io/v1/providers/{namespace}/{provider}/versions`
+The API does not return versions newest-first; always sort as above (apply the same stable-semver
+filter and sort to `avm versions` output). Use `https://registry.terraform.io/v1/providers/{namespace}/{provider}/versions`
 for provider versions with the same sort (`hashicorp/azurerm`, `hashicorp/random`,
 `Azure/azapi` — azapi is not under `hashicorp`). Run `terraform init` before
-`terraform providers schema -json`. Do not claim Azure MCP exposes Terraform
-Registry metadata.
+`terraform providers schema -json`. Azure MCP does not list provider versions; use the Registry API for those.
 
 ## Tag Syntax (HCL)
 

.github/skills/apex-azure-diagnostics/SKILL.md

@@ -117,9 +117,11 @@ For AI-powered diagnostics, use:
 ```
 mcp_azure-mcp_applens
   intent: "diagnose issues with <resource-name>"
-  command: "diagnose"
+  command: "applens_resource_diagnose"
   parameters:
-    resourceId: "<resource-id>"
+    resource: "<resource-name>"
+    question: "<what to diagnose>"
+    resource-group: "<resource-group>"
 
 Provides:
 - Automated issue detection
@@ -134,9 +136,11 @@ For querying logs and metrics:
 ```
 mcp_azure-mcp_monitor
   intent: "query logs for <resource-name>"
-  command: "logs_query"
+  command: "monitor_workspace_log_query"
   parameters:
-    workspaceId: "<workspace-id>"
+    subscription: "<subscription-id>"
+    workspace: "<workspace-name-or-id>"
+    table: "<table>"
     query: "<KQL-query>"
 ```
 

.github/skills/apex-azure-diagnostics/references/aks/general-diagnostics.md

@@ -45,12 +45,15 @@ For AI-powered diagnostics:
 ```text
 mcp_azure-mcp_applens
   intent: "diagnose AKS cluster issues"
-  command: "diagnose"
+  command: "applens_resource_diagnose"
   parameters:
-    resourceId: "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ContainerService/managedClusters/<cluster>"
+    resource: "<cluster>"
+    question: "diagnose AKS cluster issues"
+    resource-group: "<rg>"
+    resource-type: "Microsoft.ContainerService/managedClusters"
 ```
 
-> 💡 **Tip:** AppLens automatically detects common issues and provides remediation recommendations using the cluster resource ID.
+> 💡 **Tip:** AppLens automatically detects common issues and provides remediation recommendations for the named cluster.
 
 ---
 

.github/skills/apex-azure-validate/references/policy-validation.md

@@ -17,7 +17,7 @@ az account show --query id -o tsv
 Call the Azure MCP Policy tool to retrieve policies for your subscription:
 
 ```
-mcp_azure-mcp_policy(command: "list", parameters: { subscription_id: "<subscription-id>" })
+mcp_azure-mcp_policy(command: "policy_assignment_list", parameters: { subscription: "<subscription-id>" })
 ```
 
 Replace `<subscription-id>` with the actual subscription ID obtained from step 1.

.github/skills/apex-iac-common/references/avm-module-index.md

@@ -20,7 +20,9 @@ indexes** maintained by the Azure Verified Modules team.
 | `tools/scripts/_data/avm-module-cache.json` | Per-module version cache | MCR + `registry.terraform.io`, pre-warmed by the same refresh script               |
 
 The refresh script keeps all four files current; there is no need to
-hand-edit them. In consumer repositories the **Weekly Maintenance**
+hand-edit them. Agents may use Azure MCP `azureterraform` (`avm versions`, `avm get`) for live Terraform
+version and README lookup, but this index stays the source for module existence, lifecycle status and
+resource-type mapping, and the cache stays pre-warmed by the refresh script. In consumer repositories the **Weekly Maintenance**
 template (`refresh-avm-module-index` job) runs it and opens a refresh PR.
 That template does not run in APEX: APEX maintainers run
 `npm run refresh:avm-module-index` manually at least monthly and before

.github/skills/apex-iac-common/references/avm-version-freeze-gate.md

@@ -64,7 +64,8 @@ Re-resolve the latest stable version and update both the implementation
 plan and `04-iac-contract.json`:
 
 - Bicep: `curl -sf https://mcr.microsoft.com/v2/bicep/avm/res/{path}/tags/list`
-- Terraform: `curl -sf https://registry.terraform.io/v1/modules/Azure/avm-res-{path}/azurerm/versions`
+- Terraform: `curl -sf https://registry.terraform.io/v1/modules/Azure/avm-res-{path}/azurerm/versions`,
+  or Azure MCP `azureterraform avm versions --module-name avm-res-{path}`
 - Or use the corresponding MCP helpers.
 
 Re-run the validator until exit code 0.

.github/skills/apex-terraform-patterns/SKILL.md

@@ -34,7 +34,6 @@ Composable architecture building blocks for Azure Terraform. Complements
 | Plan Interpretation      | Pre-deployment validation and change analysis    | `references/plan-interpretation.md`        |
 | AVM Pitfalls             | Set-type diffs, provider pins, 4.x changes       | `references/avm-pitfalls.md`               |
 | Provider Compatibility   | Why azurerm 4.x / Terraform 1.11 floors          | `references/avm-provider-compatibility.md` |
-| AVM Authoring            | AVM certification requirements, compliance       | `references/avm-authoring-requirements.md` |
 | Module Refactoring       | Monolith → module extraction, state migration    | `references/refactor-module.md`            |
 
 ---
@@ -43,8 +42,8 @@ Composable architecture building blocks for Azure Terraform. Complements
 
 Wire AVM child modules by passing outputs as inputs (`module.<name>.<output>`); never
 hardcode IDs. **AVM-TF module versions in APEX-generated code MUST be exact semver
-(`version = "X.Y.Z"`)** — pinned at plan time from
-`registry.terraform.io` (newest stable in `modules[0].versions[]`). Range
+(`version = "X.Y.Z"`)** — pinned at plan time to the newest stable release (Azure MCP
+`azureterraform avm versions`, or `modules[0].versions[]` from `registry.terraform.io`). Range
 constraints (`~> X.Y`, `>= X.Y.Z`) are NOT allowed in `04-iac-contract.json` and
 will be flagged by `npm run validate:avm-versions`. Full code sample
 (resource group + key vault) and rationale in
@@ -115,6 +114,5 @@ Applying a Terraform pattern in a root module:
 | `references/bootstrap-backend-template.md` | Backend bootstrap template                                        |
 | `references/deploy-script-template.md`     | Deployment script template                                        |
 | `references/project-scaffold.md`           | Project scaffolding structure                                     |
-| `references/avm-authoring-requirements.md` | AVM certification: 37 requirements, compliance checklist          |
 | `references/refactor-module.md`            | Module extraction, state migration, refactoring patterns          |
 | `references/module-composition.md`         | Canonical AVM module composition example with output wiring       |