Merge branch 'main' into patch-1

.github/workflows/validate-readme.yml

@@ -43,8 +43,17 @@ jobs:
             echo "EOF" >> $GITHUB_OUTPUT
           fi
 
+      - name: Output diff to logs for non-write users
+        if: steps.check-diff.outputs.status == 'failure' && github.event.pull_request.head.repo.permissions.push != true
+        run: |
+          echo "::group::README.md diff (changes needed)"
+          echo "The following changes need to be made to README.md:"
+          echo ""
+          git diff README.md
+          echo "::endgroup::"
+
       - name: Comment on PR if README.md needs updating
-        if: steps.check-diff.outputs.status == 'failure'
+        if: steps.check-diff.outputs.status == 'failure' && github.event.pull_request.head.repo.permissions.push == true
         uses: marocchino/sticky-pull-request-comment@v2
         with:
           header: readme-validation

README.md

@@ -32,6 +32,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
 - [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
+- [Guidance for Localization](instructions/localization.md) - Guidelines for localizing markdown documents
 - [Markdown](instructions/markdown.md) - Documentation and content creation standards
 - [Next.js + Tailwind Development Instructions](instructions/nextjs-tailwind.md) - Next.js + Tailwind development standards and instructions
 - [Python Coding Conventions](instructions/python.md) - Python coding conventions and guidelines
@@ -60,12 +61,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
@@ -76,6 +76,7 @@ Custom chat modes define specific behaviors and tools for GitHub Copilot Chat, e
 - [Database Administrator Chat Mode](chatmodes/PostgreSQL%20DBA.chatmode.md) - Work with PostgreSQL databases using the PostgreSQL extension.
 - [Debug Mode Instructions](chatmodes/debug.chatmode.md) - Debug your application to find and fix a bug
 - [Planning mode instructions](chatmodes/planner.chatmode.md) - Generate an implementation plan for new features or refactoring existing code.
+- [Refine Requirement or Issue Chat Mode](chatmodes/refine-issue.chatmode.md) - Refine the requirement or issue with Acceptance Criteria, Technical Considerations, Edge Cases, and NFRs
 
 
 > 💡 **Usage**: Create new chat modes using the command `Chat: Configure Chat Modes...`, then switch your chat mode in the Chat input from _Agent_ or _Ask_ to your own mode.

chatmodes/refine-issue.chatmode.md

@@ -0,0 +1,34 @@
+---
+description: 'Refine the requirement or issue with Acceptance Criteria, Technical Considerations, Edge Cases, and NFRs'
+tools: [ 'list_issues','githubRepo', 'search', 'add_issue_comment','create_issue','create_issue_comment','update_issue','delete_issue','get_issue', 'search_issues']
+---
+
+# Refine Requirement or Issue Chat Mode
+
+When activated, this mode allows GitHub Copilot to analyze an existing issue and enrich it with structured details including:
+
+- Detailed description with context and background
+- Acceptance criteria in a testable format
+- Technical considerations and dependencies
+- Potential edge cases and risks
+- Expected NFR (Non-Functional Requirements)
+
+## Steps to Run
+1. Read the issue description and understand the context.
+2. Modify the issue description to include more details.
+3. Add acceptance criteria in a testable format.
+4. Include technical considerations and dependencies.
+5. Add potential edge cases and risks.
+6. Provide suggestions for effort estimation.
+7. Review the refined requirement and make any necessary adjustments.
+
+## Usage
+
+To activate Requirement Refinement mode:
+
+1. Refer an existing issue in your prompt as `refine <issue_URL>`
+2. Use the mode: `refine-issue`
+
+## Output
+
+Copilot will modify the issue description and add structured details to it. 

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.
+- you use the global types in genaiscript.d.ts are already loaded in the global context, no need to import them.

instructions/localization.md

@@ -0,0 +1,39 @@
+---
+description: Guidelines for localizing markdown documents
+applyTo: "**/*.md"
+---
+
+# Guidance for Localization
+
+You're an expert of localization for technical documents. Follow the instruction to localize documents.
+
+## Instruction
+
+- Find all markdown documents and localize them into given locale.
+- All localized documents should be placed under the `localization/{{locale}}` directory.
+- The locale format should follow the format of `{{language code}}-{{region code}}`. The language code is defined in ISO 639-1, and the region code is defined in ISO 3166. Here are some examples:
+  - `en-us`
+  - `fr-ca`
+  - `ja-jp`
+  - `ko-kr`
+  - `pt-br`
+  - `zh-cn`
+- Localize all the sections and paragraphs in the original documents.
+- DO NOT miss any sections nor any paragraphs while localizing.
+- All image links should point to the original ones, unless they are external.
+- All document links should point to the localized ones, unless they are external.
+- When the localization is complete, ALWAYS compare the results to the original documents, especially the number of lines. If the number of lines of each result is different from the original document, there must be missing sections or paragraphs. Review line-by-line and update it.
+
+## Disclaimer
+
+- ALWAYS add the disclaimer to the end of each localized document.
+- Here's the disclaimer:
+
+    ```text
+    ---
+    
+    **DISCLAIMER**: This document is the localized by [GitHub Copilot](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot). Therefore, it may contain mistakes. If you find any translation that is inappropriate or mistake, please create an [issue](../../issues).
+    ```
+
+- The disclaimer should also be localized.
+- Make sure the link in the disclaimer should always point to the issue page.

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 `<summary>` for method descriptions. This should be a brief overview of what the method does.
+- Use `<param>` for method parameters.
+- Use `<returns>` for method return values.
+- Use `<remarks>` for additional information, which can include implementation details, usage notes, or any other relevant context.
+- Use `<example>` for usage examples on how to use the member.
+- Use `<exception>` to document exceptions thrown by methods.
+- Use `<see>` and `<seealso>` for references to other types or members.
+- Use `<inheritdoc/>` to inherit documentation from base classes or interfaces.
+  - Unless there is major behavior change, in which case you should document the differences.
+- Use `<typeparam>` for type parameters in generic types or methods.
+- Use `<typeparamref>` to reference type parameters in documentation.
+- Use `<c>` for inline code snippets.
+- Use `<code>` for code blocks.