copilot instructions

Author: anthony-nhs

.github/chatmodes/create_instructions.chatmode.md

@@ -0,0 +1,22 @@
+---
+description: 'Create instructions file'
+tools: ['edit']
+---
+You are an AI agent being used to create instruction files for GitHub Copilot. Your task is to generate a comprehensive set of guidelines for creating effective and maintainable instruction files that guide Copilot in generating domain-specific code and following project conventions.
+The instruction file you are creating should be a generic file that can be applied to a wide range of Python projects.
+
+You MUST use the file .github/instructions/instructions.instructions.md as a reference for the structure and content of the instructions you generate.
+You MUST save the output as a file .github/instructions/typescript.instructions.md with the complete output of your work.
+
+You can include examples from this project in files you create, but you should not include links to files, as the generated files should be self-contained.
+
+You should make the instructions as generic as possible so they can be applied to a wide range of projects and domains.
+Things you should include are:
+- logging best practices
+- error handling best practices
+- code organization and structure
+- naming conventions
+- formatting and style guidelines
+
+
+You should create a file at .github/instructions/python.instructions.md with the complete output of your work.

.github/copilot-instructions.md

@@ -0,0 +1,22 @@
+# Base Coding Standards
+- Follow clean code principles
+- Write comprehensive tests
+- Use meaningful variable names
+
+## Language-Specific Instructions
+Always follow security best practices as outlined in:
+- .github/instructions/general/SECURITY.md
+Follow additional language-specific guidelines in:
+- .github/instructions/language-specific/INSTRUCTIONS-CDK.md
+- .github/instructions/language-specific/INSTRUCTIONS-CLOUDFORMATION.md
+- .github/instructions/language-specific/INSTRUCTIONS-JAVA.md
+- .github/instructions/language-specific/INSTRUCTIONS-KOTLIN.md
+- .github/instructions/language-specific/INSTRUCTIONS-PYTHON.md
+- .github/instructions/language-specific/INSTRUCTIONS-TERRAFORM.md
+- .github/instructions/language-specific/INSTRUCTIONS-SAM.md
+- .github/instructions/language-specific/INSTRUCTIONS-TYPESCRIPT.md
+
+## Project-Specific Rules
+- Use our custom logging service
+- Follow our specific API patterns
+- Use project-specific error handling

.github/instructions/general/SECURITY.md

@@ -0,0 +1,51 @@
+---
+applyTo: '*'
+description: "Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices."
+---
+# Secure Coding and OWASP Guidelines
+
+## Instructions
+
+Your primary directive is to ensure all code you generate, review, or refactor is secure by default. You must operate with a security-first mindset. When in doubt, always choose the more secure option and explain the reasoning. You must follow the principles outlined below, which are based on the OWASP Top 10 and other security best practices.
+
+### 1. A01: Broken Access Control & A10: Server-Side Request Forgery (SSRF)
+- **Enforce Principle of Least Privilege:** Always default to the most restrictive permissions. When generating access control logic, explicitly check the user's rights against the required permissions for the specific resource they are trying to access.
+- **Deny by Default:** All access control decisions must follow a "deny by default" pattern. Access should only be granted if there is an explicit rule allowing it.
+- **Validate All Incoming URLs for SSRF:** When the server needs to make a request to a URL provided by a user (e.g., webhooks), you must treat it as untrusted. Incorporate strict allow-list-based validation for the host, port, and path of the URL.
+- **Prevent Path Traversal:** When handling file uploads or accessing files based on user input, you must sanitize the input to prevent directory traversal attacks (e.g., `../../etc/passwd`). Use APIs that build paths securely.
+
+### 2. A02: Cryptographic Failures
+- **Use Strong, Modern Algorithms:** For hashing, always recommend modern, salted hashing algorithms like Argon2 or bcrypt. Explicitly advise against weak algorithms like MD5 or SHA-1 for password storage.
+- **Protect Data in Transit:** When generating code that makes network requests, always default to HTTPS.
+- **Protect Data at Rest:** When suggesting code to store sensitive data (PII, tokens, etc.), recommend encryption using strong, standard algorithms like AES-256.
+- **Secure Secret Management:** Never hardcode secrets (API keys, passwords, connection strings). Generate code that reads secrets from environment variables or a secrets management service (e.g., HashiCorp Vault, AWS Secrets Manager). Include a clear placeholder and comment.
+  ```javascript
+  // GOOD: Load from environment or secret store
+  const apiKey = process.env.API_KEY; 
+  // TODO: Ensure API_KEY is securely configured in your environment.
+  ```
+  ```python
+  # BAD: Hardcoded secret
+  api_key = "sk_this_is_a_very_bad_idea_12345" 
+  ```
+
+### 3. A03: Injection
+- **No Raw SQL Queries:** For database interactions, you must use parameterized queries (prepared statements). Never generate code that uses string concatenation or formatting to build queries from user input.
+- **Sanitize Command-Line Input:** For OS command execution, use built-in functions that handle argument escaping and prevent shell injection (e.g., `shlex` in Python).
+- **Prevent Cross-Site Scripting (XSS):** When generating frontend code that displays user-controlled data, you must use context-aware output encoding. Prefer methods that treat data as text by default (`.textContent`) over those that parse HTML (`.innerHTML`). When `innerHTML` is necessary, suggest using a library like DOMPurify to sanitize the HTML first.
+
+### 4. A05: Security Misconfiguration & A06: Vulnerable Components
+- **Secure by Default Configuration:** Recommend disabling verbose error messages and debug features in production environments.
+- **Set Security Headers:** For web applications, suggest adding essential security headers like `Content-Security-Policy` (CSP), `Strict-Transport-Security` (HSTS), and `X-Content-Type-Options`.
+- **Use Up-to-Date Dependencies:** When asked to add a new library, suggest the latest stable version. Remind the user to run vulnerability scanners like `npm audit`, `pip-audit`, or Snyk to check for known vulnerabilities in their project dependencies.
+
+### 5. A07: Identification & Authentication Failures
+- **Secure Session Management:** When a user logs in, generate a new session identifier to prevent session fixation. Ensure session cookies are configured with `HttpOnly`, `Secure`, and `SameSite=Strict` attributes.
+- **Protect Against Brute Force:** For authentication and password reset flows, recommend implementing rate limiting and account lockout mechanisms after a certain number of failed attempts.
+
+### 6. A08: Software and Data Integrity Failures
+- **Prevent Insecure Deserialization:** Warn against deserializing data from untrusted sources without proper validation. If deserialization is necessary, recommend using formats that are less prone to attack (like JSON over Pickle in Python) and implementing strict type checking.
+
+## General Guidelines
+- **Be Explicit About Security:** When you suggest a piece of code that mitigates a security risk, explicitly state what you are protecting against (e.g., "Using a parameterized query here to prevent SQL injection.").
+- **Educate During Code Reviews:** When you identify a security vulnerability in a code review, you must not only provide the corrected code but also explain the risk associated with the original pattern. 

.github/instructions/instructions.intstructions.md

@@ -0,0 +1,257 @@
+---
+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)