name: powershell-module-architect
description: Use when user needs PowerShell module design, function structure, reusable libraries, profile optimization, or cross-version compatibility across PowerShell 5.1 and PowerShell 7+.

PowerShell Module Architect

Purpose

Provides PowerShell module design and architecture expertise specializing in creating structured, reusable, and maintainable PowerShell modules. Focuses on module architecture, function design, cross-version compatibility, and profile optimization for enterprise PowerShell environments.

When to Use

• Transforming scattered scripts into structured, reusable modules
• Designing module architecture with public/private function separation
• Creating cross-version compatible modules (PowerShell 5.1 & 7+)
• Optimizing PowerShell profiles for faster load times
• Building advanced functions with proper parameter validation

Quick Start

Invoke this skill when:
- Transforming scattered scripts into structured, reusable modules
- Designing module architecture with public/private function separation
- Creating cross-version compatible modules (PowerShell 5.1 & 7+)
- Optimizing PowerShell profiles for faster load times
- Building advanced functions with proper parameter validation

Do NOT invoke when:
- Simple one-off scripts that won't be reused (use powershell-5.1-expert or powershell-7-expert)
- Already have well-structured modules needing functionality additions (use relevant domain skill)
- UI development (use powershell-ui-architect instead)
- Security hardening (use powershell-security-hardening instead)

Decision Framework

When to Create a Module

Module Structure Decision

Script Organization Need
│
├─ Few related functions (3-10)?
│  └─ Single .psm1 with inline functions
│
├─ Many functions (10+)?
│  └─ Dot-source pattern (Public/Private folders)
│
├─ Publishing to gallery?
│  └─ Full manifest + tests + docs
│
└─ Team collaboration?
   └─ Git repo + CI/CD + Pester tests

Core Workflow: Transform Scripts into Module

Use case: Refactor 10-50 scattered .ps1 scripts into organized module

Step 1: Analysis

# Inventory existing scripts
$scripts = Get-ChildItem -Path ./scripts -Filter *.ps1 -Recurse

# Analyze function signatures
foreach ($script in $scripts) {
    $content = Get-Content $script.FullName -Raw
    $functions = [regex]::Matches($content, 'function\s+(\S+)')

    Write-Host "$($script.Name): $($functions.Count) functions"
}

# Expected output:
# AD-UserManagement.ps1: 12 functions
# AD-GroupManagement.ps1: 8 functions
# Common-Helpers.ps1: 15 functions (candidates for Private/)

Step 2: Design Module Structure

# Create module skeleton
$moduleName = "Organization.ActiveDirectory"
$modulePath = "./modules/$moduleName"

New-Item -Path "$modulePath/Public" -ItemType Directory -Force
New-Item -Path "$modulePath/Private" -ItemType Directory -Force
New-Item -Path "$modulePath/Tests" -ItemType Directory -Force
New-Item -Path "$modulePath/$moduleName.psm1" -ItemType File -Force
New-Item -Path "$modulePath/$moduleName.psd1" -ItemType File -Force

Step 3: Categorize Functions

Public functions (exported to users):
  ├─ Get-OrgADUser
  ├─ New-OrgADUser
  ├─ Set-OrgADUser
  ├─ Remove-OrgADUser
  └─ ... (user-facing functions)

Private functions (internal helpers):
  ├─ _ValidateDomainConnection
  ├─ _BuildDistinguishedName
  ├─ _ConvertToCanonicalName
  └─ ... (utility functions)

Step 4: Implement Module File

# Organization.ActiveDirectory.psm1

# Dot-source Private functions first
$Private = @(Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Private) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import private function $($import.FullName): $_"
    }
}

# Dot-source Public functions
$Public = @(Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Public) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import public function $($import.FullName): $_"
    }
}

# Export Public functions explicitly
Export-ModuleMember -Function $Public.BaseName

Step 5: Create Module Manifest

# Generate manifest
$manifestParams = @{
    Path              = "$modulePath/$moduleName.psd1"
    RootModule        = "$moduleName.psm1"
    ModuleVersion     = '1.0.0'
    Author            = 'IT Team'
    CompanyName       = 'Organization'
    Description       = 'Active Directory management functions'
    PowerShellVersion = '5.1'  # Minimum version
    FunctionsToExport = @(
        'Get-OrgADUser',
        'New-OrgADUser',
        'Set-OrgADUser',
        'Remove-OrgADUser'
    )
    VariablesToExport = @()
    AliasesToExport   = @()
}
New-ModuleManifest @manifestParams

Step 6: Add Pester Tests

# Tests/Module.Tests.ps1
BeforeAll {
    Import-Module "$PSScriptRoot/../Organization.ActiveDirectory.psd1" -Force
}

Describe "Organization.ActiveDirectory Module" {
    It "Exports expected functions" {
        $commands = Get-Command -Module Organization.ActiveDirectory
        $commands.Count | Should -BeGreaterThan 0
    }

    It "Has valid module manifest" {
        $manifest = Test-ModuleManifest -Path "$PSScriptRoot/../Organization.ActiveDirectory.psd1"
        $manifest.Version | Should -Be '1.0.0'
    }
}

Describe "Get-OrgADUser" {
    It "Accepts Identity parameter" {
        { Get-OrgADUser -Identity "testuser" -WhatIf } | Should -Not -Throw
    }
}

Quick Reference: Advanced Function Template

function Get-OrgUser {
    <#
    .SYNOPSIS
        Retrieves Active Directory user by name.

    .DESCRIPTION
        Queries Active Directory for user object and returns detailed properties.

    .PARAMETER Name
        The username or SamAccountName to search for.

    .EXAMPLE
        Get-OrgUser -Name "jdoe"

        Returns all properties for user jdoe.

    .EXAMPLE
        "jdoe", "asmith" | Get-OrgUser

        Retrieves multiple users via pipeline.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$Name
    )

    process {
        Get-ADUser -Identity $Name -Properties *
    }
}

Integration Patterns

powershell-5.1-expert

• Handoff: Module architecture designed → 5.1 expert implements Windows-specific functions
• Collaboration: Module structure decisions considering 5.1 compatibility

powershell-7-expert

• Handoff: Module structure defined → 7 expert adds modern syntax optimizations
• Collaboration: Dual-mode functions using version detection

windows-infra-admin

• Handoff: Module architecture → Windows admin implements domain-specific logic
• Shared responsibility: Active Directory, GPO, DNS module functions

azure-infra-engineer

• Handoff: Module patterns → Azure engineer builds cloud automation modules
• Integration: Cross-cloud modules combining on-prem & Azure

Red Flags - When to Escalate

Additional Resources

• Detailed Technical Reference: See REFERENCE.md
• Profile optimization workflow
• Module manifest template

• Dynamic parameters pattern

• Code Examples & Patterns: See EXAMPLES.md

• Anti-patterns (monolithic files, missing help)
• Cross-version compatibility patterns
• Advanced parameter validation