What is powershell-safe-field-guide?

This repository is a field guide, not a piece of software, documenting how to safely use Windows PowerShell as the layer that runs automated commands for coding tools like Codex. It focuses specifically on the compatibility, safety, and maintainability problems that show up when PowerShell is used this way, combining general rules with notes from real problems the author actually ran into, such as escaping issues over SSH and WSL, character encoding and byte order mark problems, Chinese text getting cut off, and Windows locking a running executable file during a build. The scope is kept narrow on purpose. It covers how PowerShell parses commands when called from automation tools, how argument boundaries behave when PowerShell calls external programs like Git, SSH, WSL, Bash, Python, Rust, or Docker, encoding and truncation issues specific to PowerShell, and the problem of a running Windows executable being locked so a new build cannot overwrite it. Separate topics like Linux binary compatibility, glibc, and musl static builds are considered out of scope for the main guide and are only covered briefly in an appendix note. The guide's central piece of advice is to avoid nesting a complex command inside layer after layer of quotation marks, since every extra layer of parsing is a chance for something to be expanded early, escaped incorrectly, or have an argument silently dropped. Instead it recommends, in order of preference, using PowerShell's own cmdlets, calling native commands with an argument array, writing a temporary script file and running it directly, or using ProcessStartInfo's argument list, reserving heavier tools like Start-Process or cmd.exe for cases that specifically need them. Beyond the written guide, the repository also ships an installable Codex skill version of these rules, which can be added to a machine running Codex using a provided install script, after which Codex needs to be restarted to load it. The documentation includes worked examples of common mistakes, checklists for deployment and encoding, and a sample remote deployment script, with a stated rule that real incidents get recorded in notes or checklists while only reusable, general rules make it into the main docs.