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/                    # 14 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
│   │   ├── pull-requests.instructions.md        # Branch, commit, and PR conventions
│   │   └── 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, 2 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)

1. Click "Use this template" above
2. Create your new repository
3. 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

See CONTRIBUTING.md for how the repository is laid out, the conventions that are easy to break, the checks to run, and how pull requests are written. Every change here reaches each consuming repository on its next sync, so open an issue first for anything larger than a fix.

📊 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

• Questions, bugs, and outdated standards: open a GitHub Issue
• Security vulnerabilities: report privately, as SECURITY.md describes
• Documentation: see the Documentation folder
• Troubleshooting: see the organized guides in the 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