windows-compatibility

name	windows-compatibility
description	Cross-platform path handling and command patterns
domain	platform
confidence	high
source	template

Context

This repository may be worked on from Windows, macOS, or Linux. Use patterns that behave consistently across platforms.

Patterns

Paths

• Build file paths with platform-aware utilities instead of manual string concatenation
• Do not assume /-only or \\-only path handling in code
• Resolve paths from the repository root or current working directory intentionally

Filenames

• Avoid characters that are invalid on Windows, especially colons in generated filenames
• Prefer safe timestamps for generated file names

Shell and git usage

• Be careful with commands that behave differently across shells
• When a multi-line commit message is needed in PowerShell, use a file-based message with git commit -F
• Verify commands against the current platform before baking them into scripts or docs

Examples

✓ Good:

• Using path.join(...) in Node.js
• Generating a filename like 2026-03-15T05-30-00Z.json
• Documenting both shell assumptions and required working directory

✗ Poor:

• Hardcoding /tmp/... paths
• Creating filenames with : characters
• Assuming a Bash-only command will work unchanged in PowerShell

Anti-patterns

• Testing only on one operating system
• Hardcoding path separators in source files
• Writing scripts that depend on shell-specific behavior without noting it