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..4a1670e 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 - `build.depend.psd1` names the version the build resolves) +- Continuous integration and delivery (GitHub Actions) + ## Module Structure ```text @@ -28,9 +35,21 @@ conventions. │ └── *.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 + +| 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 +64,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 +83,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 +- 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 @@ -80,7 +116,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 (for testing; `build.depend.psd1` sets `Version = 'latest'`) - psake (for build automation) ## Release Process