Add .github/copilot-instructions.md for AI agent guidance#58
Open
cocallaw wants to merge 3 commits into
Open
Conversation
Provide project-specific instructions covering module layout, PowerShell 5.1/7+ compatibility requirements, coding conventions, security practices, testing with Pester v5, CI/CD expectations, and guidance for adding new functions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a repository-level Copilot instruction file to steer AI agents toward AzRetirementMonitor’s established module structure, PowerShell 5.1 compatibility constraints, security expectations, and CI/testing workflow.
Changes:
- Introduces
.github/copilot-instructions.mddocumenting module layout (Public/Private/Tests) and export rules. - Documents PowerShell 5.1 + 7+ compatibility guidance (including 7+-only syntax to avoid).
- Captures repo-specific guidance for error handling, security (CSV injection/XSS/nextLink validation), testing (Pester v5), and CI expectations.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+58
to
+59
| - Validate URLs with scheme checks (`https://` only) before rendering links. | ||
| - Validate pagination `nextLink` URIs against an allowlist of trusted hosts. |
Clarify that HTML link rendering accepts both http:// and https:// (to block protocol injection like javascript:), while pagination nextLink validation is strictly https-only against a trusted host allowlist. Addresses PR review feedback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
| - Tests use **Pester v5** with `BeforeAll` module imports. | ||
| - Test file: `Tests/AzRetirementMonitor.Tests.ps1` | ||
| - Mock all Azure API/module calls — tests must work without a live Azure connection. | ||
| - Use `InModuleScope AzRetirementMonitor { }` when testing private/internal functions. |
| - **Dual retrieval modes**: Default uses Az.Advisor module; `-UseAPI` switch enables direct REST calls. Both return identical `[PSCustomObject]` output shapes. | ||
| - **`SupportsShouldProcess`**: Used on destructive or file-writing operations (e.g., `Export-AzRetirementReport`). | ||
| - **Pipeline support**: `Get-AzRetirementRecommendation` output pipes directly into `Export-AzRetirementReport`. | ||
| - **No external dependencies at runtime** beyond Az.Advisor/Az.Accounts (for default mode) or Azure CLI (for API mode). |
- Replace InModuleScope guidance with the actual pattern used in the repo:
& (Get-Module AzRetirementMonitor) { ... }
- Clarify that API mode supports both Azure CLI and Az.Accounts for auth
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a
.github/copilot-instructions.mdfile so that GitHub Copilot (and other AI coding agents) understand the project's conventions, compatibility constraints, and architecture when assisting with this repo.Without project-specific instructions, AI agents default to generic PowerShell patterns that may introduce 7+-only syntax, miss the Public/Private module structure, or overlook security practices like CSV formula injection prevention.
Related Issue
N/A
Type of Change
Changes Made
.github/copilot-instructions.mdcovering:Testing
N/A -- documentation-only change that does not affect runtime behavior.
Test Environment
Test Commands
# No runtime testing needed for documentation fileTest Results
Checklist
Additional Notes
This file is automatically loaded by VS Code Copilot for all workspace interactions. It helps AI agents produce code that is compatible with both PowerShell Desktop 5.1 and Core 7+, follows the module's established patterns, and respects the security constraints documented in the codebase.