Powershell engineering

PowerShell Engineering

Engineer PowerShell as an object-oriented automation language, not as Bash with different punctuation. Preserve the repository's target runtimes and style, then make compatibility, safety, and verification explicit.

Workflow

1. Inspect the repository before changing code. Find #Requires, manifests, module layout, test configuration, analyzer settings, CI matrices, and local instructions. Do not impose a new architecture on an established project.
2. Establish the target shell, PowerShell edition and version, operating systems, privilege level, and required modules. Run scripts/Get-PowerShellEnvironment.ps1 when the environment is unclear.
3. Load only the references needed for the task from the map below. For a multi-domain change, read every directly relevant reference before editing.
4. Implement with PowerShell-native semantics: objects through pipelines, typed parameters, explicit error behavior, argument arrays for native tools, structured output, and narrow privilege.
5. Validate at the same boundaries the code will cross. Parse every changed PowerShell file, run focused Pester tests, run PSScriptAnalyzer when the project uses it, and exercise each supported runtime/platform where feasible.
6. Report the target runtime, behavioral changes, tests run, and any unverified platform, module, privilege, or external-system assumptions.

Target Selection

• Follow an existing repository's declared runtime and compatibility matrix.
• For new general-purpose work, prefer a currently supported PowerShell 7 release and invoke it as pwsh.
• Treat Windows PowerShell 5.1 (powershell.exe, Desktop edition) as a separate legacy target. Do not claim PowerShell 7 replaces it; they install side by side and use different profiles and module paths.
• Keep portable code within the oldest supported runtime's syntax. Do not emit ternary operators, null-coalescing operators, pipeline-chain operators, ForEach-Object -Parallel, or PS7-only automatic variables for a 5.1 target.
• Use a Windows-only implementation only when the task depends on Windows APIs, modules, providers, COM, WPF, or Windows Forms. State that boundary.

Correctness Rules

• Resolve command identity before assuming semantics: use Get-Command -All, Get-Help, and Get-Member. Verify third-party cmdlets and module versions from installed metadata or current official documentation; never invent them.
• Prefer full cmdlet and parameter names in durable code. Use approved Verb-Noun names, [CmdletBinding()], typed parameters, validation attributes, and comment-based help for reusable commands.
• Return objects from reusable functions. Keep Format-* at the presentation boundary. Use verbose, information, warning, and error streams for messages; do not use Write-Host as a data channel.
• Remember that try/catch catches terminating errors. Add -ErrorAction Stop or a deliberately scoped error preference when a non-terminating cmdlet error must enter catch.
• Invoke native executables with the call operator and argument arrays when quoting is nontrivial. Inspect $LASTEXITCODE; do not infer native success solely from whether PowerShell threw.
• Build objects before serializing JSON. Set ConvertTo-Json -Depth deliberately, use Get-Content -Raw for whole JSON documents, and specify encoding at interoperability boundaries.
• Use Join-Path, Resolve-Path, and -LiteralPath according to intent. Resolve and display destructive targets before mutation. Use SupportsShouldProcess, ShouldProcess, -WhatIf, and -Confirm where appropriate.
• Never hardcode credentials, tokens, or private keys. Never log secret values. Prefer managed/workload identity or established secret stores over plaintext files and environment variables when the platform supports them.
• Do not weaken execution policy globally to run one script. Do not present execution policy as a security boundary. Do not default to irm ... | iex.
• Preserve Unicode when the data requires it. PowerShell source is not ASCII-only. Choose encodings based on the target runtime and consumer.
• Use parentheses where PowerShell grammar requires an expression; do not wrap every command mechanically. Complex subexpressions such as $($item.Name) are valid. A return inside try is valid, though finally still runs.
• Measure before optimizing. Pipelines improve composition; foreach language loops are often faster. Avoid repeated array += in large loops.

Reference Map

• Runtime selection, shell detection, profiles, encoding, and 5.1/7.x differences: read compatibility-and-environment.md.
• Functions, parameters, pipelines, object output, collections, style, and reusable API design: read language-and-api-design.md.
• Native tools, quoting, argument passing, paths, files, JSON, REST, CSV, XML, and Bash translation: read native-commands-and-data.md.
• Terminating errors, output streams, logging, cleanup, retries, and process exit behavior: read errors-output-and-observability.md.
• Modules, manifests, dependency management, PSResourceGet, Gallery publishing, cloud modules, and DSC: read modules-packaging-and-dependencies.md.
• AST parsing, PSScriptAnalyzer, Pester, mocking, coverage, CI matrices, and release gates: read testing-analysis-and-ci.md.
• Input trust, secrets, execution policy, signing, downloads, least privilege, destructive actions, WinRM, SSH remoting, and JEA: read security-remoting-and-automation.md.
• Profiling, allocation, pipeline costs, jobs, thread jobs, parallel pipelines, runspaces, and throttling: read performance-and-concurrency.md.
• Registry, services, scheduled tasks, event logs, CIM, COM, WPF, Windows Forms, STA requirements, and elevation: read windows-integration-and-gui.md.
• Primary official documentation and community survey inputs: read source-map.md when claims need current verification or sources need updating.

Bundled Commands

Inspect the current shell without profiles or secret values:

& "$skillRoot/scripts/Get-PowerShellEnvironment.ps1" -OutputFormat Json

Validate a project after edits:

$result = & "$skillRoot/scripts/Test-PowerShellProject.ps1" -Path . -RunPester
$result
if (-not $result.Succeeded) { throw 'PowerShell validation failed.' }

Resolve $skillRoot to this skill directory. The validator always performs AST syntax parsing. It runs PSScriptAnalyzer when available unless skipped, and runs Pester only when requested. Missing optional tooling is reported, not hidden.

Review Gate

Before finishing, check all applicable items:

• The declared runtime and operating systems match the syntax and cmdlets used.
• Pipeline binding, empty input, $null, scalar-versus-array behavior, and paths containing spaces or wildcard characters are covered.
• Failures are observable and do not silently produce partial success.
• Native exit codes, stdout, and stderr are handled intentionally.
• Destructive commands honor ShouldProcess or have an equivalent dry run.
• Secrets stay out of source, command history, logs, errors, and test fixtures.
• Functions emit stable objects and avoid presentation formatting.
• Tests cover success, invalid input, external failures, and cleanup.
• Changed files parse cleanly; focused tests and analysis have been run.
• Any unavailable runtime, platform, module, service, or credential is named in the handoff instead of being implied as verified.