Platform-Specific Script Paths in Generated Command Files

[nacho4d]

Problem

When users run specify init --ai <agent> on Windows, the generated command files (e.g., .bob/commands/speckit.plan.md) contain hardcoded Windows-specific script paths:

1. **Setup**: Run `.specify/scripts/powershell/setup-plan.ps1 -Json` from repo root...

When these files are committed to git and a macOS/Linux teammate pulls them, the commands fail because:

• PowerShell scripts don't exist on Unix systems
• PowerShell-specific argument syntax (-Json) doesn't work in bash

This creates merge conflicts in mixed-OS teams where Windows users commit PowerShell paths and Unix users commit bash paths.

Impact

Severity: High - Affects all 19+ supported AI agents in mixed-OS development teams

• ❌ Broken workflows - Commands fail when teammates use different operating systems
• ❌ Merge conflicts - Every command file becomes a conflict point between Windows/Unix users
• ❌ Team friction - Developers must manually fix paths after pulling changes
• ❌ Poor onboarding - New team members on different OS face immediate failures
• ❌ Documentation confusion - Need separate instructions for each platform

Root cause: Release package generation scripts expand platform-specific script paths into command files during build, baking OS-specific paths into committed files.

Proposed Solutions

Solution 1: Minimal Fix with Frontmatter (Simple to implement,Harder for LLMs to deal with)

Approach: Preserve the scripts: section in command files and use placeholders in command body.

Generated command file:

---
scripts:
  sh: .specify/scripts/bash/setup-plan.sh --json
  ps: .specify/scripts/powershell/setup-plan.ps1 -Json
---

1. **Setup**: Run `{SCRIPT}` from repo root...

How it works: AI agents read the frontmatter, detect the user's platform, select the appropriate script path, and substitute {SCRIPT} at runtime.

Solution 2: Polyglot Wrappers (Recommended)

Approach: Create platform-agnostic wrapper scripts that work on both Windows and Unix, with unified command syntax.

Generated command file:

1. **Setup**: Run `.specify/scripts/setup-plan --json` from repo root...

How it works: The wrapper script .specify/scripts/setup-plan (no extension) detects the platform internally and delegates to the appropriate implementation (bash or PowerShell), automatically translating arguments.

Comparison and Recommendation

	Solution 1: Minimal Fix with Frontmatter	Solution2: Polyglot Wrappers
Pros	- ✅ Minimal code changes (easy implementation)	- ✅ More reliable - Direct, concrete paths with no variable substitution means simpler stuff for LLMs. (No frontmatter parsing - LLMs just execute the literal command) - ✅ Better UX - Same documentation for all platforms
Cons	- ⚠️ Requires LLMs to parse YAML frontmatter and substitute placeholders - Custom pattern not in LLM training data, may cause execution errors - ⚠️ Custom placeholder pattern ({SCRIPT}) not standard in LLM training data - ⚠️ Different command syntax per platform (--json vs -Json)	- ⚠️ Requires creating and maintaining 4 additional wrapper scripts

Recommendation

Solution 2 (Polyglot Wrappers) is strongly recommended because:

1. Significantly simpler for AI agents/LLMs - They execute literal commands without parsing frontmatter or substituting custom placeholders
2. Better user experience - Unified command syntax across all platforms
3. More reliable - Reduces risk of LLM execution errors from custom conventions
4. The cost of maintaining 4 additional wrapper scripts is small compared to the long-term benefits in team collaboration and reliability