ai-agents powershell.instructions.md

PowerShell Rules

These rules apply when you write or review PowerShell. Baseline is PowerShell 7+ (cross-platform pwsh), NOT Windows PowerShell 5.1. Write for Linux and macOS runners as well as Windows. Defer to PSScriptAnalyzer settings in the repo.

Structure

• Make every non-trivial function an advanced function: [CmdletBinding()] plus a param() block with typed, attributed parameters ([Parameter(Mandatory)], [ValidateNotNullOrEmpty()], [ValidateSet(...)]).
• Use approved verbs (Get-Verb) and Verb-Noun names. Get-, Set-, New-, Remove-, Test-. A function named DoStuff will not pass review.
• Emit objects to the pipeline; let the caller format. Do not Write-Host data. Use Write-Output (or bare output) for results, Write-Verbose/Write-Warning/ Write-Error for diagnostics, and Write-Host only for genuine console UX.
• Support the pipeline with process {} blocks and ValueFromPipeline when a function operates on a stream of inputs.

Cross-Platform

• Build paths with Join-Path or [IO.Path]::Combine, never string concatenation with \. Use [IO.Path]::DirectorySeparatorChar when you must.
• Use $env:TEMP via [IO.Path]::GetTempPath() and $HOME, not Windows-only paths. Do not assume C:\ or backslashes.
• Prefer [Environment]::NewLine awareness in tests; normalize line endings when comparing multi-line output across platforms.

Error Handling

• Set $ErrorActionPreference = 'Stop' at the top of scripts that must fail fast, or pass -ErrorAction Stop per call. Non-terminating errors are silent by default and hide failures.
• Wrap risky calls in try/catch/finally. Catch specific exception types where you can. Clean up in finally.
• After calling an external (native) executable, check $LASTEXITCODE explicitly and reset it. A non-zero $LASTEXITCODE left over from one command makes a later step or the whole workflow look failed.
• Standardize process exit codes per ADR-035: 0 success, 1 logic or validation error, 2 usage or configuration error, 3 external or dependency failure, 4 authentication or authorization failure (5-99 reserved, 100+ documented script-specific). exit with the matching code so callers and CI branch on the cause, not just pass or fail.