Skip to content

Commit 2756e5f

Browse files
authored
chore: move the standards sync to the 2.0 installer (#57)
The sync workflow copied folders from ai-powershell-standards with rm -rf and cp. That copy installs neither the skills nor the Codex files, and it kept the pre-2.0 examples folder and the prompt stubs that version 2.0 only ships for old workflows. The workflow is now the current template from the standards repository. It runs Tools/Install-CopilotStandards.ps1 with -RemoveLegacyFiles, pins its actions to commit IDs, and opens its pull request from chore/sync-powershell-standards. This commit applies that installation once: - Adds AGENTS.md, which points agents to the core rules. - Adds the eight powershell-* skills for GitHub Copilot, Claude Code and Codex. - Removes the copied powershell-standards/ examples, .github/prompts/ and .claude/commands/powershell-standards/. - Updates CLAUDE.md and CONTRIBUTING.md, which described the old mirror.
1 parent 478118f commit 2756e5f

46 files changed

Lines changed: 967 additions & 1510 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: powershell-ci-pipeline
3+
description: Add or fix a CI workflow for a PowerShell project that runs PSScriptAnalyzer and Pester with a coverage gate. Use when asked to set up, create, or repair CI, GitHub Actions, or quality gates for PowerShell code.
4+
---
5+
6+
# Set up CI for a PowerShell project
7+
8+
Read `.github/instructions/powershell-cicd.instructions.md` first, unless it is already loaded. It
9+
holds the rules, a pull request workflow, and a publishing workflow.
10+
11+
## Steps
12+
13+
1. Look at what exists: workflow files, a build script, the test folder, and the module manifest.
14+
Extend an existing workflow instead of adding a second one that does the same job.
15+
2. Establish what the project supports from its manifest and `#requires` lines: PowerShell 7.6 only,
16+
or also Windows PowerShell 5.1, and which operating systems. Build the job list from that. Do not
17+
add a version or operating system the project does not claim to support.
18+
3. Add the pull request workflow from the CI rules: install PSScriptAnalyzer and Pester at fixed
19+
versions, run PSScriptAnalyzer and fail on findings, and run the test gate.
20+
4. Put the test gate in a script in the repository, `Tests/Invoke-Tests.ps1` unless the project
21+
keeps its build scripts elsewhere, so that developers can run the same check locally. Use the
22+
runner in `.github/instructions/pester-supporting-docs/test-execution.md`, and pass
23+
`-CodeCoverage` in the job that holds the coverage gate; the alternative is the minimal gate in
24+
`.github/instructions/powershell-pester.instructions.md`, which takes no parameters. Set its test
25+
path and coverage paths to the project's real folders.
26+
5. If the repository has no `PSScriptAnalyzerSettings.psd1`, offer to add the one shown in the CI
27+
rules. Adding it can surface many layout findings in existing code, so say that first.
28+
6. If the repository has no `.gitattributes` file, add one that contains `* text=auto eol=lf`
29+
(CIC-11), so that the tests see the same line endings on every runner.
30+
7. If the module ships compiled help, add the help checks from
31+
`.github/instructions/powershell-platyps.instructions.md`.
32+
8. Validate the workflow file's syntax, and run the gate script locally if you can.
33+
34+
## Report
35+
36+
Say which files you added or changed, what each job runs, and what you were able to run locally. A
37+
workflow is not verified until it has run on the CI system; say so, and do not claim that it passes.
38+
Do not add publishing, signing, or deployment steps unless the user asked for them.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: powershell-module-help
3+
description: Generate, update, validate, or build PowerShell module help with Microsoft.PowerShell.PlatyPS, where help is written as Markdown and shipped as compiled external help. Use when asked to document a module's commands, update help after a parameter change, or fix Get-Help output for a module.
4+
---
5+
6+
# Maintain module help with PlatyPS
7+
8+
Read `.github/instructions/powershell-platyps.instructions.md` first, unless it is already loaded. It
9+
holds the rules and every command used below.
10+
11+
## Steps
12+
13+
1. Confirm the tool. `Get-Module -ListAvailable Microsoft.PowerShell.PlatyPS` must show version 1.0.3
14+
or later. Do not use the retired `platyPS` module or its commands.
15+
2. Find the state of the module's help: whether `docs/<ModuleName>/` exists, which exported commands
16+
have a Markdown file, and whether the exported functions carry `.EXTERNALHELP`.
17+
3. For a command with no Markdown yet: make sure the function has complete comment-based help, run
18+
`New-MarkdownCommandHelp` with `-Locale`, and only then add `.EXTERNALHELP` and reduce the comment
19+
block to a one-line `.SYNOPSIS`. The order matters.
20+
4. For a command whose parameters changed: import the module and run `Update-MarkdownCommandHelp`,
21+
then update the module page. Do not edit syntax blocks or parameter metadata by hand.
22+
5. Write the content. Replace every `{{ Fill in ... }}` placeholder, put each example's command in a
23+
fenced `powershell` block, and describe only what the command does.
24+
6. Validate with the checks in the PlatyPS rules: structure, leftover placeholders, and relative
25+
links.
26+
7. Build the compiled help with `Export-MamlCommandHelp`, copy it into the module's culture folder,
27+
and confirm with `Get-Help <Command> -Full` against the imported module that the text and the
28+
examples appear. Before a release, repeat the check against the packaged module on a
29+
case-sensitive file system (PLT-14).
30+
31+
## Report
32+
33+
List the Markdown files you created or changed, the result of each validation, and what `Get-Help`
34+
showed. Mention any command whose description or examples you could not write from the code alone,
35+
and ask the user for the missing facts instead of inventing them.
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: powershell-new-function
3+
description: Write a new PowerShell function with its comment-based help and Pester tests, following this repository's PowerShell standards. Use when asked to create, add, or scaffold a PowerShell function or command.
4+
---
5+
6+
# Write a new PowerShell function
7+
8+
Read these before writing code, unless they are already loaded:
9+
10+
- `.github/copilot-instructions.md`, or `AGENTS.md` if the repository has no such file (the core rules
11+
and the function template)
12+
- `.github/instructions/powershell-functions.instructions.md`
13+
- `.github/instructions/powershell-error-handling.instructions.md`
14+
- `.github/instructions/powershell-help.instructions.md`
15+
16+
## Steps
17+
18+
1. Find the target version. Read the `#requires -Version` lines and the nearest module manifest. If the
19+
project declares nothing and it is not clear which target applies, ask. If you cannot ask, target
20+
PowerShell 7.6 and say that you assumed it.
21+
2. Choose the name. Use a verb that `Get-Verb` lists and a singular noun. Search the repository for an
22+
existing function with that name or purpose before creating a new one.
23+
3. Decide where the file goes. In a module, an exported function goes in `Public/<Name>.ps1` and its
24+
name is added to `FunctionsToExport` in the manifest; an internal one goes in `Private/<Name>.ps1`.
25+
Outside a module, put it where the user asked.
26+
4. Write the function in the shape of the function template: help first, `[CmdletBinding()]`,
27+
`[OutputType()]`, typed and validated parameters, a `process` block for pipeline input, `try` and
28+
`$PSCmdlet.ThrowTerminatingError()` for a failure that ends the function,
29+
`$PSCmdlet.WriteError()` for a failure of one item, and objects written to the pipeline as they are
30+
produced.
31+
5. If the function changes state, add `SupportsShouldProcess` and guard each change with
32+
`$PSCmdlet.ShouldProcess()`. If it only reads, do not.
33+
6. Write the tests following `.github/instructions/powershell-pester.instructions.md`, in
34+
`Tests/Unit/<Name>.Tests.ps1` (MOD-01) or beside the tests the project already has. Cover each
35+
parameter set, the documented output, each validation failure, and each error path.
36+
7. Run PSScriptAnalyzer on the new files, with `-Settings ./PSScriptAnalyzerSettings.psd1` when that
37+
file exists, and run the tests. Fix what they report.
38+
39+
## Report
40+
41+
Say which files you created or changed, which PowerShell version you targeted and why, what you ran
42+
and what it reported, and anything you could not verify. Ask instead of guessing when the purpose, the
43+
inputs, or the output of the function is unclear.
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: powershell-new-module
3+
description: Create a new PowerShell module with a manifest, a root module, Public and Private folders, a first function, and Pester tests, following this repository's PowerShell standards. Use when asked to create, scaffold, or start a PowerShell module.
4+
---
5+
6+
# Create a new PowerShell module
7+
8+
Read these before writing files, unless they are already loaded:
9+
10+
- `.github/copilot-instructions.md`, or `AGENTS.md` if the repository has no such file (the core rules
11+
and the function template)
12+
- `.github/instructions/powershell-modules.instructions.md`
13+
- `.github/instructions/powershell-version.instructions.md`
14+
15+
## Steps
16+
17+
1. Ask for, or confirm, the module name, what it is for, and whether it must run on Windows PowerShell
18+
5.1. Without a 5.1 requirement, target PowerShell 7.6.
19+
2. Create the layout from the module rules: `ModuleName.psd1`, `ModuleName.psm1`, `Public/`,
20+
`Private/`, and `Tests/`, with the unit tests under `Tests/Unit/` (MOD-01). Add
21+
`Tests/Integration/` and `Tests/Performance/` when the module has such tests, and `Classes/` only
22+
if the module defines a class. Do not create empty folders for things the module does not have.
23+
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
24+
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
25+
by name. Take `Author` and the project links from the user or the repository; leave out what you do
26+
not know.
27+
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
28+
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
29+
`Public` dot-sourced in that order, failing the import if a file fails to load.
30+
5. Add the first function with the `powershell-new-function` skill, or follow its steps.
31+
6. Import the module in a new session with `Import-Module ./ModuleName.psd1 -Force`, confirm that
32+
`Get-Command -Module ModuleName` lists exactly the exported functions, and run the tests.
33+
7. Add a `README.md` that follows `.github/instructions/powershell-readme.instructions.md`.
34+
35+
## Report
36+
37+
List the files you created, the target version, and the results of the import check and the tests. Do
38+
not add dependencies or CI workflows unless the user asked for them; mention them as possible next
39+
steps instead. Every module generates its command help with PlatyPS (PLT-10): do that with the
40+
`powershell-module-help` skill, or say that it is still to do.
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: powershell-performance-review
3+
description: Find and fix performance problems in PowerShell code by measuring it. Use when asked to optimize, speed up, profile, or analyze the performance of PowerShell code.
4+
---
5+
6+
# Performance review of PowerShell code
7+
8+
The collection and string rules are in `.github/instructions/powershell-style.instructions.md`
9+
(STY-22, STY-40 to STY-45, and STY-50). Read them first, unless that file is already loaded.
10+
11+
## Steps
12+
13+
1. Ask what is slow and how large the real input is, if the user has not said. An improvement that
14+
matters at 100,000 items can be noise at 100.
15+
2. Measure before changing anything. Use `Measure-Command` around the code with realistic input, and
16+
repeat the run several times. If you cannot run the code, say so and present your suggestions as
17+
unmeasured.
18+
3. Look for the causes that usually dominate:
19+
- An array grown with `+=` inside a loop, or a string extended with `+=` about 100 times or
20+
more. Below that, `+=` on a string is fine (STY-22); do not report it.
21+
- A command called once for each item when it accepts all items at once, or a remote or disk call
22+
inside a loop that could be made once outside it.
23+
- Filtering with `Where-Object` what the source command could have filtered.
24+
- A lookup that scans a collection inside a loop, where a hashtable built once would do.
25+
- `ForEach-Object` over a large collection that is already in memory.
26+
- Output piped to `Out-Null` in a tight loop.
27+
4. Change one thing at a time and measure again with the same input. Keep a change only if it is
28+
faster and the output is the same.
29+
5. Do not trade correctness or clarity for a small gain, and do not add parallelism
30+
(`ForEach-Object -Parallel`, thread jobs) unless the work is slow per item and the items are
31+
independent.
32+
33+
## Report
34+
35+
Give the measurements before and after, with the input size and the PowerShell version, for each
36+
change you kept. Performance figures MUST come from runs you made; do not estimate percentages. List
37+
what you tried that did not help.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: powershell-review
3+
description: Review PowerShell code against this repository's PowerShell standards and report findings by rule ID. Use when asked to review, validate, analyze, or check PowerShell code for quality or standards compliance.
4+
---
5+
6+
# Review PowerShell code against the standards
7+
8+
Read the core rules (`.github/copilot-instructions.md`, or `AGENTS.md` if the repository has no such
9+
file) and the topic files they list for the kind of file under review, unless they are already
10+
loaded. Every rule has an ID such as `ERR-10`; cite it.
11+
12+
## Steps
13+
14+
1. Establish the target version from `#requires` lines and the module manifest. Judge the code
15+
against that version, not against the newest one.
16+
2. Run the tools first when you can: PSScriptAnalyzer, with `-Settings ./PSScriptAnalyzerSettings.psd1`
17+
when that file exists, and the existing tests. Include what they report.
18+
3. Read the code for what tools cannot see, in this order:
19+
1. Correctness: logic errors, unhandled failure paths, wrong assumptions about a command's output.
20+
2. Error handling: the ERR rules, in particular `throw` in advanced functions, a missing
21+
`-ErrorAction Stop` inside `try`, and empty or silent `catch` blocks.
22+
3. Security: the SEC rules.
23+
4. Functions and output: the FUN rules.
24+
5. Version fit: the VER rules.
25+
6. Help and style: the DOC and STY rules.
26+
4. Confirm each finding before reporting it. Read the surrounding code, and where behaviour is in
27+
doubt, run a small test. Do not report a rule violation in code that the change did not touch,
28+
unless it is a defect.
29+
30+
## Report
31+
32+
List findings with the most serious first. For each one give the file and line, the rule ID or the
33+
word "defect", what is wrong, and the corrected code. Separate requirements (MUST) from
34+
recommendations (SHOULD). State what you ran and what you did not check. If nothing is wrong, say so;
35+
do not invent findings.
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: powershell-security-review
3+
description: Review PowerShell code for security problems such as exposed secrets, unsafe credential handling, command or path injection, and disabled certificate checks. Use when asked for a security review or audit of PowerShell code.
4+
---
5+
6+
# Security review of PowerShell code
7+
8+
Read `.github/instructions/powershell-security.instructions.md` first, unless it is already loaded.
9+
10+
## Steps
11+
12+
1. Map where data enters the code: parameters, files, environment variables, web responses, and
13+
pipeline input. Treat each as untrusted unless the code proves otherwise.
14+
2. Follow each input to where it is used and check:
15+
- Secrets and credentials: SEC-01 to SEC-08, and SEC-50 to SEC-53 where the code uses a secret
16+
vault. Search for literals that look like passwords, tokens, keys, and connection strings,
17+
including in comments, defaults, and test data.
18+
- Command construction: SEC-10. Look for `Invoke-Expression`, `[scriptblock]::Create()`,
19+
`Start-Process` with a built argument string, and strings passed to `cmd /c` or `pwsh -Command`.
20+
- Paths: SEC-12. Look for input joined into a path that is then read, written, or deleted.
21+
- Queries: SEC-13.
22+
- Input checks: SEC-11 and SEC-16 to SEC-19.
23+
- Code signing, where the code signs files: SEC-30 to SEC-35.
24+
- Transport and privilege: SEC-14 and SEC-15.
25+
3. Check what the code writes. Verbose, debug, warning, and error messages, log files, and exported
26+
files must not contain secrets or personal data.
27+
4. Run PSScriptAnalyzer. Its rules `PSAvoidUsingPlainTextForPassword`,
28+
`PSAvoidUsingConvertToSecureStringWithPlainText`, `PSAvoidUsingUsernameAndPasswordParams`, and
29+
`PSAvoidUsingInvokeExpression` cover part of this.
30+
5. Confirm each finding by reading the full path from input to use. A pattern match alone is not a
31+
finding. The patterns of SEC-40 find candidates. `Add-Type -TypeDefinition` is a Medium finding
32+
(SEC-41).
33+
34+
## Report
35+
36+
List findings with the most serious first, each with its tier (Critical, High, Medium, or Low), and
37+
state the overall risk as the highest tier found (SEC-42): file and line, rule ID, how the problem
38+
could be exploited or exposed, and the corrected code. Say which inputs you traced and which you did
39+
not. If you find a real secret, tell the user that it must be revoked and replaced; removing it from
40+
the file does not remove it from the repository history. This review covers the code only. It is not
41+
a compliance assessment, so do not state that the code meets any regulation or framework.
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: powershell-write-tests
3+
description: Write or extend Pester 6 tests for existing PowerShell code, following this repository's testing rules. Use when asked to add tests, raise coverage, or test a PowerShell function, script, or module.
4+
---
5+
6+
# Write Pester tests for PowerShell code
7+
8+
Read `.github/instructions/powershell-pester.instructions.md` first, unless it is already loaded. It
9+
holds the rules, a complete test file, and a table of assertion behaviour.
10+
11+
## Steps
12+
13+
1. Read the code under test completely: its parameters and parameter sets, validation attributes,
14+
output type, every `catch`, and every call that leaves the process (network, files, other modules,
15+
the clock).
16+
2. Look at an existing test file in the repository. Keep its assertion style and layout. In a new
17+
file use the Pester 6 `Should-*` assertions.
18+
3. List the behaviours to test before writing any: each parameter set, the documented output, each
19+
validation failure, each error path, pipeline input, and for a `Test-` function both outcomes.
20+
4. Write the file so that it runs on its own: a versioned `#Requires` for Pester, the code loaded in a
21+
top-level `BeforeAll`, and test data built in `BeforeDiscovery`.
22+
5. Mock only what crosses a boundary. For code inside a module, pass `-ModuleName` to `Mock` and
23+
`Should-Invoke`, and reach private functions with `InModuleScope`.
24+
6. Make every test able to fail: assert specific values, assert the count before reading by index, and
25+
assert expected errors with `Should-Throw` or by counting error records.
26+
7. Run the tests. A test that passes on its first run has not been shown to work: break the behaviour
27+
it covers, or the expected value, once to see it fail, then restore it.
28+
29+
## Report
30+
31+
Say which behaviours are covered and which are not, the pass and fail counts, and the coverage figure
32+
if you measured it. If a test exposes a defect in the code, report the defect; do not weaken the test
33+
to make it pass, and do not change the code under test unless the user asked for that.

‎.claude/commands/powershell-standards/.keep‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

0 commit comments

Comments
 (0)