CHANGE: Add Azure Verified Modules Bicep instructions (#481)

- Introduced comprehensive documentation for Azure Verified Modules (AVM) and Bicep.
- Included guidelines for module discovery, usage, naming conventions, and best practices.
- Added validation requirements and troubleshooting tips for Bicep files.

docs/README.instructions.md

@@ -26,6 +26,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
 | [Azure Functions Typescript](../instructions/azure-functions-typescript.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-functions-typescript.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-functions-typescript.instructions.md) | TypeScript patterns for Azure Functions |
 | [Azure Logic Apps and Power Automate Instructions](../instructions/azure-logic-apps-power-automate.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-logic-apps-power-automate.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-logic-apps-power-automate.instructions.md) | Guidelines for developing Azure Logic Apps and Power Automate workflows with best practices for Workflow Definition Language (WDL), integration patterns, and enterprise automation |
 | [Azure Terraform Best Practices](../instructions/terraform-azure.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md) | Create or modify solutions built using Terraform on Azure. |
+| [Azure Verified Modules (AVM) Bicep](../instructions/azure-verified-modules-bicep.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-bicep.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-bicep.instructions.md) | Azure Verified Modules (AVM) and Bicep |
 | [Azure Verified Modules (AVM) Terraform](../instructions/azure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md) |  Azure Verified Modules (AVM) and Terraform |
 | [Best Practices and Guidance for Code Components](../instructions/pcf-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-best-practices.instructions.md) | Best practices and guidance for developing PCF code components |
 | [Bicep Code Best Practices](../instructions/bicep-code-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md) | Infrastructure as Code with Bicep |

instructions/azure-verified-modules-bicep.instructions.md

@@ -0,0 +1,205 @@
+---
+description: 'Azure Verified Modules (AVM) and Bicep'
+applyTo: '**/*.bicep, **/*.bicepparam'
+---
+
+# Azure Verified Modules (AVM) Bicep
+
+## Overview
+
+Azure Verified Modules (AVM) are pre-built, tested, and validated Bicep modules that follow Azure best practices. Use these modules to create, update, or review Azure Infrastructure as Code (IaC) with confidence.
+
+## Module Discovery
+
+### Bicep Public Registry
+
+- Search for modules: `br/public:avm/res/{service}/{resource}:{version}`
+- Browse available modules: `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res`
+- Example: `br/public:avm/res/storage/storage-account:0.30.0`
+
+### Official AVM Index
+
+- **Bicep Resource Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/BicepResourceModules.csv`
+- **Bicep Pattern Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/BicepPatternModules.csv`
+
+### Module Documentation
+
+- **GitHub Repository**: `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource}`
+- **README**: Each module contains comprehensive documentation with examples
+
+## Module Usage
+
+### From Examples
+
+1. Review module README in `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource}`
+2. Copy example code from module documentation
+3. Reference module using `br/public:avm/res/{service}/{resource}:{version}`
+4. Configure required and optional parameters
+
+### Example Usage
+
+```bicep
+module storageAccount 'br/public:avm/res/storage/storage-account:0.30.0' = {
+  name: 'storage-account-deployment'
+  scope: resourceGroup()
+  params: {
+    name: storageAccountName
+    location: location
+    skuName: 'Standard_LRS'
+    tags: tags
+  }
+}
+```
+
+### When AVM Module Not Available
+
+If no AVM module exists for a resource type, use native Bicep resource declarations with latest stable API version.
+
+## Naming Conventions
+
+### Module References
+
+- **Resource Modules**: `br/public:avm/res/{service}/{resource}:{version}`
+- **Pattern Modules**: `br/public:avm/ptn/{pattern}:{version}`
+- Example: `br/public:avm/res/network/virtual-network:0.7.2`
+
+### Symbolic Names
+
+- Use lowerCamelCase for all names (variables, parameters, resources, modules)
+- Use resource type descriptive names (e.g., `storageAccount` not `storageAccountName`)
+- Avoid 'name' suffix in symbolic names as they represent the resource, not the resource's name
+- Avoid distinguishing variables and parameters by suffixes
+
+## Version Management
+
+### Version Pinning Best Practices
+
+- Always pin to specific module versions: `:{version}`
+- Use semantic versioning (e.g., `:0.30.0`)
+- Review module changelog before upgrading
+- Test version upgrades in non-production environments first
+
+## Development Best Practices
+
+### Module Discovery and Usage
+
+- ✅ **Always** check for existing AVM modules before creating raw resources
+- ✅ **Review** module documentation and examples before implementation
+- ✅ **Pin** module versions explicitly
+- ✅ **Use** types from modules when available (import types from module)
+- ✅ **Prefer** AVM modules over raw resource declarations
+
+### Code Structure
+
+- ✅ **Declare** parameters at top of file with `@sys.description()` decorators
+- ✅ **Specify** `@minLength()` and `@maxLength()` for naming parameters
+- ✅ **Use** `@allowed()` decorator sparingly to avoid blocking valid deployments
+- ✅ **Set** default values safe for test environments (low-cost SKUs)
+- ✅ **Use** variables for complex expressions instead of embedding in resource properties
+- ✅ **Leverage** `loadJsonContent()` for external configuration files
+
+### Resource References
+
+- ✅ **Use** symbolic names for references (e.g., `storageAccount.id`) not `reference()` or `resourceId()`
+- ✅ **Create** dependencies through symbolic names, not explicit `dependsOn`
+- ✅ **Use** `existing` keyword for accessing properties from other resources
+- ✅ **Access** module outputs via dot notation (e.g., `storageAccount.outputs.resourceId`)
+
+### Resource Naming
+
+- ✅ **Use** `uniqueString()` with meaningful prefixes for unique names
+- ✅ **Add** prefixes since some resources don't allow names starting with numbers
+- ✅ **Respect** resource-specific naming constraints (length, characters)
+
+### Child Resources
+
+- ✅ **Avoid** excessive nesting of child resources
+- ✅ **Use** `parent` property or nesting instead of constructing names manually
+
+### Security
+
+- ❌ **Never** include secrets or keys in outputs
+- ✅ **Use** resource properties directly in outputs (e.g., `storageAccount.outputs.primaryBlobEndpoint`)
+- ✅ **Enable** managed identities where possible
+- ✅ **Disable** public access when network isolation is enabled
+
+### Types
+
+- ✅ **Import** types from modules when available: `import { deploymentType } from './module.bicep'`
+- ✅ **Use** user-defined types for complex parameter structures
+- ✅ **Leverage** type inference for variables
+
+### Documentation
+
+- ✅ **Include** helpful `//` comments for complex logic
+- ✅ **Use** `@sys.description()` on all parameters with clear explanations
+- ✅ **Document** non-obvious design decisions
+
+## Validation Requirements
+
+### Build Validation (MANDATORY)
+
+After any changes to Bicep files, run the following commands to ensure all files build successfully:
+
+```shell
+# Ensure Bicep CLI is up to date
+az bicep upgrade
+
+# Build and validate changed Bicep files
+az bicep build --file main.bicep
+```
+
+### Bicep Parameter Files
+
+- ✅ **Always** update accompanying `*.bicepparam` files when modifying `*.bicep` files
+- ✅ **Validate** parameter files match current parameter definitions
+- ✅ **Test** deployments with parameter files before committing
+
+## Tool Integration
+
+### Use Available Tools
+
+- **Schema Information**: Use `azure_get_schema_for_Bicep` for resource schemas
+- **Deployment Guidance**: Use `azure_get_deployment_best_practices` tool
+- **Service Documentation**: Use `microsoft.docs.mcp` for Azure service-specific guidance
+
+### GitHub Copilot Integration
+
+When working with Bicep:
+
+1. Check for existing AVM modules before creating resources
+2. Use official module examples as starting points
+3. Run `az bicep build` after all changes
+4. Update accompanying `.bicepparam` files
+5. Document customizations or deviations from examples
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Module Version**: Always specify exact version in module reference
+2. **Missing Dependencies**: Ensure resources are created before dependent modules
+3. **Validation Failures**: Run `az bicep build` to identify syntax/type errors
+4. **Parameter Files**: Ensure `.bicepparam` files are updated when parameters change
+
+### Support Resources
+
+- **AVM Documentation**: `https://azure.github.io/Azure-Verified-Modules/`
+- **Bicep Registry**: `https://github.com/Azure/bicep-registry-modules`
+- **Bicep Documentation**: `https://learn.microsoft.com/azure/azure-resource-manager/bicep/`
+- **Best Practices**: `https://learn.microsoft.com/azure/azure-resource-manager/bicep/best-practices`
+
+## Compliance Checklist
+
+Before submitting any Bicep code:
+
+- [ ] AVM modules used where available
+- [ ] Module versions are pinned
+- [ ] Code builds successfully (`az bicep build`)
+- [ ] Accompanying `.bicepparam` files updated
+- [ ] `@sys.description()` on all parameters
+- [ ] Symbolic names used for references
+- [ ] No secrets in outputs
+- [ ] Types imported/defined where appropriate
+- [ ] Comments added for complex logic
+- [ ] Follows lowerCamelCase naming convention