SKILL.md (2665B)
1 --- 2 name: "windows-compatibility" 3 description: "Cross-platform path handling and command patterns" 4 domain: "platform" 5 confidence: "high" 6 source: "earned (multiple Windows-specific bugs: colons in filenames, git -C failures, path separators)" 7 --- 8 9 ## Context 10 11 Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platform-specific assumptions: ISO timestamps with colons (illegal on Windows), `git -C` with Windows paths (unreliable), forward-slash paths in Node.js on Windows. 12 13 ## Patterns 14 15 ### Filenames & Timestamps 16 - **Never use colons in filenames:** ISO 8601 format `2026-03-15T05:30:00Z` is illegal on Windows 17 - **Use `safeTimestamp()` utility:** Replaces colons with hyphens → `2026-03-15T05-30-00Z` 18 - **Centralize formatting:** Don't inline `.toISOString().replace(/:/g, '-')` — use the utility 19 20 ### Git Commands 21 - **Never use `git -C {path}`:** Unreliable with Windows paths (backslashes, spaces, drive letters) 22 - **Always `cd` first:** Change directory, then run git commands 23 - **Check for changes before commit:** `git diff --cached --quiet` (exit 0 = no changes) 24 25 ### Commit Messages 26 - **Never embed newlines in `-m` flag:** Backtick-n (`\n`) fails silently in PowerShell 27 - **Use temp file + `-F` flag:** Write message to file, commit with `git commit -F $msgFile` 28 29 ### Paths 30 - **Never assume CWD is repo root:** Always use `TEAM ROOT` from spawn prompt or run `git rev-parse --show-toplevel` 31 - **Use path.join() or path.resolve():** Don't manually concatenate with `/` or `\` 32 33 ## Examples 34 35 ✓ **Correct:** 36 ```javascript 37 // Timestamp utility 38 const safeTimestamp = () => new Date().toISOString().replace(/:/g, '-').split('.')[0] + 'Z'; 39 40 // Git workflow (PowerShell) 41 cd $teamRoot 42 git add .squad/ 43 if ($LASTEXITCODE -eq 0) { 44 $msg = @" 45 docs(ai-team): session log 46 47 Changes: 48 - Added decisions 49 "@ 50 $msgFile = [System.IO.Path]::GetTempFileName() 51 Set-Content -Path $msgFile -Value $msg -Encoding utf8 52 git commit -F $msgFile 53 Remove-Item $msgFile 54 } 55 ``` 56 57 ✗ **Incorrect:** 58 ```javascript 59 // Colon in filename 60 const logPath = `.squad/log/${new Date().toISOString()}.md`; // ILLEGAL on Windows 61 62 // git -C with Windows path 63 exec('git -C C:\\src\\squad add .squad/'); // UNRELIABLE 64 65 // Inline newlines in commit message 66 exec('git commit -m "First line\nSecond line"'); // FAILS silently in PowerShell 67 ``` 68 69 ## Anti-Patterns 70 71 - Testing only on one platform (bugs ship to other platforms) 72 - Assuming Unix-style paths work everywhere 73 - Using `git -C` because it "looks cleaner" (it doesn't work) 74 - Skipping `git diff --cached --quiet` check (creates empty commits)