From 578eb891bf539bdf581f340424701545c14017c4 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Wed, 19 Aug 2026 11:22:14 -0400 Subject: [PATCH 1/3] chore(aim): adopt the standard AGENTS.md template Replace the hand-written AGENTS.md with AIM's AGENTS.template.md at v0.11.0, matching the five sibling repositories that already run the standard template. The bespoke file carried no Template Version stamp and no Instruction Applicability Matrix, so the agent skills vendored into .agents/skills/ had no matrix row to route from -- the Skill Dependencies section it did gain pointed at "the Instruction Applicability Matrix above", which did not exist. The template comment block is removed, Last sync is set to 2026-08-19, and the skills row plus the Skill Dependencies section are copied verbatim from ScheduledTasksManager and ReScenePS so all seven repositories match. No hand-written content is lost. The repository-specific parts move into instructions/repository-specific.instructions.md, which is never synced from upstream: the conventions list, a Key Files table, Code Style, Adding a New Function, and the Pester testing requirement, merged with what was already there rather than duplicated. The {{ModuleName}} and {{Prefix}} placeholders are preserved so Initialize-Template.ps1 still substitutes them. Also correct a stale claim. Both files said "Pester 5.x" while build.depend.psd1 pins Version = 'latest' and build.psake.ps1 was hardened for Pester 6; the text now says Pester 6 and names the pin as the source of truth. --- AGENTS.md | 93 +++++++++++-------- .../repository-specific.instructions.md | 35 ++++++- 2 files changed, 88 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ff38cf9..42c3ca4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,61 +1,76 @@ # AI Agent Instructions -This document provides guidance for AI agents (such as Claude Code, GitHub Copilot, or similar tools) when working with this repository. +AI agents working in this repository must follow these instructions. -## Repository Overview +Template Version: 0.11.0 -This is a PowerShell module project following standard conventions for: -- Module structure (Public/Private function separation) -- Build automation (psake + PowerShellBuild) -- Testing (Pester 5.x) -- CI/CD (GitHub Actions) +Last sync: 2026-08-19 -## Key Files +## Instructions for AI Agents -| File | Purpose | -|------|---------| -| `build.ps1` | Entry point for all build operations | -| `build.psake.ps1` | Psake task definitions | -| `{{ModuleName}}/{{ModuleName}}.psd1` | Module manifest | -| `{{ModuleName}}/{{ModuleName}}.psm1` | Module root file | -| `tests/` | Pester test suite | +AI agents **must**: -## Common Tasks +1. **When deploying or updating this template, follow `instructions/update.instructions.md` and + update the Last sync date above.** -### Building +1. **Read `instructions/agent-workflow.instructions.md` FIRST to determine which other instruction + files apply to your task.** Follow all applicable instructions before proceeding with work. -```powershell -./build.ps1 -Task Build -Bootstrap -``` +1. **Check `aim.config.json`** for module configuration, external source, and skill dependency settings. -### Testing +## Instruction Applicability Matrix -```powershell -./build.ps1 -Task Test -``` +Use this matrix to determine which instruction files to read based on your task: -### Adding a New Function +| Task Type | Required Instructions | +| ---------------------------- | -------------------------------------- | +| Any task | `agent-workflow.instructions.md` | +| Any code or documentation | `shorthand.instructions.md` | +| Git operations | `git-workflow.instructions.md` | +| Writing tests | `testing.instructions.md` | +| Build, test, or publish (psake / PowerShellBuild) | `.agents/skills/psake/SKILL.md`, `.agents/skills/powershellbuild/SKILL.md` | +| PowerShell code | `powershell.instructions.md` | +| Documentation | `markdown.instructions.md` | +| README files | `readme.instructions.md` | +| GitHub CLI usage | `github-cli.instructions.md` | +| Creating releases | `releases.instructions.md` | +| Repository-specific work | `repository-specific.instructions.md` | +| Updating instructions | `update.instructions.md` | +| Contributing to upstream | `contributing.instructions.md` | -1. Create function file in `{{ModuleName}}/Public/` or `{{ModuleName}}/Private/` -2. Add function name to `FunctionsToExport` in `.psd1` (public functions only) -3. Create corresponding test file in `tests/Unit/Public/` or `tests/Unit/Private/` +## Available Instruction Files -## Code Style +- `agent-workflow.instructions.md` - Pre-flight protocol and task workflow +- `shorthand.instructions.md` - Avoid shorthand and abbreviations +- `git-workflow.instructions.md` - Git branching, commits, and PR conventions +- `testing.instructions.md` - Test writing best practices +- `powershell.instructions.md` - PowerShell coding standards +- `markdown.instructions.md` - Markdown formatting standards +- `readme.instructions.md` - README maintenance guidelines +- `github-cli.instructions.md` - GitHub CLI usage guidelines +- `releases.instructions.md` - Release management guidelines +- `repository-specific.instructions.md` - Repository-specific customizations +- `update.instructions.md` - Procedures for updating instructions +- `contributing.instructions.md` - Contributing improvements to upstream -- Use `{{Prefix}}` prefix for all function nouns (e.g., `Get-{{Prefix}}Example`) -- Include full comment-based help with .SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE -- Use `[CmdletBinding()]` on all functions -- Follow PSScriptAnalyzer rules +## Quick Reference -## Testing Requirements +### Before Starting Any Task -- All public functions must have corresponding test files -- Use Pester 5.x syntax (BeforeAll, BeforeDiscovery, etc.) -- Mock external dependencies in unit tests +1. Identify the task type from the matrix above +1. Read all applicable instruction files +1. Follow the guidelines when implementing -## Instructions Directory +### Best Practices -See the `instructions/` folder for detailed guidance on specific topics. +- Follow existing patterns in the codebase +- Keep solutions simple and focused +- Only make changes that are directly requested +- Follow language-specific guidelines + +## Repository-Specific Instructions + +See `instructions/repository-specific.instructions.md` for customizations specific to this repository. ## Skill Dependencies diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index 61f7f10..47cd819 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -13,6 +13,13 @@ conventions. {{Description}} +The repository follows the standard conventions of this module fleet: + +- Module structure (Public and Private function separation) +- Build automation (psake and PowerShellBuild) +- Testing (Pester 6) +- Continuous integration and delivery (GitHub Actions) + ## Module Structure ```text @@ -31,6 +38,17 @@ conventions. └── build.psake.ps1 # psake build tasks ``` +### Key Files + +| File | Purpose | +| ------------------------------------ | ------------------------------------ | +| `build.ps1` | Entry point for all build operations | +| `build.psake.ps1` | psake task definitions | +| `build.depend.psd1` | PSDepend build dependency versions | +| `{{ModuleName}}/{{ModuleName}}.psd1` | Module manifest | +| `{{ModuleName}}/{{ModuleName}}.psm1` | Module root file | +| `tests/` | Pester test suite | + ## Naming Conventions ### Function Prefix @@ -45,6 +63,18 @@ Private functions also use the `{{Prefix}}` prefix but are not exported: - `Invoke-{{Prefix}}Helper` +## Code Style + +- Include full comment-based help with `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, and `.EXAMPLE` +- Use `[CmdletBinding()]` on all functions +- Follow the PSScriptAnalyzer rules configured in `PSScriptAnalyzerSettings.psd1` + +## Adding a New Function + +1. Create the function file in `{{ModuleName}}/Public/` or `{{ModuleName}}/Private/` +2. Add the function name to `FunctionsToExport` in the module manifest (public functions only) +3. Create the corresponding test file in `tests/Unit/Public/` or `tests/Unit/Private/` + ## Testing Requirements ### Pester Tests @@ -52,6 +82,9 @@ Private functions also use the `{{Prefix}}` prefix but are not exported: - All public functions must have corresponding tests in `tests/Unit/Public/` - All private functions should have tests in `tests/Unit/Private/` - Mock external dependencies - never make real HTTP requests in tests +- Use Pester 6 syntax (`BeforeAll`, `BeforeDiscovery`, and so on). `build.depend.psd1` pins + Pester to `latest`, so the build floats onto the newest released major version; the `UnitTest` + task in `build.psake.ps1` reads that same value so the installed and imported versions agree ### Running Tests @@ -80,7 +113,7 @@ The module uses psake for build automation: - PowerShell 5.1 or higher (PowerShell 7+ recommended) - No external module dependencies for runtime -- Pester (for testing) +- Pester 6 (for testing; `build.depend.psd1` pins `Version = 'latest'`) - psake (for build automation) ## Release Process From f02acef807df2d3341ffb00b605dbabfb7fe0f05 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Wed, 19 Aug 2026 11:34:41 -0400 Subject: [PATCH 2/3] docs: name build.depend.psd1 as the Pester version source of truth Review feedback. `Version = 'latest'` selects the newest release rather than pinning one, so it can cross a major boundary; wording that hard-codes a major version drifts the same way the "Pester 5.x" text this branch replaced did. State the resolved major once, as the current value, and point at `build.depend.psd1` everywhere else. --- instructions/repository-specific.instructions.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index 47cd819..fc4279e 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -17,7 +17,7 @@ The repository follows the standard conventions of this module fleet: - Module structure (Public and Private function separation) - Build automation (psake and PowerShellBuild) -- Testing (Pester 6) +- Testing (Pester - `build.depend.psd1` names the version the build resolves) - Continuous integration and delivery (GitHub Actions) ## Module Structure @@ -82,9 +82,11 @@ Private functions also use the `{{Prefix}}` prefix but are not exported: - All public functions must have corresponding tests in `tests/Unit/Public/` - All private functions should have tests in `tests/Unit/Private/` - Mock external dependencies - never make real HTTP requests in tests -- Use Pester 6 syntax (`BeforeAll`, `BeforeDiscovery`, and so on). `build.depend.psd1` pins - Pester to `latest`, so the build floats onto the newest released major version; the `UnitTest` - task in `build.psake.ps1` reads that same value so the installed and imported versions agree +- Write tests for the Pester major version the build resolves, currently Pester 6 (`BeforeAll`, + `BeforeDiscovery`, and so on). `build.depend.psd1` sets `Version = 'latest'` rather than a + pinned version, so the build floats onto the newest release and can cross a major boundary; + the `UnitTest` task in `build.psake.ps1` reads that same value, so the installed and imported + versions agree. Treat `build.depend.psd1` as the source of truth, not this sentence ### Running Tests @@ -113,7 +115,7 @@ The module uses psake for build automation: - PowerShell 5.1 or higher (PowerShell 7+ recommended) - No external module dependencies for runtime -- Pester 6 (for testing; `build.depend.psd1` pins `Version = 'latest'`) +- Pester (for testing; `build.depend.psd1` sets `Version = 'latest'`) - psake (for build automation) ## Release Process From a2291e8db6f9a53791128a67b4748356a9e15ab5 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Wed, 19 Aug 2026 11:35:03 -0400 Subject: [PATCH 3/3] docs: list build.depend.psd1 in the module structure tree Review feedback. The Key Files table references it, so the tree that sits directly above should show where it lives. --- instructions/repository-specific.instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index fc4279e..4a1670e 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -35,7 +35,8 @@ The repository follows the standard conventions of this module fleet: │ └── *.tests.ps1 # Meta, Manifest, Help tests ├── instructions/ # AI agent instructions (AIM) ├── build.ps1 # Build entry point -└── build.psake.ps1 # psake build tasks +├── build.psake.ps1 # psake build tasks +└── build.depend.psd1 # PSDepend build dependency versions ``` ### Key Files