workspace-architect 1.3.0

package/assets/instructions/azure-verified-modules-terraform.instructions.md

@@ -0,0 +1,229 @@
+---
+description: ' Azure Verified Modules (AVM) and Terraform'
+applyTo: '**/*.terraform, **/*.tf, **/*.tfvars, **/*.tfstate, **/*.tflint.hcl, **/*.tf.json, **/*.tfvars.json'
+---
+
+# Azure Verified Modules (AVM) Terraform
+
+## Overview
+
+Azure Verified Modules (AVM) are pre-built, tested, and validated Terraform and Bicep modules that follow Azure best practices. Use these modules to create, update, or review Azure Infrastructure as Code (IaC) with confidence.
+
+## Custom Instructions for GitHub Copilot Agents
+
+**IMPORTANT**: When GitHub Copilot Agent or GitHub Copilot Coding Agent is working on this repository, the following local unit tests MUST be executed to comply with PR checks. Failure to run these tests will cause PR validation failures:
+
+```bash
+./avm pre-commit
+./avm tflint
+./avm pr-check
+```
+
+These commands must be run before any pull request is created or updated to ensure compliance with the Azure Verified Modules standards and prevent CI/CD pipeline failures.
+More details on the AVM process can be found in the [Azure Verified Modules Contribution documentation](https://azure.github.io/Azure-Verified-Modules/contributing/terraform/testing/).
+
+**Failure to run these tests will cause PR validation failures and prevent successful merges.**
+
+## Module Discovery
+
+### Terraform Registry
+
+- Search for "avm" + resource name
+- Filter by "Partner" tag to find official AVM modules
+- Example: Search "avm storage account" → filter by Partner
+
+### Official AVM Index
+
+> **Note:** The following links always point to the latest version of the CSV files on the main branch. As intended, this means the files may change over time. If you require a point-in-time version, consider using a specific release tag in the URL.
+
+- **Terraform Resource Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/TerraformResourceModules.csv`
+- **Terraform Pattern Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/TerraformPatternModules.csv`
+- **Terraform Utility Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/TerraformUtilityModules.csv`
+
+
+## Terraform Module Usage
+
+### From Examples
+
+1. Copy the example code from the module documentation
+2. Replace `source = "../../"` with `source = "Azure/avm-res-{service}-{resource}/azurerm"`
+3. Add `version = "~> 1.0"` (use latest available)
+4. Set `enable_telemetry = true`
+
+### From Scratch
+
+1. Copy the Provision Instructions from module documentation
+2. Configure required and optional inputs
+3. Pin the module version
+4. Enable telemetry
+
+### Example Usage
+
+```hcl
+module "storage_account" {
+  source  = "Azure/avm-res-storage-storageaccount/azurerm"
+  version = "~> 0.1"
+
+  enable_telemetry    = true
+  location            = "East US"
+  name                = "mystorageaccount"
+  resource_group_name = "my-rg"
+
+  # Additional configuration...
+}
+```
+
+## Naming Conventions
+
+### Module Types
+
+- **Resource Modules**: `Azure/avm-res-{service}-{resource}/azurerm`
+  - Example: `Azure/avm-res-storage-storageaccount/azurerm`
+- **Pattern Modules**: `Azure/avm-ptn-{pattern}/azurerm`
+  - Example: `Azure/avm-ptn-aks-enterprise/azurerm`
+- **Utility Modules**: `Azure/avm-utl-{utility}/azurerm`
+  - Example: `Azure/avm-utl-regions/azurerm`
+
+### Service Naming
+
+- Use kebab-case for services and resources
+- Follow Azure service names (e.g., `storage-storageaccount`, `network-virtualnetwork`)
+
+## Version Management
+
+### Check Available Versions
+
+- Endpoint: `https://registry.terraform.io/v1/modules/Azure/{module}/azurerm/versions`
+- Example: `https://registry.terraform.io/v1/modules/Azure/avm-res-storage-storageaccount/azurerm/versions`
+
+### Version Pinning Best Practices
+
+- Use pessimistic version constraints: `version = "~> 1.0"`
+- Pin to specific versions for production: `version = "1.2.3"`
+- Always review changelog before upgrading
+
+## Module Sources
+
+### Terraform Registry
+
+- **URL Pattern**: `https://registry.terraform.io/modules/Azure/{module}/azurerm/latest`
+- **Example**: `https://registry.terraform.io/modules/Azure/avm-res-storage-storageaccount/azurerm/latest`
+
+### GitHub Repository
+
+- **URL Pattern**: `https://github.com/Azure/terraform-azurerm-avm-{type}-{service}-{resource}`
+- **Examples**:
+  - Resource: `https://github.com/Azure/terraform-azurerm-avm-res-storage-storageaccount`
+  - Pattern: `https://github.com/Azure/terraform-azurerm-avm-ptn-aks-enterprise`
+
+## Development Best Practices
+
+### Module Usage
+
+- ✅ **Always** pin module and provider versions
+- ✅ **Start** with official examples from module documentation
+- ✅ **Review** all inputs and outputs before implementation
+- ✅ **Enable** telemetry: `enable_telemetry = true`
+- ✅ **Use** AVM utility modules for common patterns
+- ✅ **Follow** AzureRM provider requirements and constraints
+
+### Code Quality
+
+- ✅ **Always** run `terraform fmt` after making changes
+- ✅ **Always** run `terraform validate` after making changes
+- ✅ **Use** meaningful variable names and descriptions
+- ✅ **Add** proper tags and metadata
+- ✅ **Document** complex configurations
+
+### Validation Requirements
+
+Before creating or updating any pull request:
+
+```bash
+# Format code
+terraform fmt -recursive
+
+# Validate syntax
+terraform validate
+
+# AVM-specific validation (MANDATORY)
+./avm pre-commit
+./avm tflint
+./avm pr-check
+```
+
+## Tool Integration
+
+### Use Available Tools
+
+- **Deployment Guidance**: Use `azure_get_deployment_best_practices` tool
+- **Service Documentation**: Use `microsoft.docs.mcp` tool for Azure service-specific guidance
+- **Schema Information**: Use `azure_get_schema_for_Bicep` for Bicep resources
+
+### GitHub Copilot Integration
+
+When working with AVM repositories:
+
+1. Always check for existing modules before creating new resources
+2. Use the official examples as starting points
+3. Run all validation tests before committing
+4. Document any customizations or deviations from examples
+
+## Common Patterns
+
+### Resource Group Module
+
+```hcl
+module "resource_group" {
+  source  = "Azure/avm-res-resources-resourcegroup/azurerm"
+  version = "~> 0.1"
+
+  enable_telemetry = true
+  location         = var.location
+  name            = var.resource_group_name
+}
+```
+
+### Virtual Network Module
+
+```hcl
+module "virtual_network" {
+  source  = "Azure/avm-res-network-virtualnetwork/azurerm"
+  version = "~> 0.1"
+
+  enable_telemetry    = true
+  location            = module.resource_group.location
+  name                = var.vnet_name
+  resource_group_name = module.resource_group.name
+  address_space       = ["10.0.0.0/16"]
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Version Conflicts**: Always check compatibility between module and provider versions
+2. **Missing Dependencies**: Ensure all required resources are created first
+3. **Validation Failures**: Run AVM validation tools before committing
+4. **Documentation**: Always refer to the latest module documentation
+
+### Support Resources
+
+- **AVM Documentation**: `https://azure.github.io/Azure-Verified-Modules/`
+- **GitHub Issues**: Report issues in the specific module's GitHub repository
+- **Community**: Azure Terraform Provider GitHub discussions
+
+## Compliance Checklist
+
+Before submitting any AVM-related code:
+
+- [ ] Module version is pinned
+- [ ] Telemetry is enabled
+- [ ] Code is formatted (`terraform fmt`)
+- [ ] Code is validated (`terraform validate`)
+- [ ] AVM pre-commit checks pass (`./avm pre-commit`)
+- [ ] TFLint checks pass (`./avm tflint`)
+- [ ] AVM PR checks pass (`./avm pr-check`)
+- [ ] Documentation is updated
+- [ ] Examples are tested and working

package/assets/instructions/bicep-code-best-practices.instructions.md

@@ -0,0 +1,54 @@
+---
+description: 'Infrastructure as Code with Bicep'
+applyTo: '**/*.bicep'
+---
+
+## Naming Conventions
+
+-   When writing Bicep code, use lowerCamelCase for all names (variables, parameters, resources)
+-   Use resource type descriptive symbolic names (e.g., 'storageAccount' not 'storageAccountName')
+-   Avoid using 'name' in a symbolic name as it represents the resource, not the resource's name
+-   Avoid distinguishing variables and parameters by the use of suffixes
+
+## Structure and Declaration
+
+-   Always declare parameters at the top of files with @description decorators
+-   Use latest stable API versions for all resources
+-   Use descriptive @description decorators for all parameters
+-   Specify minimum and maximum character length for naming parameters
+
+## Parameters
+
+-   Set default values that are safe for test environments (use low-cost pricing tiers)
+-   Use @allowed decorator sparingly to avoid blocking valid deployments
+-   Use parameters for settings that change between deployments
+
+## Variables
+
+-   Variables automatically infer type from the resolved value
+-   Use variables to contain complex expressions instead of embedding them directly in resource properties
+
+## Resource References
+
+-   Use symbolic names for resource references instead of reference() or resourceId() functions
+-   Create resource dependencies through symbolic names (resourceA.id) not explicit dependsOn
+-   For accessing properties from other resources, use the 'existing' keyword instead of passing values through outputs
+
+## Resource Names
+
+-   Use template expressions with uniqueString() to create meaningful and unique resource names
+-   Add prefixes to uniqueString() results since some resources don't allow names starting with numbers
+
+## Child Resources
+
+-   Avoid excessive nesting of child resources
+-   Use parent property or nesting instead of constructing resource names for child resources
+
+## Security
+
+-   Never include secrets or keys in outputs
+-   Use resource properties directly in outputs (e.g., storageAccount.properties.primaryEndpoints)
+
+## Documentation
+
+-   Include helpful // comments within your Bicep files to improve readability

package/assets/instructions/blazor.instructions.md

@@ -0,0 +1,77 @@
+---
+description: 'Blazor component and application patterns'
+applyTo: '**/*.razor, **/*.razor.cs, **/*.razor.css'
+---
+
+## Blazor Code Style and Structure
+
+- Write idiomatic and efficient Blazor and C# code.
+- Follow .NET and Blazor conventions.
+- Use Razor Components appropriately for component-based UI development.
+- Prefer inline functions for smaller components but separate complex logic into code-behind or service classes.
+- Async/await should be used where applicable to ensure non-blocking UI operations.
+
+## Naming Conventions
+
+- Follow PascalCase for component names, method names, and public members.
+- Use camelCase for private fields and local variables.
+- Prefix interface names with "I" (e.g., IUserService).
+
+## Blazor and .NET Specific Guidelines
+
+- Utilize Blazor's built-in features for component lifecycle (e.g., OnInitializedAsync, OnParametersSetAsync).
+- Use data binding effectively with @bind.
+- Leverage Dependency Injection for services in Blazor.
+- Structure Blazor components and services following Separation of Concerns.
+- Always use the latest version C#, currently C# 13 features like record types, pattern matching, and global usings.
+
+## Error Handling and Validation
+
+- Implement proper error handling for Blazor pages and API calls.
+- Use logging for error tracking in the backend and consider capturing UI-level errors in Blazor with tools like ErrorBoundary.
+- Implement validation using FluentValidation or DataAnnotations in forms.
+
+## Blazor API and Performance Optimization
+
+- Utilize Blazor server-side or WebAssembly optimally based on the project requirements.
+- Use asynchronous methods (async/await) for API calls or UI actions that could block the main thread.
+- Optimize Razor components by reducing unnecessary renders and using StateHasChanged() efficiently.
+- Minimize the component render tree by avoiding re-renders unless necessary, using ShouldRender() where appropriate.
+- Use EventCallbacks for handling user interactions efficiently, passing only minimal data when triggering events.
+
+## Caching Strategies
+
+- Implement in-memory caching for frequently used data, especially for Blazor Server apps. Use IMemoryCache for lightweight caching solutions.
+- For Blazor WebAssembly, utilize localStorage or sessionStorage to cache application state between user sessions.
+- Consider Distributed Cache strategies (like Redis or SQL Server Cache) for larger applications that need shared state across multiple users or clients.
+- Cache API calls by storing responses to avoid redundant calls when data is unlikely to change, thus improving the user experience.
+
+## State Management Libraries
+
+- Use Blazor's built-in Cascading Parameters and EventCallbacks for basic state sharing across components.
+- Implement advanced state management solutions using libraries like Fluxor or BlazorState when the application grows in complexity.
+- For client-side state persistence in Blazor WebAssembly, consider using Blazored.LocalStorage or Blazored.SessionStorage to maintain state between page reloads.
+- For server-side Blazor, use Scoped Services and the StateContainer pattern to manage state within user sessions while minimizing re-renders.
+
+## API Design and Integration
+
+- Use HttpClient or other appropriate services to communicate with external APIs or your own backend.
+- Implement error handling for API calls using try-catch and provide proper user feedback in the UI.
+
+## Testing and Debugging in Visual Studio
+
+- All unit testing and integration testing should be done in Visual Studio Enterprise.
+- Test Blazor components and services using xUnit, NUnit, or MSTest.
+- Use Moq or NSubstitute for mocking dependencies during tests.
+- Debug Blazor UI issues using browser developer tools and Visual Studio's debugging tools for backend and server-side issues.
+- For performance profiling and optimization, rely on Visual Studio's diagnostics tools.
+
+## Security and Authentication
+
+- Implement Authentication and Authorization in the Blazor app where necessary using ASP.NET Identity or JWT tokens for API authentication.
+- Use HTTPS for all web communication and ensure proper CORS policies are implemented.
+
+## API Documentation and Swagger
+
+- Use Swagger/OpenAPI for API documentation for your backend API services.
+- Ensure XML documentation for models and API methods for enhancing Swagger documentation.