squad: Skill for Claude Code

Context

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.

Patterns

Filenames & Timestamps

• Never use colons in filenames: ISO 8601 format 2026-03-15T05:30:00Z is illegal on Windows
• Use safeTimestamp() utility: Replaces colons with hyphens → 2026-03-15T05-30-00Z
• Centralize formatting: Don't inline .toISOString().replace(/:/g, '-') — use the utility

Git Commands

• Never use git -C {path}: Unreliable with Windows paths (backslashes, spaces, drive letters)
• Always cd first: Change directory, then run git commands
• Check for changes before commit: git diff --cached --quiet (exit 0 = no changes)

Commit Messages

• Never embed newlines in -m flag: Backtick-n (\n) fails silently in PowerShell
• Use temp file + -F flag: Write message to file, commit with git commit -F $msgFile

Paths

• Never assume CWD is repo root: Always use TEAM ROOT from spawn prompt or run git rev-parse --show-toplevel
• Use path.join() or path.resolve(): Don't manually concatenate with / or \

Path Comparison (Case Sensitivity)

• Never use naive prefix checks to confine paths: a bare substring/prefix match can let sibling paths escape the intended root
• Never infer case-insensitive behavior from process.platform alone: Windows is case-insensitive, but Darwin volumes are not all case-insensitive. APFS and HFS+ can be case-sensitive; a blanket lowercase conversion on macOS can conflate distinct sibling directories.
• Use filesystem-aware case handling: Only fold case when the relevant volume has been explicitly identified as case-insensitive. Otherwise, compare the resolved path case-sensitively.
• Current implementation caveat: This is the safe target pattern, not a claim about every existing repository implementation. FSStorageProvider currently folds case for all Darwin paths, so its root confinement is not volume-aware on case-sensitive macOS filesystems.
• Resolve first, compare second: resolve both paths before comparing; do not compare user input or unresolved relative segments.
• Root confinement must be exact-match-or-separator: a path is within rootDir only when it equals the normalized root exactly or starts with rootDir + path.sep; a bare substring/prefix match lets /root-escape slip past /root. Filesystem roots are valid roots and must remain exact-match-or-separator checks.
• Where it matters: security checks such as path-traversal prevention, rootDir confinement, and any validation that a resolved path stays under an allowed directory
• Pattern:

  import path from 'node:path';
  
  function normalizeForRootComparison(value: string, volumeIsCaseInsensitive = false): string {
    return volumeIsCaseInsensitive ? value.toLowerCase() : value;
  }
  
  function isPathWithin(candidate: string, rootDir: string, volumeIsCaseInsensitive = false): boolean {
    const a = normalizeForRootComparison(path.resolve(candidate), volumeIsCaseInsensitive);
    const b = normalizeForRootComparison(path.resolve(rootDir), volumeIsCaseInsensitive);
    const boundary = b.replace(/[\\/]+$/, '') + path.sep;
    return a === b || a.startsWith(boundary);
  }
  

• Resolve first, compare second: compare normalized absolute paths; only treat a case mismatch as equivalent when the relevant filesystem volume has already been confirmed to be case-insensitive