Architect Powershell Helper

Transforms fragmented PowerShell scripts into clean, documented, testable enterprise modules with proper architecture.

When to Use This Agent

Choose this agent when you need to:

• Refactor scattered PowerShell scripts into reusable modules with public/private function separation and manifest versioning
• Design PowerShell profiles optimized for fast load times with lazy imports and organized profile fragments
• Build cross-version compatible tooling that detects capabilities across PowerShell 5.1 and 7+ environments

Consider alternatives when:

• You need to execute or debug a specific PowerShell command rather than architect a module structure
• Your task involves writing infrastructure provisioning scripts that belong in a dedicated IaC tool like Terraform or Ansible

Quick Start

Configuration

Copy
name: architect-powershell-helper
type: agent
category: security

Example Invocation

Copy
claude agent:invoke architect-powershell-helper "Refactor our AD user management scripts into a proper module"

Example Output

Module Architecture Plan: ADUserToolkit v1.0.0

Public Functions (exported):
  - New-ADUserOnboarding
  - Set-ADUserDepartment
  - Remove-ADUserOffboarding
  - Get-ADUserAuditReport

Private Helpers (internal):
  - Resolve-OUPath
  - Test-ADConnection
  - Format-AuditEntry

Manifest: ADUserToolkit.psd1
  RootModule: ADUserToolkit.psm1
  FunctionsToExport: @('New-ADUserOnboarding','Set-ADUserDepartment',...)
  RequiredModules: @('ActiveDirectory')

Pester Test Coverage: 4 test files generated
  - New-ADUserOnboarding.Tests.ps1 (6 test cases)
  - Set-ADUserDepartment.Tests.ps1 (4 test cases)
  ...

Core Concepts

Module Architecture Overview

Aspect	Details
Function Separation	Public functions exported via manifest; private helpers dot-sourced internally
Manifest Standards	.psd1 files with semantic versioning, dependency declarations, and export lists
DRY Helper Pattern	Shared logic extracted into Private/ folder functions to eliminate duplication
Dot-Sourcing Layout	Public/ and Private/ directories dot-sourced in .psm1 for clarity and load performance
Error Handling	Standardized try/catch with Write-Error, -ErrorAction propagation, and $ErrorActionPreference

Module Directory Architecture

MyModule/
├── MyModule.psd1            [Manifest - version, exports, deps]
├── MyModule.psm1            [Root module - dot-sources all]
├── Public/
│   ├── Get-Widget.ps1       [Exported function]
│   ├── Set-Widget.ps1       [Exported function]
│   └── Remove-Widget.ps1    [Exported function]
├── Private/
│   ├── Resolve-Path.ps1     [Internal helper]
│   └── Test-Connection.ps1  [Internal helper]
└── Tests/
    ├── Get-Widget.Tests.ps1 [Pester test suite]
    └── Set-Widget.Tests.ps1 [Pester test suite]

Configuration

Parameter	Type	Default	Description
targetVersion	string	"5.1+7"	PowerShell version compatibility target (5.1, 7, or both)
modulePrefix	string	""	Organization prefix for function naming conventions (e.g., "Corp")
strictMode	boolean	true	Enable Set-StrictMode -Version Latest in generated modules
pesterVersion	string	"5.x"	Pester framework version for generated test scaffolding
profileScope	string	"CurrentUserCurrentHost"	Target profile scope when engineering profile fragments

Best Practices

1. Enforce CmdletBinding on Every Function - Advanced functions with CmdletBinding enable -Verbose, -Debug, -WhatIf, and -Confirm support automatically. This transforms simple scripts into production-grade commands that integrate with PowerShell's preference variable system and support pipeline operations safely.

2. Separate Public and Private Surfaces Rigorously - Exporting only intentional public functions through the module manifest prevents accidental API surface sprawl. Private helpers should never appear in FunctionsToExport, ensuring consumers depend only on stable, documented interfaces that you control.

3. Implement Capability Detection for Cross-Version Code - Rather than hardcoding version checks, use feature detection patterns like $PSVersionTable.PSEdition and Get-Command -ErrorAction SilentlyContinue to determine available capabilities. This produces modules that degrade gracefully rather than failing on version mismatches.

4. Keep Profile Load Times Under 500ms - Profile scripts run on every session launch, so heavy imports and complex initialization destroy developer productivity. Use lazy loading patterns where modules are imported only when their functions are first called, and measure startup time with Measure-Command { pwsh -NoProfile -Command 1 }.

5. Write Pester Tests Before Refactoring - Capture current script behavior in Pester test cases before restructuring into modules. This safety net ensures the refactored module produces identical outputs and catches regressions in parameter handling, error paths, and edge cases during the architectural transformation.

Common Issues

1. Module Not Found After Installation - The module directory name must exactly match the .psd1 manifest filename and the RootModule entry. Verify the module exists in a path listed in $env:PSModulePath and that the manifest's ModuleVersion field is properly set, as PowerShell uses versioned subdirectories for side-by-side installations.

2. Functions Missing from Exported Surface - When FunctionsToExport in the manifest is set to @() or omits function names, those functions become invisible to Import-Module consumers. Always explicitly list every public function in the manifest rather than relying on wildcard exports, which bypass the performance optimization of module autoloading.

3. Profile Slowing Down Terminal Launch - Dot-sourcing heavy modules or running network-dependent commands in profile scripts causes multi-second delays. Audit profile load time by temporarily renaming profile files, then reintroduce fragments one at a time. Move any logic taking over 50ms into on-demand module imports or background jobs.