Add comprehensive guidelines for custom instruction files, localizati…

.github/copilot-instructions.md

@@ -22,16 +22,15 @@
 - Always validate input parameters
 - Implement proper authentication and authorization checks
 
-# PowerShell Commit Message Template
+# Commit Message Template
 
-Generate commit messages for PowerShell projects using this format:
+Generate commit messages using this format:
 
 `<emoji><type>[optional scope]: <description>`
 
-Follow the GitMoji specifications at <https://conventional-emoji-commits.site/full-specification/specification> for
-commit messages. Tailor commit messages for PowerShell development, using the provided types and scopes.
+Follow the GitMoji specifications at <https://conventional-emoji-commits.site/full-specification/specification> for commit messages. Tailor commit messages for PowerShell development, using the provided types and scopes.
 
-## PowerShell-Specific Types:
+## Types
 - feat: ✨ New cmdlet, function, or module feature
 - fix: 🐛 Bug fix in PowerShell code
 - docs: 📚 Help documentation, comment-based help
@@ -46,17 +45,17 @@ commit messages. Tailor commit messages for PowerShell development, using the pr
 - packaging: 📦 Packaging changes, module version updates
 - security: 🔒 Security-related changes, input validation, authentication
 
-## PowerShell Scopes:
+## Scopes
 - module: Module-level changes
 - cmdlet: Specific cmdlet modifications
 - function: Function updates
 - help: Documentation changes
 - manifest: Module manifest updates
 - tests: Test-related changes
 
-## Examples:
-✨feat(cmdlet): add Get-UserProfile with parameter validation  
-🐛fix(function): resolve Invoke-ApiCall error handling  
-📚docs(help): update comment-based help for Set-Configuration  
-🎨style(module): apply OTBS formatting and Pascal case  
-✅test(cmdlet): add Pester tests for Get-SystemInfo  
+## Examples
+✨ feat(cmdlet): add Get-UserProfile with parameter validation
+🐛 fix(function): resolve Invoke-ApiCall error handling
+📚 docs(help): update comment-based help for Set-Configuration
+🎨 style(module): apply OTBS formatting and Pascal case
+✅ test(cmdlet): add Pester tests for Get-SystemInfo

.github/instructions/codacy.instructions.md

@@ -10,7 +10,6 @@ Configuration for AI behavior when interacting with Codacy's MCP Server
 - ALWAYS use:
  - provider: gh
  - organization: SamErde
- - repository: PrivateAutomations
 - Avoid calling `git remote -v` unless really necessary
 
 ## CRITICAL: After ANY successful `edit_file` or `reapply` operation
@@ -28,7 +27,7 @@ Configuration for AI behavior when interacting with Codacy's MCP Server
 - Wait for the user to respond before proceeding with any other actions
 
 ## After every response
-- If you made any file edits in this conversation, verify you ran `codacy_cli_analyze` tool from Codacy's MCP Server 
+- If you made any file edits in this conversation, verify you ran `codacy_cli_analyze` tool from Codacy's MCP Server
 
 ## When there are no Codacy MCP Server tools available, or the MCP Server is not reachable
 - Suggest the user the following troubleshooting steps:
@@ -76,4 +75,4 @@ Configuration for AI behavior when interacting with Codacy's MCP Server
 - If the user accepts, run the `codacy_setup_repository` tool
 - Do not ever try to run the `codacy_setup_repository` tool on your own
 - After setup, immediately retry the action that failed (only retry once)
----
+---

.github/instructions/instructions.instructions.md

@@ -0,0 +1,256 @@
+---
+description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot'
+applyTo: '**/*.instructions.md'
+---
+
+# Custom Instructions File Guidelines
+
+Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.
+
+## Project Context
+
+- Target audience: Developers and GitHub Copilot working with domain-specific code
+- File format: Markdown with YAML frontmatter
+- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)
+- Location: `.github/instructions/` directory
+- Purpose: Provide context-aware guidance for code generation, review, and documentation
+
+## Required Frontmatter
+
+Every instruction file must include YAML frontmatter with the following fields:
+
+```yaml
+---
+description: 'Brief description of the instruction purpose and scope'
+applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
+---
+```
+
+### Frontmatter Guidelines
+
+- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose
+- **applyTo**: Glob pattern(s) specifying which files these instructions apply to
+  - Single pattern: `'**/*.ts'`
+  - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`
+  - Specific files: `'src/**/*.py'`
+  - All files: `'**'`
+
+## File Structure
+
+A well-structured instruction file should include the following sections:
+
+### 1. Title and Overview
+
+- Clear, descriptive title using `#` heading
+- Brief introduction explaining the purpose and scope
+- Optional: Project context section with key technologies and versions
+
+### 2. Core Sections
+
+Organize content into logical sections based on the domain:
+
+- **General Instructions**: High-level guidelines and principles
+- **Best Practices**: Recommended patterns and approaches
+- **Code Standards**: Naming conventions, formatting, style rules
+- **Architecture/Structure**: Project organization and design patterns
+- **Common Patterns**: Frequently used implementations
+- **Security**: Security considerations (if applicable)
+- **Performance**: Optimization guidelines (if applicable)
+- **Testing**: Testing standards and approaches (if applicable)
+
+### 3. Examples and Code Snippets
+
+Provide concrete examples with clear labels:
+
+```markdown
+### Good Example
+\`\`\`language
+// Recommended approach
+code example here
+\`\`\`
+
+### Bad Example
+\`\`\`language
+// Avoid this pattern
+code example here
+\`\`\`
+```
+
+### 4. Validation and Verification (Optional but Recommended)
+
+- Build commands to verify code
+- Linting and formatting tools
+- Testing requirements
+- Verification steps
+
+## Content Guidelines
+
+### Writing Style
+
+- Use clear, concise language
+- Write in imperative mood ("Use", "Implement", "Avoid")
+- Be specific and actionable
+- Avoid ambiguous terms like "should", "might", "possibly"
+- Use bullet points and lists for readability
+- Keep sections focused and scannable
+
+### Best Practices
+
+- **Be Specific**: Provide concrete examples rather than abstract concepts
+- **Show Why**: Explain the reasoning behind recommendations when it adds value
+- **Use Tables**: For comparing options, listing rules, or showing patterns
+- **Include Examples**: Real code snippets are more effective than descriptions
+- **Stay Current**: Reference current versions and best practices
+- **Link Resources**: Include official documentation and authoritative sources
+
+### Common Patterns to Include
+
+1. **Naming Conventions**: How to name variables, functions, classes, files
+2. **Code Organization**: File structure, module organization, import order
+3. **Error Handling**: Preferred error handling patterns
+4. **Dependencies**: How to manage and document dependencies
+5. **Comments and Documentation**: When and how to document code
+6. **Version Information**: Target language/framework versions
+
+## Patterns to Follow
+
+### Bullet Points and Lists
+
+```markdown
+## Security Best Practices
+
+- Always validate user input before processing
+- Use parameterized queries to prevent SQL injection
+- Store secrets in environment variables, never in code
+- Implement proper authentication and authorization
+- Enable HTTPS for all production endpoints
+```
+
+### Tables for Structured Information
+
+```markdown
+## Common Issues
+
+| Issue            | Solution            | Example                       |
+| ---------------- | ------------------- | ----------------------------- |
+| Magic numbers    | Use named constants | `const MAX_RETRIES = 3`       |
+| Deep nesting     | Extract functions   | Refactor nested if statements |
+| Hardcoded values | Use configuration   | Store API URLs in config      |
+```
+
+### Code Comparison
+
+```markdown
+### Good Example - Using TypeScript interfaces
+\`\`\`typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function getUser(id: string): User {
+  // Implementation
+}
+\`\`\`
+
+### Bad Example - Using any type
+\`\`\`typescript
+function getUser(id: any): any {
+  // Loses type safety
+}
+\`\`\`
+```
+
+### Conditional Guidance
+
+```markdown
+## Framework Selection
+
+- **For small projects**: Use Minimal API approach
+- **For large projects**: Use controller-based architecture with clear separation
+- **For microservices**: Consider domain-driven design patterns
+```
+
+## Patterns to Avoid
+
+- **Overly verbose explanations**: Keep it concise and scannable
+- **Outdated information**: Always reference current versions and practices
+- **Ambiguous guidelines**: Be specific about what to do or avoid
+- **Missing examples**: Abstract rules without concrete code examples
+- **Contradictory advice**: Ensure consistency throughout the file
+- **Copy-paste from documentation**: Add value by distilling and contextualizing
+
+## Testing Your Instructions
+
+Before finalizing instruction files:
+
+1. **Test with Copilot**: Try the instructions with actual prompts in VS Code
+2. **Verify Examples**: Ensure code examples are correct and run without errors
+3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files
+
+## Example Structure
+
+Here's a minimal example structure for a new instruction file:
+
+```markdown
+---
+description: 'Brief description of purpose'
+applyTo: '**/*.ext'
+---
+
+# Technology Name Development
+
+Brief introduction and context.
+
+## General Instructions
+
+- High-level guideline 1
+- High-level guideline 2
+
+## Best Practices
+
+- Specific practice 1
+- Specific practice 2
+
+## Code Standards
+
+### Naming Conventions
+- Rule 1
+- Rule 2
+
+### File Organization
+- Structure 1
+- Structure 2
+
+## Common Patterns
+
+### Pattern 1
+Description and example
+
+\`\`\`language
+code example
+\`\`\`
+
+### Pattern 2
+Description and example
+
+## Validation
+
+- Build command: `command to verify`
+- Linting: `command to lint`
+- Testing: `command to test`
+```
+
+## Maintenance
+
+- Review instructions when dependencies or frameworks are updated
+- Update examples to reflect current best practices
+- Remove outdated patterns or deprecated features
+- Add new patterns as they emerge in the community
+- Keep glob patterns accurate as project structure evolves
+
+## Additional Resources
+
+- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
+- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)

.github/instructions/localization.instructions.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.