GitHub-Template: Instructions file for Codex

AGENTS.md

This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, Windsurf, Codex, and others) working in this repository.

Project Overview

ModuleName is a PowerShell module hosted at https://github.com/YOUR-USERNAME/YOUR-REPO.

• Language: PowerShell 7.2+
• Build System: Sampler / ModuleBuilder
• Test Framework: Pester 5.6+
• Linter: PSScriptAnalyzer
• License: MIT

Quick Start

# Bootstrap dependencies (required first time)
./build.ps1 -ResolveDependency -Tasks noop

# Run full pipeline (Clean -> Build -> Test)
./build.ps1

# Local pre-push validation (build + analyze + test)
./Tests/test-local.ps1

Build Commands

All commands require PowerShell 7.2+ and use Sampler/ModuleBuilder with InvokeBuild as the task runner. Configuration lives in build.yaml and RequiredModules.psd1.

# Individual tasks
./build.ps1 -Tasks test             # Run Pester tests (builds first)
./build.ps1 -Tasks build            # Build module to output/
./build.ps1 -Tasks publish          # Publish to PowerShell Gallery

# Bootstrap + build (first time or after dependency changes)
./build.ps1 -ResolveDependency -Tasks build

# Local validation (build + analyze + test)
./Tests/test-local.ps1
./Tests/test-local.ps1 -SkipBuild       # Skip build step
./Tests/test-local.ps1 -SkipTests       # Skip Pester tests
./Tests/test-local.ps1 -SkipAnalyze     # Skip PSScriptAnalyzer

Architecture

Directory Layout

YOUR-REPO/
  build.ps1                  # Sampler bootstrap and task runner (vendor)
  build.yaml                 # Build pipeline configuration
  RequiredModules.psd1       # Build dependency specifications
  Resolve-Dependency.ps1     # Dependency resolver (vendor)
  Resolve-Dependency.psd1    # Resolver configuration
  source/
    ModuleName.psd1          # Module manifest
    ModuleName.psm1          # Root module (auto-loads subdirectories)
    Classes/                 # PowerShell class definitions (loaded first)
    Private/                 # Internal helper functions (not exported)
    Public/                  # Exported functions (one file per function)
  Tests/
    Unit/Public/             # Tests for exported functions
    Unit/Private/            # Tests for internal functions
    Integration/             # Integration tests
    TestHelpers/             # Shared test utilities
  Templates/                 # Boilerplate for new functions/tests
  Scripts/                   # Automation scripts
  output/                    # Build output (gitignored)
  docs/                      # Documentation and media assets
    media/                   # Logo, demo GIF, donation QR codes