From fb56de5b69f4276aafbed16c8bb4fe16e5c85f53 Mon Sep 17 00:00:00 2001
From: Mike Swanson <mike@azcomputerguru.com>
Date: Tue, 12 May 2026 20:04:16 -0700
Subject: [PATCH] docs: Add PowerShell best practices to CODING_GUIDELINES

Added comprehensive section on PowerShell execution patterns:
- Documented mandatory -NoProfile -File approach
- Explained rationale (prevents font/codepage changes, avoids Git Bash quoting issues)
- Referenced .claude/hooks/pre-bash-pwsh-script.sh enforcement
- Provided correct and incorrect examples

This addresses recurring font change issues on Windows when running PowerShell commands through Claude Code CLI.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .claude/CODING_GUIDELINES.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/.claude/CODING_GUIDELINES.md b/.claude/CODING_GUIDELINES.md
index 6525cb5..62411b2 100644
--- a/.claude/CODING_GUIDELINES.md
+++ b/.claude/CODING_GUIDELINES.md
@@ -31,6 +31,40 @@ Never use emojis in code, scripts, config files, log messages, or output strings
 
 ---
 
+## PowerShell Execution (Windows)
+
+### ALWAYS Use -NoProfile -File Pattern
+
+Never use inline PowerShell commands (`-Command` or `-c`). Always write scripts to `.ps1` files and execute with `-NoProfile -File`.
+
+**Rationale:**
+- **Prevents font/codepage changes**: PowerShell profile scripts often set `chcp 65001` or modify `[Console]::OutputEncoding`, which changes the Claude Code CLI font and breaks rendering
+- **Avoids Git Bash quoting issues**: Inline commands have unpredictable quote escaping and variable expansion (`$_`, `$foo`) before PowerShell sees them
+- **Enforced by hooks**: `.claude/hooks/pre-bash-pwsh-script.sh` blocks inline execution and requires the file-based approach
+
+**Correct:**
+```bash
+# Write script to file using Write tool
+cat > /tmp/script.ps1 << 'EOF'
+Get-Process | Select-Object -First 5 Name, CPU
+EOF
+
+# Execute with -NoProfile -File
+pwsh -NoProfile -File /tmp/script.ps1
+```
+
+**Incorrect (BLOCKED BY HOOKS):**
+```bash
+# These will be rejected
+powershell -Command "Get-Process"
+pwsh -c "Get-Date"
+powershell.exe -Command '$x = 5; Write-Host $x'
+```
+
+**Reference:** See `.claude/hooks/pre-bash-pwsh-script.sh` for enforcement details.
+
+---
+
 ## Security
 
 - Never hardcode credentials -- use SOPS vault or environment variables
@@ -70,4 +104,4 @@ All scripts and tools use ASCII status markers:
 
 ---
 
-**Last Updated:** 2026-04-02
+**Last Updated:** 2026-05-12