AI PowerShell Standards

Enterprise-grade PowerShell development standards, shipped as GitHub Copilot instructions and Claude Code
rules, for consistent, secure, and high-quality PowerShell code across teams and projects.

Target versions (verified 2026-08-01): PowerShell 7.6 (LTS) is the default target,
supported through 14-Nov-2028. Windows PowerShell 5.1 remains supported as a compatibility
target. PowerShell 7.4 and 7.5 both reach end of support on 10-Nov-2026 — plan upgrades now.
See powershell-version.instructions.md
for the full lifecycle table, version-gated features, and breaking changes.

🚀 Quick Start

For New Projects

# Use as template repository or clone
git clone https://github.com/fadwen/ai-powershell-standards.git
cd ai-powershell-standards

# Install standards in your project
./Tools/Install-CopilotStandards.ps1 -ProjectPath "C:\YourProject" -StandardsType "Module"

For Existing Projects

# Add as submodule
git submodule add https://github.com/fadwen/ai-powershell-standards.git .copilot-standards

# Link instructions (Windows)
mklink .github\copilot-instructions.md .copilot-standards\.github\copilot-instructions.md

# Link instructions (Linux/macOS)
ln -s .copilot-standards/.github/copilot-instructions.md .github/copilot-instructions.md

📋 What's Included

🤖 GitHub Copilot Integration

Main Instructions: Comprehensive enterprise PowerShell standards
Prompt Files: Quick-access prompts for common tasks
Variable Prompts: Interactive code generation
Quality Gates: Automated validation and enforcement

🧠 Claude Code Integration

Always-On Rule: .claude/rules/powershell-standards/copilot-instructions.md imports the main
instructions, so every Claude Code session starts with the standards
Path-Scoped Rules: the other files in that folder mirror each instruction file with the same globs
as its applyTo, so a standard loads only when Claude works on a matching file
Slash Commands: .claude/commands/powershell-standards/ offers each prompt file as
/powershell-standards:<name>, attaching the prompt rather than copying it
Synced Like Everything Else: the sync workflow and installer mirror both folders, and never touch
a project's own CLAUDE.md, rules, or commands
Single Source: The .github/ files are the only copy. The Claude files reference them, never
restate them

📚 PowerShell Standards

Version Baseline: PowerShell 7.6 (LTS) targeting, with the support lifecycle, version-gated
cmdlets, and breaking changes for 7.5/7.6 documented in one place
Community Best Practices: Integrated PowerShell community guidelines
Enterprise Security: Audit logging, credential handling, and data-classification patterns
covering controls that SOX, GDPR, and HIPAA programmes commonly ask for
Performance Optimization: Memory management and pipeline efficiency, including the
version-dependent += guidance that changed in PowerShell 7.5
Modern Tooling: Install-PSResource (Microsoft.PowerShell.PSResourceGet) over PowerShellGet
v2, with a capability check for Windows PowerShell 5.1 fallback
Testing Standards: Pester 6.2 patterns — Should-* assertions, custom assertions via
New-ShouldAssertion, BeforeDiscovery data, self-contained test files, and 13 supporting guides
covering mocking, CI, and templates

🛠️ Development Tools

Project Templates: Module, script collection, and application templates
Validation Scripts: Automated standards compliance checking
CI/CD Integration: GitHub Actions and Azure DevOps templates
Troubleshooting Guides: Organized problem-solving documentation

🎯 Key Features

✨ Automatic Code Generation

Enterprise Functions: Complete functions with security, error handling, and documentation
Module Scaffolding: Full module structure with tests and documentation
CI/CD Pipelines: Automated quality gates and deployment workflows

🔒 Security by Design

Input Validation: Comprehensive sanitization and validation patterns
Credential Management: SecretManagement integration and secure handling
Regulatory Patterns: Audit-trail, consent, and access-control patterns for SOX, GDPR, and
HIPAA work. These are code patterns and review prompts — they support a compliance programme but
do not constitute one, and none of it substitutes for your own controls, evidence, and audit
Security Scanning: Automated vulnerability detection

📊 Quality Assurance

Code Analysis: Comprehensive quality assessment tools
Performance Testing: Automated benchmarking and optimization
Documentation Standards: PlatyPS-generated command help, comment-based help, README generation
Community Compliance: PowerShell best practices enforcement

📁 Repository Structure

ai-powershell-standards/
├── .github/
│   ├── copilot-instructions.md          # Main Copilot instructions (applied automatically)
│   ├── instructions/                    # 13 scoped instruction files, applied by `applyTo` glob
│   │   ├── powershell-version.instructions.md   # Version baseline, lifecycle, breaking changes
│   │   ├── pester.instructions.md               # Pester 6.2 core testing standards
│   │   ├── platyps.instructions.md              # Help docs: PlatyPS Markdown to MAML
│   │   └── pester-supporting-docs/              # 13 guides: mocking, assertions, CI, templates
│   ├── prompts/                         # 10 `/prompt-name` files for Copilot Chat
│   └── workflows/                       # Quality gates run on every pull request
├── .claude/
│   ├── commands/
│   │   └── powershell-standards/        # 10 slash commands, one per prompt file; mirrored to consumers
│   └── rules/
│       └── powershell-standards/        # Claude Code rules: 13 path-scoped, 1 always-on; mirrored to consumers
├── Documentation/                       # Guides and the deliberate anti-pattern demo
├── powershell-standards/
│   └── Examples/                        # Worked examples the instructions link to; mirrored to consumers
├── Templates/                           # Module, script-collection, and application templates
│   └── Workflows/                       # Workflows to copy into consuming projects
├── Tools/                               # Install-CopilotStandards, Test-StandardsCompliance
├── Troubleshooting/                     # Organized problem-solving guides
├── .markdownlint.json                   # Documentation lint rules enforced in CI
├── CLAUDE.md                            # Notes for working on this repository itself
└── README.md                            # This file

🚀 Getting Started

1. Enable Copilot Instructions

Current VS Code picks these up with no configuration: .github/copilot-instructions.md is applied
automatically, .github/instructions/*.instructions.md apply to files matching their applyTo
glob, and .github/prompts/*.prompt.md are available as /prompt-name in Copilot Chat.

You only need settings if you keep these files somewhere other than the defaults:

{
  "chat.instructionsFilesLocations": { ".github/instructions": true },
  "chat.promptFilesLocations": { ".github/prompts": true }
}

Older guidance recommended chat.promptFiles and
github.copilot.chat.codeGeneration.useInstructionFiles. Settings-based instructions were
deprecated in VS Code 1.102 in favour of the file-based layout above; neither setting is required
now.

2. Enable Claude Code

Nothing to configure either. Claude Code discovers .claude/rules/ recursively. The always-on rule in
.claude/rules/powershell-standards/ imports .github/copilot-instructions.md at launch, and each
path-scoped rule imports one instruction file when Claude touches a matching file. The rules import
rather than copy, so there is one set of standards to maintain. Run /memory inside Claude Code to
see what is loaded.

The prompt files are slash commands in Claude Code too. .claude/commands/powershell-standards/ holds
one command per prompt, so /new-function in Copilot Chat is /powershell-standards:new-function
here. The / menu matches on any part of a name, so typing /new-func is enough to find it.

The installer and the sync workflow mirror both folders into consuming projects along with the
.github/ files and the examples. A project's own CLAUDE.md and anything else it keeps under
.claude/rules/ or .claude/commands/ are never touched.

3. Choose Your Integration Method

Option A: Template Repository (New Projects)

Click "Use this template" above
Create your new repository
Start developing with standards automatically applied

Option B: Git Submodule (Existing Projects)

git submodule add https://github.com/fadwen/ai-powershell-standards.git .copilot-standards

Option C: Direct Copy (Simple Projects)

./Tools/Install-CopilotStandards.ps1 -ProjectPath "." -StandardsType "Basic"

Option D: Direct Copy, Kept in Sync (Recommended)

Options A through C copy the instruction files once. They then drift as this repository moves on.
Adding -IncludeSyncWorkflow also installs a weekly job that mirrors the instruction files and
opens a pull request when they fall behind:

./Tools/Install-CopilotStandards.ps1 -ProjectPath "." -StandardsType "Basic" -IncludeSyncWorkflow

The workflow needs Settings → Actions → General → Workflow permissions → "Allow GitHub Actions to
create and approve pull requests" enabled on the target repository, and it overwrites local edits
to the mirrored paths. See Templates/Workflows/ for both caveats in
full.

4. Verify Setup

# Test standards compliance
./Tools/Test-StandardsCompliance.ps1 -Path "."

# Create your first function using Copilot
# In VS Code, type: /new-function

💡 Usage Examples

Quick Function Creation

# Use the new-function prompt in Copilot Chat
/new-function
# Copilot will prompt for: function name, purpose, parameters
# Generates complete enterprise-standard function with tests

Security Review

# Select PowerShell code, then use security-review prompt
/security-review
# Comprehensive security analysis with compliance validation

Performance Optimization

# Select code that needs optimization
/optimize-performance
# Get specific optimization recommendations with benchmarks

🧪 Testing and Quality

Automated Testing

Standards for the code you generate — Pester 6.2 throughout:

Unit Tests: Pester tests targeting 80%+ coverage
Integration Tests: External dependency validation
Performance Tests: Benchmarking and regression detection
Security Tests: Input validation and credential handling

Quality Gates

These run against this repository on every pull request, and the templates set the same gates up
for yours:

PSScriptAnalyzer: Zero errors in production files (test files are analyzed separately, since
patterns like a hardcoded -ComputerName 'MOCKSERVER' are legitimate in a mock)
Pester: Fails on FailedCount and FailedContainersCount — a file that fails discovery
contributes zero failed tests and would otherwise read green
Coverage: Measured over Tools/ and powershell-standards/Examples/, the code this repository ships
and holds up as exemplary. Templates are excluded: they are scaffolding to copy, so covering a
placeholder measures nothing
Security Scanning: Credential leak and vulnerability detection. Secret patterns apply to all
files; code-execution patterns apply only to .ps1/.psm1, since a .psd1 is restricted data
and cannot invoke a cmdlet
Documentation: markdownlint over all Markdown, plus comment-based help validation
Community Standards: PowerShell best practices compliance

🔧 Customization

Team-Specific Instructions

Create .instructions.md files in your project for team-specific standards:

---
applyTo: "**/*.ps1"
---
# Team-specific PowerShell standards
- Use specific naming conventions for your domain
- Include team-specific validation patterns
- Reference team tools and processes

Project-Specific Prompts

Add custom prompts for your specific use cases:

---
agent: 'agent'
description: 'Creates infrastructure automation function'
---
Create function for infrastructure management with:
- SCOM integration
- ServiceNow ticket correlation
- Active Directory validation

📚 Documentation

Core Documentation

PowerShell Version Baseline:
Support lifecycle, choosing a target, version-gated features, breaking changes
Pester 6.2 Testing Standards: Core testing
requirements, with 13 supporting guides for
mocking, assertions, CI, templates, and v6 migration
PlatyPS Help Documentation: Generating and
shipping module help with Microsoft.PowerShell.PlatyPS — Markdown source, MAML output, drift gate
Implementation Guide: Step-by-step setup and usage
PowerShell Best Practices: Community standards reference
Enterprise Extensions: Organization-specific additions

Quick References

Prompt Files Guide: How to use and create prompts
Troubleshooting: Organized problem-solving guides
Examples: Real-world usage examples

🤝 Contributing

Adding New Standards

Create feature branch: git checkout -b feature/new-standard
Add instruction files with comprehensive examples
Include validation tests and documentation
Submit pull request with impact assessment

Improving Existing Standards

Test changes with real-world scenarios
Validate backward compatibility
Update documentation and examples
Include performance impact analysis

📊 Measuring Adoption

No benchmark study backs this repository, so it makes no claims about what adopting it will do for
your team. Measure it in your own environment instead — the quality gates emit most of what you
need:

PSScriptAnalyzer findings per pull request, split by severity
Test coverage and pass rate from the Pester gate
Security scan findings — hardcoded secrets and unsafe patterns caught before merge
Documentation completeness — comment-based help present on exported functions, markdownlint
clean

Track these before and after adoption if you want a real before/after comparison.

🆘 Support

Getting Help

Issues: Report bugs or request features via GitHub Issues
Discussions: Ask questions in GitHub Discussions
Documentation: Check the Documentation folder
Troubleshooting: See organized guides in Troubleshooting folder

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏆 Acknowledgments

PowerShell Community: For establishing excellent best practices and style guidelines
GitHub Copilot Team: For creating the extensible instruction system
Enterprise PowerShell Users: For real-world validation and feedback

Ready to transform your PowerShell development with AI-assisted enterprise standards?

🚀 Get Started Now | 📚 Read the Docs | 🤝 Contribute