From 6c6b793fefe8a42402bbca735b9e884cb4feb34f Mon Sep 17 00:00:00 2001 From: webreidi Date: Fri, 27 Jun 2025 08:54:16 -0700 Subject: [PATCH 01/10] Add guidelines for C# development and MAUI patterns --- instructions/blazor.md | 2 +- instructions/csharp.md | 113 ++++++++++++++++++++++++++++++++++++ instructions/dotnet-maui.md | 67 +++++++++++++++++++++ 3 files changed, 181 insertions(+), 1 deletion(-) create mode 100644 instructions/csharp.md create mode 100644 instructions/dotnet-maui.md diff --git a/instructions/blazor.md b/instructions/blazor.md index 74642b3..c9aa40d 100644 --- a/instructions/blazor.md +++ b/instructions/blazor.md @@ -23,7 +23,7 @@ appliesTo: "**/*.razor, **/*.cs" - Use data binding effectively with @bind. - Leverage Dependency Injection for services in Blazor. - Structure Blazor components and services following Separation of Concerns. -- Use C# 10+ features like record types, pattern matching, and global usings. +- Always use the latest version C#, currently C# 13 features like record types, pattern matching, and global usings. ## Error Handling and Validation diff --git a/instructions/csharp.md b/instructions/csharp.md new file mode 100644 index 0000000..c12d7aa --- /dev/null +++ b/instructions/csharp.md @@ -0,0 +1,113 @@ +--- +description: Guidelines for building C# applications +--- + +# C# Development + +## C# Instructions +- Always use the latest version C#, currently C# 13 features. +- Write clear and concise comments for each function. + +## General Instructions +- Make only high confidence suggestions when reviewing code changes. +- Write code with good maintainability practices, including comments on why certain design decisions were made. +- Handle edge cases and write clear exception handling. +- For libraries or external dependencies, mention their usage and purpose in comments. + +## 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). + +## Formatting + +- Apply code-formatting style defined in `.editorconfig`. +- Prefer file-scoped namespace declarations and single-line using directives. +- Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.). +- Ensure that the final return statement of a method is on its own line. +- Use pattern matching and switch expressions wherever possible. +- Use `nameof` instead of string literals when referring to member names. +- Ensure that XML doc comments are created for any public APIs. When applicable, include `` and `` documentation in the comments. + +## Project Setup and Structure + +- Guide users through creating a new .NET project with the appropriate templates. +- Explain the purpose of each generated file and folder to build understanding of the project structure. +- Demonstrate how to organize code using feature folders or domain-driven design principles. +- Show proper separation of concerns with models, services, and data access layers. +- Explain the Program.cs and configuration system in ASP.NET Core 9 including environment-specific settings. + +## Nullable Reference Types + +- Declare variables non-nullable, and check for `null` at entry points. +- Always use `is null` or `is not null` instead of `== null` or `!= null`. +- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null. + +## Data Access Patterns + +- Guide the implementation of a data access layer using Entity Framework Core. +- Explain different options (SQL Server, SQLite, In-Memory) for development and production. +- Demonstrate repository pattern implementation and when it's beneficial. +- Show how to implement database migrations and data seeding. +- Explain efficient query patterns to avoid common performance issues. + +## Authentication and Authorization + +- Guide users through implementing authentication using JWT Bearer tokens. +- Explain OAuth 2.0 and OpenID Connect concepts as they relate to ASP.NET Core. +- Show how to implement role-based and policy-based authorization. +- Demonstrate integration with Microsoft Entra ID (formerly Azure AD). +- Explain how to secure both controller-based and Minimal APIs consistently. + +## Validation and Error Handling + +- Guide the implementation of model validation using data annotations and FluentValidation. +- Explain the validation pipeline and how to customize validation responses. +- Demonstrate a global exception handling strategy using middleware. +- Show how to create consistent error responses across the API. +- Explain problem details (RFC 7807) implementation for standardized error responses. + +## API Versioning and Documentation + +- Guide users through implementing and explaining API versioning strategies. +- Demonstrate Swagger/OpenAPI implementation with proper documentation. +- Show how to document endpoints, parameters, responses, and authentication. +- Explain versioning in both controller-based and Minimal APIs. +- Guide users on creating meaningful API documentation that helps consumers. + +## Logging and Monitoring + +- Guide the implementation of structured logging using Serilog or other providers. +- Explain the logging levels and when to use each. +- Demonstrate integration with Application Insights for telemetry collection. +- Show how to implement custom telemetry and correlation IDs for request tracking. +- Explain how to monitor API performance, errors, and usage patterns. + +## Testing + +- Always include test cases for critical paths of the application. +- Guide users through creating unit tests. +- Do not emit "Act", "Arrange" or "Assert" comments. +- Copy existing style in nearby files for test method names and capitalization. +- Explain integration testing approaches for API endpoints. +- Demonstrate how to mock dependencies for effective testing. +- Show how to test authentication and authorization logic. +- Explain test-driven development principles as applied to API development. + +## Performance Optimization + +- Guide users on implementing caching strategies (in-memory, distributed, response caching). +- Explain asynchronous programming patterns and why they matter for API performance. +- Demonstrate pagination, filtering, and sorting for large data sets. +- Show how to implement compression and other performance optimizations. +- Explain how to measure and benchmark API performance. + +## Deployment and DevOps + +- Guide users through containerizing their API using .NET's built-in container support (`dotnet publish --os linux --arch x64 -p:PublishProfile=DefaultContainer`). +- Explain the differences between manual Dockerfile creation and .NET's container publishing features. +- Explain CI/CD pipelines for NET applications. +- Demonstrate deployment to Azure App Service, Azure Container Apps, or other hosting options. +- Show how to implement health checks and readiness probes. +- Explain environment-specific configurations for different deployment stages. diff --git a/instructions/dotnet-maui.md b/instructions/dotnet-maui.md new file mode 100644 index 0000000..e5e7e41 --- /dev/null +++ b/instructions/dotnet-maui.md @@ -0,0 +1,67 @@ +--- +description: MAUI component and application patterns +appliesTo: "**/*.xaml, **/*.cs" +--- + +## MAUI Code Style and Structure + +- Write idiomatic and efficient MAUI and C# code. +- Follow .NET and MAUI conventions. +- 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). + +## MAUI and .NET Specific Guidelines + +- Utilize MAUI's built-in features for component lifecycle (e.g. OnAppearing, OnDisappearing). +- Use data binding effectively with {Binding}. +- Structure MAUI 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 MAUI pages and API calls. +- Use logging for error tracking in the backend and consider capturing UI-level errors in MAUI with tools like MAUI Community Toolkit's Logger. +- Implement validation using FluentValidation or DataAnnotations in forms. + +## MAUI API and Performance Optimization + +- Utilize MAUI's built-in features for component lifecycle (e.g. OnAppearing, OnDisappearing). +- Use asynchronous methods (async/await) for API calls or UI actions that could block the main thread. +- Optimize MAUI components by reducing unnecessary renders and using OnPropertyChanged() efficiently. +- Minimize the component render tree by avoiding re-renders unless necessary, using BatchBegin() and BatchCommit() where appropriate. + +## Caching Strategies + +- Implement in-memory caching for frequently used data, especially for MAUI apps. Use IMemoryCache for lightweight caching solutions. +- 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 dependency injection and the .NET MAUI Community Toolkit for state sharing across components. + +## 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 + +- Test components and services using xUnit, NUnit, or MSTest. +- Use Moq or NSubstitute for mocking dependencies during tests. + +## Security and Authentication + +- Implement Authentication and Authorization in the MAUI app where necessary using OAuth 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. From f7f6ac7d3d1eb3374ef8ed1edd495f90f29169fa Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Wed, 2 Jul 2025 17:55:56 +1000 Subject: [PATCH 02/10] Fixing README from merge --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 59584ae..2a9435e 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for - [Blazor](instructions/blazor.md) - Blazor component and application patterns - [Cmake Vcpkg](instructions/cmake-vcpkg.md) - C++ project configuration and package management - [Copilot Process tracking Instructions](instructions/copilot-thought-logging.instructions.md) - See process Copilot is following where you can edit this to reshape the interaction or save when follow up may be needed +- [C# Development](instructions/csharp.md) - Guidelines for building C# applications +- [Dotnet Maui](instructions/dotnet-maui.md) - MAUI component and application patterns - [Genaiscript](instructions/genaiscript.md) - AI-powered script generation guidelines - [Generate Modern Terraform Code For Azure](instructions/generate-modern-terraform-code-for-azure.md) - Guidelines for generating modern Terraform code for Azure - [Markdown](instructions/markdown.md) - Documentation and content creation standards From fdca96c3c92d3da410298c75d60a1bfb5016ac69 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Wed, 2 Jul 2025 09:57:38 +0200 Subject: [PATCH 03/10] Add Azure Cost Optimization workflow prompt with detailed steps and error handling --- prompts/az-cost-optimize.prompt.md | 303 +++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 prompts/az-cost-optimize.prompt.md diff --git a/prompts/az-cost-optimize.prompt.md b/prompts/az-cost-optimize.prompt.md new file mode 100644 index 0000000..024da1e --- /dev/null +++ b/prompts/az-cost-optimize.prompt.md @@ -0,0 +1,303 @@ +--- +mode: agent +description: Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. +--- + +## Overview +This workflow analyzes Infrastructure-as-Code (IaC) files and Azure resources to generate cost optimization recommendations. It creates individual GitHub issues for each optimization opportunity plus one EPIC issue to coordinate implementation, enabling efficient tracking and execution of cost savings initiatives. + +## Prerequisites +- Azure MCP server configured and authenticated +- GitHub MCP server configured and authenticated +- Target GitHub repository identified +- Azure resources deployed (IaC files optional but helpful) +- Prefer Azure MCP tools (`azmcp-*`) over direct Azure CLI when available + +## Workflow Steps + +### Step 1: Get Azure Best Practices +**Action**: Retrieve cost optimization best practices before analysis +**Tools**: Azure MCP best practices tool +**Process**: +1. **Load Best Practices**: + - Execute `azmcp-bestpractices-get` to get some of the latest Azure optimization guidelines. This may not cover all scenarios but provides a foundation. + - Use these practices to inform subsequent analysis and recommendations as possible + - Reference best practices in optimization recommendations, either from the MCP tool output or general Azure documentation + +### Step 2: Discover Azure Infrastructure +**Action**: Dynamically discover and analyze Azure resources and configurations +**Tools**: Azure MCP tools + Azure CLI fallback + Local file system access +**Process**: +1. **Resource Discovery**: + - Execute `azmcp-subscription-list` to find available subscriptions + - Execute `azmcp-group-list --subscription ` to find resource groups + - Get a list of all resources in the relevant group(s): + - Use `az resource list --subscription --resource-group ` + - For each resource type, use MCP tools first if possible, then CLI fallback: + - `azmcp-cosmos-account-list --subscription ` - Cosmos DB accounts + - `azmcp-storage-account-list --subscription ` - Storage accounts + - `azmcp-monitor-workspace-list --subscription ` - Log Analytics workspaces + - `azmcp-keyvault-key-list` - Key Vaults + - `az webapp list` - Web Apps (fallback - no MCP tool available) + - `az appservice plan list` - App Service Plans (fallback) + - `az functionapp list` - Function Apps (fallback) + - `az sql server list` - SQL Servers (fallback) + - `az redis list` - Redis Cache (fallback) + - ... and so on for other resource types + +2. **IaC Detection**: + - Use `file_search` to scan for IaC files: "**/*.bicep", "**/*.tf", "**/main.json", "**/*template*.json" + - Parse resource definitions to understand intended configurations + - Compare against discovered resources to identify discrepancies + - Note presence of IaC files for implementation recommendations later on + - Do NOT use any other file from the repository, only IaC files. Using other files like markdown or text files is NOT allowed as it is not a source of truth. + +3. **Configuration Analysis**: + - Extract current SKUs, tiers, and settings for each resource + - Identify resource relationships and dependencies + - Map resource utilization patterns where available + +### Step 3: Collect Usage Metrics & Validate Current Costs +**Action**: Gather utilization data AND verify actual resource costs +**Tools**: Azure MCP monitoring tools + Azure CLI +**Process**: +1. **Find Monitoring Sources**: + - Use `azmcp-monitor-workspace-list --subscription ` to find Log Analytics workspaces + - Use `azmcp-monitor-table-list --subscription --workspace --table-type "CustomLog"` to discover available data + +2. **Execute Usage Queries**: + - Use `azmcp-monitor-log-query` with these predefined queries: + - Query: "recent" for recent activity patterns + - Query: "errors" for error-level logs indicating issues + - For custom analysis, use KQL queries: + ```kql + // CPU utilization for App Services + AppServiceAppLogs + | where TimeGenerated > ago(7d) + | summarize avg(CpuTime) by Resource, bin(TimeGenerated, 1h) + + // Cosmos DB RU consumption + AzureDiagnostics + | where ResourceProvider == "MICROSOFT.DOCUMENTDB" + | where TimeGenerated > ago(7d) + | summarize avg(RequestCharge) by Resource + + // Storage account access patterns + StorageBlobLogs + | where TimeGenerated > ago(7d) + | summarize RequestCount=count() by AccountName, bin(TimeGenerated, 1d) + ``` + +3. **Calculate Baseline Metrics**: + - CPU/Memory utilization averages + - Database throughput patterns + - Storage access frequency + - Function execution rates + +4. **VALIDATE CURRENT COSTS**: + - Using the SKU/tier configurations discovered in Step 2 + - Look up current Azure pricing at https://azure.microsoft.com/pricing/ or use `az billing` commands + - Document: Resource → Current SKU → Estimated monthly cost + - Calculate realistic current monthly total before proceeding to recommendations + +### Step 4: Generate Cost Optimization Recommendations +**Action**: Analyze resources to identify optimization opportunities +**Tools**: Local analysis using collected data +**Process**: +1. **Apply Optimization Patterns** based on resource types found: + + **Compute Optimizations**: + - App Service Plans: Right-size based on CPU/memory usage + - Function Apps: Premium → Consumption plan for low usage + - Virtual Machines: Scale down oversized instances + + **Database Optimizations**: + - Cosmos DB: + - Provisioned → Serverless for variable workloads + - Right-size RU/s based on actual usage + - SQL Database: Right-size service tiers based on DTU usage + + **Storage Optimizations**: + - Implement lifecycle policies (Hot → Cool → Archive) + - Consolidate redundant storage accounts + - Right-size storage tiers based on access patterns + + **Infrastructure Optimizations**: + - Remove unused/redundant resources + - Implement auto-scaling where beneficial + - Schedule non-production environments + +2. **Calculate Evidence-Based Savings**: + - Current validated cost → Target cost = Savings + - Document pricing source for both current and target configurations + +3. **Calculate Priority Score** for each recommendation: + ``` + Priority Score = (Value Score × Monthly Savings) / (Risk Score × Implementation Days) + + High Priority: Score > 20 + Medium Priority: Score 5-20 + Low Priority: Score < 5 + ``` + +4. **Validate Recommendations**: + - Ensure Azure CLI commands are accurate + - Verify estimated savings calculations + - Assess implementation risks and prerequisites + - Ensure all savings calculations have supporting evidence + +### Step 5: User Confirmation +**Action**: Present summary and get approval before creating GitHub issues +**Process**: +1. **Display Optimization Summary**: + ``` + 🎯 Azure Cost Optimization Summary + + 📊 Analysis Results: + • Total Resources Analyzed: X + • Current Monthly Cost: $X + • Potential Monthly Savings: $Y + • Optimization Opportunities: Z + • High Priority Items: N + + 🏆 Recommendations: + 1. [Resource]: [Current SKU] → [Target SKU] = $X/month savings - [Risk Level] | [Implementation Effort] + 2. [Resource]: [Current Config] → [Target Config] = $Y/month savings - [Risk Level] | [Implementation Effort] + 3. [Resource]: [Current Config] → [Target Config] = $Z/month savings - [Risk Level] | [Implementation Effort] + ... and so on + + 💡 This will create: + • Y individual GitHub issues (one per optimization) + • 1 EPIC issue to coordinate implementation + + ❓ Proceed with creating GitHub issues? (y/n) + ``` + +2. **Wait for User Confirmation**: Only proceed if user confirms + +### Step 6: Create Individual Optimization Issues +**Action**: Create separate GitHub issues for each optimization opportunity. Label them with "cost-optimization" (green color), "azure" (blue color). +**MCP Tools Required**: `create_issue` for each recommendation +**Process**: +1. **Create Individual Issues** using this template: + + **Title Format**: `[COST-OPT] [Resource Type] - [Brief Description] - $X/month savings` + + **Body Template**: + ```markdown + ## 💰 Cost Optimization: [Brief Title] + + **Monthly Savings**: $X | **Risk Level**: [Low/Medium/High] | **Implementation Effort**: X days + + ### 📋 Description + [Clear explanation of the optimization and why it's needed] + + ### 🔧 Implementation + + **IaC Files Detected**: [Yes/No - based on file_search results] + + ```bash + # If IaC files found: Show IaC modifications + deployment + # File: infrastructure/bicep/modules/app-service.bicep + # Change: sku.name: 'S3' → 'B2' + az deployment group create --resource-group [rg] --template-file infrastructure/bicep/main.bicep + + # If no IaC files: Direct Azure CLI commands + warning + # ⚠️ No IaC files found. If they exist elsewhere, modify those instead. + az appservice plan update --name [plan] --sku B2 + ``` + + ### 📊 Evidence + - Current Configuration: [details] + - Usage Pattern: [evidence from monitoring data] + - Cost Impact: $X/month → $Y/month + - Best Practice Alignment: [reference to Azure best practices if applicable] + + ### ✅ Validation Steps + - [ ] Test in non-production environment + - [ ] Verify no performance degradation + - [ ] Confirm cost reduction in Azure Cost Management + - [ ] Update monitoring and alerts if needed + + ### ⚠️ Risks & Considerations + - [Risk 1 and mitigation] + - [Risk 2 and mitigation] + + **Priority Score**: X | **Value**: X/10 | **Risk**: X/10 + ``` + +### Step 7: Create EPIC Coordinating Issue +**Action**: Create master issue to track all optimization work. Label it with "cost-optimization" (green color), "azure" (blue color), and "epic" (purple color). +**MCP Tools Required**: `create_issue` for EPIC +**Note about mermaid diagrams**: Ensure you verify mermaid syntax is correct and create the diagrams taking accessibility guidelines into account (styling, colors, etc.). +**Process**: +1. **Create EPIC Issue**: + + **Title**: `[EPIC] Azure Cost Optimization Initiative - $X/month potential savings` + + **Body Template**: + ```markdown + # 🎯 Azure Cost Optimization EPIC + + **Total Potential Savings**: $X/month | **Implementation Timeline**: X weeks + + ## 📊 Executive Summary + - **Resources Analyzed**: X + - **Optimization Opportunities**: Y + - **Total Monthly Savings Potential**: $X + - **High Priority Items**: N + + ## 🏗️ Current Architecture Overview + + ```mermaid + graph TB + subgraph "Resource Group: [name]" + [Generated architecture diagram showing current resources and costs] + end + ``` + + ## 📋 Implementation Tracking + + ### 🚀 High Priority (Implement First) + - [ ] #[issue-number]: [Title] - $X/month savings + - [ ] #[issue-number]: [Title] - $X/month savings + + ### ⚡ Medium Priority + - [ ] #[issue-number]: [Title] - $X/month savings + - [ ] #[issue-number]: [Title] - $X/month savings + + ### 🔄 Low Priority (Nice to Have) + - [ ] #[issue-number]: [Title] - $X/month savings + + ## 📈 Progress Tracking + - **Completed**: 0 of Y optimizations + - **Savings Realized**: $0 of $X/month + - **Implementation Status**: Not Started + + ## 🎯 Success Criteria + - [ ] All high-priority optimizations implemented + - [ ] >80% of estimated savings realized + - [ ] No performance degradation observed + - [ ] Cost monitoring dashboard updated + + ## 📝 Notes + - Review and update this EPIC as issues are completed + - Monitor actual vs. estimated savings + - Consider scheduling regular cost optimization reviews + ``` + +## Error Handling +- **Cost Validation**: If savings estimates lack supporting evidence or seem inconsistent with Azure pricing, re-verify configurations and pricing sources before proceeding +- **Azure Authentication Failure**: Provide manual Azure CLI setup steps +- **No Resources Found**: Create informational issue about Azure resource deployment +- **GitHub Creation Failure**: Output formatted recommendations to console +- **Insufficient Usage Data**: Note limitations and provide configuration-based recommendations only + +## Success Criteria +- ✅ All cost estimates verified against actual resource configurations and Azure pricing +- ✅ Individual issues created for each optimization (trackable and assignable) +- ✅ EPIC issue provides comprehensive coordination and tracking +- ✅ All recommendations include specific, executable Azure CLI commands +- ✅ Priority scoring enables ROI-focused implementation +- ✅ Architecture diagram accurately represents current state +- ✅ User confirmation prevents unwanted issue creation \ No newline at end of file From 7128f5b8373de9aefb6769d431b266bdd29e2962 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Wed, 2 Jul 2025 11:02:02 +0200 Subject: [PATCH 04/10] Add Azure Cost Optimization prompt and enhance IaC file handling instructions --- README.md | 3 +++ prompts/az-cost-optimize.prompt.md | 5 +++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 59584ae..c7f2af9 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,9 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi - [My Issues](prompts/my-issues.prompt.md) - [My Pull Requests](prompts/my-pull-requests.prompt.md) +### FinOps +- [Azure Cost Optimize](prompts/az-cost-optimize.prompt.md) - Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. + > 💡 **Usage**: Use `/prompt-name` in VS Code chat, run `Chat: Run Prompt` command, or hit the run button while you have a prompt open. diff --git a/prompts/az-cost-optimize.prompt.md b/prompts/az-cost-optimize.prompt.md index 024da1e..546bda5 100644 --- a/prompts/az-cost-optimize.prompt.md +++ b/prompts/az-cost-optimize.prompt.md @@ -21,7 +21,7 @@ This workflow analyzes Infrastructure-as-Code (IaC) files and Azure resources to **Process**: 1. **Load Best Practices**: - Execute `azmcp-bestpractices-get` to get some of the latest Azure optimization guidelines. This may not cover all scenarios but provides a foundation. - - Use these practices to inform subsequent analysis and recommendations as possible + - Use these practices to inform subsequent analysis and recommendations as much as possible - Reference best practices in optimization recommendations, either from the MCP tool output or general Azure documentation ### Step 2: Discover Azure Infrastructure @@ -50,7 +50,8 @@ This workflow analyzes Infrastructure-as-Code (IaC) files and Azure resources to - Parse resource definitions to understand intended configurations - Compare against discovered resources to identify discrepancies - Note presence of IaC files for implementation recommendations later on - - Do NOT use any other file from the repository, only IaC files. Using other files like markdown or text files is NOT allowed as it is not a source of truth. + - Do NOT use any other file from the repository, only IaC files. Using other files is NOT allowed as it is not a source of truth. + - If you do not find IaC files, then STOP and report no IaC files found to the user. 3. **Configuration Analysis**: - Extract current SKUs, tiers, and settings for each resource From 02909a6f8be46d4cf1e79615f5fad1454fefd867 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Wed, 2 Jul 2025 19:03:27 +1000 Subject: [PATCH 05/10] Adding workflow to ensure that the readme is correctly updated --- .github/workflows/validate-readme.yml | 75 +++++++++++++++++++++++++++ CONTRIBUTING.md | 2 + 2 files changed, 77 insertions(+) create mode 100644 .github/workflows/validate-readme.yml diff --git a/.github/workflows/validate-readme.yml b/.github/workflows/validate-readme.yml new file mode 100644 index 0000000..7a1efe1 --- /dev/null +++ b/.github/workflows/validate-readme.yml @@ -0,0 +1,75 @@ +name: Validate README.md + +on: + pull_request: + types: [opened, synchronize, reopened] + paths: + - "instructions/**" + - "prompts/**" + - "chatmodes/**" + - "*.js" + +jobs: + validate-readme: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Update README.md + run: node update-readme.js + + - name: Check for README.md changes + id: check-diff + run: | + if git diff --exit-code README.md; then + echo "No changes to README.md after running update script." + echo "status=success" >> $GITHUB_OUTPUT + else + echo "Changes detected in README.md after running update script." + echo "status=failure" >> $GITHUB_OUTPUT + echo "diff<> $GITHUB_OUTPUT + git diff README.md >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Comment on PR if README.md needs updating + if: steps.check-diff.outputs.status == 'failure' + uses: actions/github-script@v7 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const diff = `${{ steps.check-diff.outputs.diff }}`; + const body = `## ⚠️ README.md needs to be updated + + The \`update-readme.js\` script detected changes that need to be made to the README.md file. + + Please run \`node update-readme.js\` locally and commit the changes before merging this PR. + +
+ View diff + + \`\`\`diff + ${diff} + \`\`\` +
`; + + github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: body + }); + + - name: Fail workflow if README.md needs updating + if: steps.check-diff.outputs.status == 'failure' + run: | + echo "❌ README.md needs to be updated. Please run 'node update-readme.js' locally and commit the changes." + exit 1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index adf3520..5c8ac13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,8 @@ Your goal is to... 2. **Create a new branch** for your contribution 3. **Add your instruction or prompt file** following the guidelines above 4. **Run the update script** (optional): `node update-readme.js` to update the README with your new file + - A GitHub Actions workflow will verify that this step was performed correctly + - If the README.md would be modified by running the script, the PR check will fail with a comment showing the required changes 5. **Submit a pull request** with: - A clear title describing your contribution - A brief description of what your instruction/prompt does From 1a19f1e26662e70eb9893c102f1c3fd9bda8f696 Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Wed, 2 Jul 2025 19:21:48 +1000 Subject: [PATCH 06/10] update workflow --- .github/workflows/validate-readme.yml | 31 +++++++++++---------------- 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/.github/workflows/validate-readme.yml b/.github/workflows/validate-readme.yml index 7a1efe1..e469a65 100644 --- a/.github/workflows/validate-readme.yml +++ b/.github/workflows/validate-readme.yml @@ -11,6 +11,9 @@ on: jobs: validate-readme: + permissions: + pull-requests: write + contents: read runs-on: ubuntu-latest steps: - name: Checkout code @@ -42,31 +45,23 @@ jobs: - name: Comment on PR if README.md needs updating if: steps.check-diff.outputs.status == 'failure' - uses: actions/github-script@v7 + uses: marocchino/sticky-pull-request-comment@v2 with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const diff = `${{ steps.check-diff.outputs.diff }}`; - const body = `## ⚠️ README.md needs to be updated + header: readme-validation + message: | + ## ⚠️ README.md needs to be updated - The \`update-readme.js\` script detected changes that need to be made to the README.md file. + The `update-readme.js` script detected changes that need to be made to the README.md file. - Please run \`node update-readme.js\` locally and commit the changes before merging this PR. + Please run `node update-readme.js` locally and commit the changes before merging this PR.
View diff - \`\`\`diff - ${diff} - \`\`\` -
`; - - github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: context.issue.number, - body: body - }); + ```diff + ${{ steps.check-diff.outputs.diff }} + ``` + - name: Fail workflow if README.md needs updating if: steps.check-diff.outputs.status == 'failure' From 0844c87740b0e48f8eb06fb60cf6ed971eefcccb Mon Sep 17 00:00:00 2001 From: Peli de Halleux Date: Wed, 2 Jul 2025 03:36:53 -0700 Subject: [PATCH 07/10] Update genaiscript.md Pointing to online llms.txt source. --- instructions/genaiscript.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/instructions/genaiscript.md b/instructions/genaiscript.md index adc96ab..7a14eeb 100644 --- a/instructions/genaiscript.md +++ b/instructions/genaiscript.md @@ -10,8 +10,7 @@ or answer questions about GenAIScript. ## Reference -- [GenAIScript docs](../../.genaiscript/docs/llms-full.txt) -- [GenAIScript ambient type definitions](../../.genaiscript/genaiscript.d.ts) +- [GenAIScript llms.txt](https://microsoft.github.io/genaiscript/llms.txt) ## Guidance for Code Generation @@ -19,4 +18,4 @@ or answer questions about GenAIScript. - you prefer using APIs from GenAIScript 'genaiscript.d.ts' rather node.js. Avoid node.js imports. - you keep the code simple, avoid exception handlers or error checking. - you add TODOs where you are unsure so that the user can review them -- you use the global types in genaiscript.d.ts are already loaded in the global context, no need to import them. \ No newline at end of file +- you use the global types in genaiscript.d.ts are already loaded in the global context, no need to import them. From 9b202e88d521f179dac97176eb0cfb9bf3b5dc3b Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Wed, 2 Jul 2025 20:39:00 +1000 Subject: [PATCH 08/10] C# member documentatino prompt --- prompts/csharp-docs.prompt.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 prompts/csharp-docs.prompt.md diff --git a/prompts/csharp-docs.prompt.md b/prompts/csharp-docs.prompt.md new file mode 100644 index 0000000..6f82916 --- /dev/null +++ b/prompts/csharp-docs.prompt.md @@ -0,0 +1,23 @@ +--- +mode: "agent" +tools: ["changes", "codebase", "editFiles", "problems"] +description: "Ensure that C# types are documented with XML comments and follow best practices for documentation." +--- + +# C# Documentation Best Practices + +- Public members should be documented with XML comments. +- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory. +- Use `` for method descriptions. This should be a brief overview of what the method does. +- Use `` for method parameters. +- Use `` for method return values. +- Use `` for additional information, which can include implementation details, usage notes, or any other relevant context. +- Use `` for usage examples on how to use the the member. +- Use `` to document exceptions thrown by methods. +- Use `` and `` for references to other types or members. +- Use `` to inherit documentation from base classes or interfaces. + - Unless there is major behavior change, in which case you should document the differences. +- Use `` for type parameters in generic types or methods. +- Use `` to reference type parameters in documentation. +- Use `` for inline code snippets. +- Use `` for code blocks. From eddac3934f017ed37568f434c6ca4c9facd205bb Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Wed, 2 Jul 2025 20:40:25 +1000 Subject: [PATCH 09/10] Updating readme --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 3b7ac47..7aafecc 100644 --- a/README.md +++ b/README.md @@ -60,12 +60,11 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi - [Generate Specs as Issues](prompts/gen-specs-as-issues.prompt.md) - Convert requirements into GitHub issues - [My Issues](prompts/my-issues.prompt.md) - [My Pull Requests](prompts/my-pull-requests.prompt.md) +- [C# Documentation Best Practices](prompts/csharp-docs.prompt.md) - Ensure that C# types are documented with XML comments and follow best practices for documentation. ### FinOps - [Azure Cost Optimize](prompts/az-cost-optimize.prompt.md) - Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. - - > 💡 **Usage**: Use `/prompt-name` in VS Code chat, run `Chat: Run Prompt` command, or hit the run button while you have a prompt open. ## 🧩 Custom Chat Modes From e30b801289139663a651b2865cd53e6be5d9d8ca Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Wed, 2 Jul 2025 20:40:53 +1000 Subject: [PATCH 10/10] fixing grammar --- prompts/csharp-docs.prompt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prompts/csharp-docs.prompt.md b/prompts/csharp-docs.prompt.md index 6f82916..39b672a 100644 --- a/prompts/csharp-docs.prompt.md +++ b/prompts/csharp-docs.prompt.md @@ -12,7 +12,7 @@ description: "Ensure that C# types are documented with XML comments and follow b - Use `` for method parameters. - Use `` for method return values. - Use `` for additional information, which can include implementation details, usage notes, or any other relevant context. -- Use `` for usage examples on how to use the the member. +- Use `` for usage examples on how to use the member. - Use `` to document exceptions thrown by methods. - Use `` and `` for references to other types or members. - Use `` to inherit documentation from base classes or interfaces.