chore: Sync AI agent instructions to AIM 0.12.1

[tablackburn]

Syncs the AI agent instructions from AIM 0.8.14 (2026-05-16) to 0.12.0 (2026-08-19), following
instructions/update.instructions.md with per-file confirmation.

Documentation only. No code, no build changes.

What actually changed

Every file reported as differing at first, with suspiciously symmetric line counts — that was
CRLF against LF, not content. Ignoring line endings, three files differ:

File	Change
powershell.instructions.md	+351 lines — a new Pester section
update.instructions.md	+54 — skill-dependency vendoring, procedure renumbered
git-workflow.instructions.md	+6 — ticket-identifier examples lowercased

The other eight are byte-identical to upstream. repository-specific.instructions.md is never
copied from upstream and was left alone.

Why the Pester section is worth having

It carries six findings measured during a Pester 5 → 6 migration, and three of them describe
traps this repository has already hit or can still hit:

• -Skip: is evaluated during discovery, so an expression reading a BeforeAll variable
  sees $null and skips unconditionally — and a skipped test reads as a passing build. This bit
  me earlier today writing test: Baseline the help building functions #170's predecessor; I diagnosed and fixed it by hand, and the rule was
  already written down upstream.
• $_ is not bound by an It-level -ForEach when the skip condition is evaluated, so
  every generated case skips. The fix is to move -ForEach to an enclosing Context.
• Gating a build on Invoke-Pester results needs FailedBlocksCount and
  FailedContainersCount, not FailedCount alone — which is exactly the gap Also fail on Pester block/container failures (not just failed tests) #128/fix: Fail the build when a Pester run fails for any reason #133 closed in
  Test-PSBuildPester, now written down as a general rule.

One rule this repository currently violates

The new section says:

Never pin Pester itself to an exact version in a dependency manifest [...] use
Version = 'latest'. Pester 6 runs discovery for each test file separately, and resolving
Describe triggers PowerShell module autoloading. Autoloading always selects the highest
installed version, overriding whatever version was explicitly imported beforehand.

requirements.psd1 pins Pester = '6.0.0', and requirements.pester-matrix.psd1 pins 5.9.0
deliberately for the Test-PSBuildPester compatibility matrix. Whether that pin is honored or
silently overridden on a runner with a newer Pester is worth checking — but it is a behavioral
question about this repository's test suite, not part of a documentation sync, so it is not
addressed here. Filing separately.

Not done

• aim.config.json is unchanged. The module list is the same, and no skills block is
  declared, so step 7's new skill-vendoring flow is inert. Worth a later look: the upstream
  example vendors psake/psake-llm-tools, which is this org's own skill.
• No external instruction module added. update.instructions.md §6 checks external sources
  only when guidance is not found in AIM. Pester guidance now lives in AIM's
  powershell.instructions.md, so pulling awesome-copilot's powershell-pester-6.instructions.md
  alongside it would create two overlapping sources that can drift.

Mechanics

Files were written with CRLF to match the repository, so the diff shows content rather than
every line. The upstream clone was removed after syncing, per step 10.

---

Retargeted at 0.12.1 (2026-08-24)

Now syncs AIM 0.12.1, not 0.12.0. The branch name still says 0.12.0; only the name.

Copilot's three findings on this pull request were all correct, and all about upstream text
rather than anything this sync could fix locally — editing them here would have created drift
that the next sync silently reverts. They were fixed upstream in
tablackburn/ai-agent-instruction-modules#41
and released as v0.12.1.

Retargeting rather than merging-then-following-up, because 0.12.1 contains only fixes to the
same Pester section this pull request introduces. Merging 0.12.0 would have landed known-wrong
text and required a second pull request to correct it.

What changed since the 0.12.0 revision:

instructions/powershell.instructions.md	re-synced from v0.12.1
AGENTS.md	Template Version: 0.12.0 → 0.12.1

Nothing else moved between the two releases, and Last sync was already today's date.

The 0.12.1 delta, all inside text this pull request adds:

• InModuleScope no longer contradicts itself. It said a wrapping InModuleScope "forces the
  module to load during discovery" and then, eleven lines later, that it "requires the module to
  be loaded already". It now describes the actual chain: a top-level InModuleScope is file-scope
  code so it runs at discovery, and because it needs an already-loaded module the Import-Module
  satisfying it sits at file scope too — that import is what accumulates.
• Pester pinning is scoped to the version the suite itself runs on, with install-only
  compatibility matrices documented as the exception. As written before, it condemned this
  repository's own requirements.pester-matrix.psd1, and an agent following it would have deleted
  that pin and quietly reduced the matrix to one major.
• A contraction used where the possessive was meant.

Suite: 453 passed, 0 failed.

Still not addressed here, deliberately

requirements.psd1 pins Pester = '6.0.0' while the suite actually runs on 6.1.0 — the pin is
not honored. That is a real problem in this repository, but it is a behavioral question about the
test suite rather than part of a documentation sync. Filed separately as #172.

[github-actions]

Test Results

    4 files  +  1    720 suites  +180   4m 55s ⏱️ + 2m 28s
  454 tests ±  0    452 ✅ ±  0   2 💤 ± 0  0 ❌ ±0 
1 820 runs  +455  1 773 ✅ +440  47 💤 +15  0 ❌ ±0 

Results for commit df17584. ± Comparison against base commit 58f8a54.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

Documentation-only sync of AI agent instructions from AIM 0.8.14 to 0.12.0.

Changes:

• Adds Pester 6 guidance and PowerShell updates.
• Documents skill-dependency vendoring.
• Updates Git examples and AIM metadata.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Review summary
instructions/update.instructions.md	Adds skill-dependency synchronization procedures.
instructions/powershell.instructions.md	Adds Pester guidance. One moderate issue (2 votes) and two nits (2 votes each) remain.
instructions/git-workflow.instructions.md	Updates ticket-identifier examples to lowercase.
AGENTS.md	Updates AIM metadata and skill guidance.

Suppressed comments (8)

AGENTS.md:82

• This repeats the configurable-vendorPath problem in AGENTS.md: a repository using a non-default path is still told that native clients discover the skill directly, even though those clients scan .agents/skills/. Keep this statement conditional on the default path or document how custom paths are discovered.

natively scan `.agents/skills/` also pick it up directly. Because Claude Code reads `CLAUDE.md`

instructions/powershell.instructions.md:809

• This absolute rule conflicts with the repository's checked-in compatibility fixture: tests/TestModule/Tests/a_InModuleScope.tests.ps1:1 wraps Describe in InModuleScope, and tests/TestModule/psakeFile.ps1:23-24 explicitly enables module import so that pattern works. Because this documentation sync leaves that test unchanged, agents following the new rule will immediately treat a current repository test as invalid. Please either migrate the fixture with this change or qualify the rule to suites where discovery-time imports can conflict.

Put `InModuleScope` inside the `Context` or `It` that needs it; never wrap it around `Describe`
or `It`. Pester's own documentation advises against that enclosing placement, because a
wrapping `InModuleScope` forces the module to load during discovery rather than execution.
Combined with Pester 6 discovering each test file separately, those discovery-time imports
accumulate across files until a later file's discovery hard-errors:

instructions/powershell.instructions.md:613

• Use the possessive wording It block's (or Its) here; It's is the contraction for “it is” and is incorrect in this sentence.

`-ForEach`, never by the `It`'s own `-ForEach`. PowerShell evaluates the `-Skip:` argument

instructions/powershell.instructions.md:590

• $IsWindows is not defined in Windows PowerShell 5.1, which this repository still supports; an undefined variable makes -not $IsWindows true, so this supposedly Windows-only test is skipped on the Desktop runner. Use a guard that treats Desktop as Windows or explicitly qualify the example for PowerShell 7+.

It 'Runs only on Windows' -Skip:(-not $IsWindows) {

instructions/powershell.instructions.md:720

• These instructions are consumed by this repository's Pester 5 compatibility leg as well as Pester 6, but -AllowNullOrEmptyForEach is a Pester 6-only parameter. Applying the recommended form in a shared suite makes Pester 5 fail during discovery; the existing tests/Help.tests.ps1 instead uses an if ($collection) guard. Mark this advice as Pester 6-only or include the compatible pattern.

Add `-AllowNullOrEmptyForEach` only to collections that can legitimately be empty. Leave it off
wherever an empty collection means something upstream is broken - there the throw is the signal

instructions/powershell.instructions.md:783

• The $pesterConfiguration object was already set to Run.PassThru = $true in the preceding “Good” example, so this “Bad” invocation still returns a result and does not demonstrate the claimed $null behavior. Reset Run.PassThru to $false (or create a fresh configuration) before invoking it.

$testResult = Invoke-Pester -Configuration $pesterConfiguration

instructions/powershell.instructions.md:707

• The claim that Import-Module -RequiredVersion cannot rescue a selected Pester version contradicts this repository's compatibility test: tests/Test-PSBuildPester.tests.ps1:50-51 imports the requested version before discovery and :284-291 verifies that only that version remains loaded; Test-PSBuildPester.ps1:70-76 intentionally preserves an already-loaded module. Narrow this text to dependency-manifest pins, otherwise it tells agents that the suite's tested version-selection mechanism cannot work.

`Import-Module -RequiredVersion` does not rescue it either, because autoloading re-resolves
`Describe` for every test file during discovery and picks the highest installed version
regardless of what was imported first. The only way to make a lower pin stick is to remove the

instructions/update.instructions.md:157

• skills.vendorPath is configurable above, but this sentence promises direct discovery only for clients scanning the fixed .agents/skills/ path. If a repository chooses another vendorPath, native Agent Skills clients will not find the skill there, so the new configuration can produce a vendored skill that those clients ignore. Qualify direct discovery to the default path (or make non-default paths unsupported) and document the fallback.

Agents that natively scan `.agents/skills/` (for example Cursor and opencode) pick the skill up
directly; the `AGENTS.md` routing plus the `CLAUDE.md` bridge covers agents that do not.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[tablackburn]

Agreed, and fixed upstream rather than here: tablackburn/ai-agent-instruction-modules#41.

This pull request is a verbatim sync of AIM 0.12.0. Editing the rule locally would create drift that the next sync silently reverts, so instructions/contributing.instructions.md sends corrections to instruction text upstream. That PR scopes the rule to "the Pester the suite itself runs on" and documents the install-only compatibility matrix as the exception, citing requirements.pester-matrix.psd1 as the case that motivated it.

The concern is exactly right about the risk: as written, an agent could have deleted the 5.9.0 pin and quietly reduced the matrix to one major.

Separately, this repository does have a real pinning problem, just not the one the rule describes. requirements.psd1 pins Pester = '6.0.0' and the suite has been running on 6.1.0 — the pin is not honored. Filed as #172 with the evidence.

[tablackburn]

Verified and correct — fixed upstream in tablackburn/ai-agent-instruction-modules#41 rather than here, since this is a verbatim sync and a local edit would be reverted by the next one.

The two statements do conflict. Line 807: a wrapping InModuleScope "forces the module to load during discovery rather than execution". Line 816: InModuleScope "requires the module to be loaded already - otherwise the test fails with No modules named 'X' are currently loaded".

The upstream rewrite describes the chain the original skipped: a top-level InModuleScope is file-scope code, so it runs during discovery, and because it needs an already-loaded module the Import-Module satisfying it has to sit at file scope too — that import is what runs at discovery on every file, and what accumulates into the "Multiple script or manifest modules" error. The advice is unchanged; only the reason is now accurate.

While confirming this I also checked the suppressed comment on line 809, which flags that the new rule condemns a checked-in fixture. That one is correct too. tests/TestModule/Tests/a_InModuleScope.tests.ps1 opens with:

InModuleScope TestModule {
    Describe 'MyModule' {

exactly the forbidden pattern — and deliberately so, since it is the compatibility fixture proving the consumer-facing $PSBPreference.Test.ImportModule path works. It is a fixture simulating a consumer's suite rather than a test of this repository, so the rule and the fixture are not really in conflict, but an agent reading the rule would not know that. Worth a comment in the fixture; not part of a documentation sync.

(Edited: an earlier version of this reply lost the quoted error message to shell escaping.)

[tablackburn]

Correct — fixed upstream in tablackburn/ai-agent-instruction-modules#41 along with the other two, since this pull request is a verbatim sync and a local edit would be reverted by the next one.

Changed to It block's:

# Bad - $_ is not bound yet on the It block's own -ForEach, so every case skips