Shell Platform

---
name: shell-platform
description: Platform-specific shell command rules for Windows PowerShell 5.x
type: skill
scope: local
---

# Shell Platform Skill

**Status:** ACTIVE (confirmed by user)

The critical rules are in `.cursorrules` Rule 1. This skill provides the full reference.

## When to Use

- Running any shell command on Windows (PowerShell 5.x)
- Executing Python, pip, conda, or git commands
- Chaining commands or using heredocs
- Any terminal operation where platform-specific syntax matters

## Prerequisites

- Windows with PowerShell 5.x (not pwsh 7+)
- Anaconda installed at `C:\App\Anaconda`
- Session cache file at `.cursor/cache/session-paths.json`

## Process

### Step 1: Read Session Cache
Read `.cursor/cache/session-paths.json` to get verified tool paths.

### Step 2: Apply PowerShell 5.x Rules
Use `;` instead of `&&`, avoid heredocs, use full tool paths.

### Step 3: Execute and Verify
Run the command and verify exit code. On path failure, fall back through the resolution priority.

## Session Cache (READ FIRST)

Before any shell command, read the verified paths:

```
.cursor/cache/session-paths.json
```

This has the working Python path and shell type for this machine. Reading it once prevents every path error.

## PowerShell 5.x Rules

This machine runs `powershell.exe` (5.x), NOT `pwsh.exe` (7+). Three things break every time:

### 1. No `&&` Chaining

```powershell
# WRONG -- fails with "Das Token && ist kein gültiges Anweisungstrennzeichen"
cd "path" && git pull

# CORRECT
cd "path"; git pull
```

### 2. No Heredoc

```powershell
# WRONG -- fails silently or with parse error
git commit -m "$(cat <<'EOF'
message
EOF
)"

# CORRECT -- simple string
git commit -m "feat: Add new feature"

# CORRECT -- multi-line with multiple -m
git commit -m "feat: Add new feature" -m "Detailed description here"

# CORRECT -- PowerShell here-string (if needed)
$message = @"
Title line

Body paragraph
"@
git commit -m $message
```

### 3. Use Full Tool Paths

```powershell
# WRONG -- may not be in PATH
python scripts/validation/sync_manifest_versions.py --sync

# CORRECT -- verified path from session cache
C:\App\Anaconda\python.exe scripts/validation/sync_manifest_versions.py --sync
```

## Command Chaining Reference

| Bash | PowerShell 5.x | Purpose |
|------|----------------|---------|
| `&&` | `;` | Sequential execution |
| `\|\|` | `; if ($LASTEXITCODE -ne 0) { ... }` | Run on failure |
| `\|` | `\|` | Pipe (same) |

## Tool Paths (Windows)

| Tool | Verified Path | Env Variable |
|------|--------------|--------------|
| Python | `C:\App\Anaconda\python.exe` | `PYTHON_PATH` |
| Pip | `C:\App\Anaconda\Scripts\pip.exe` | `PIP_PATH` |
| Conda | `C:\App\Anaconda\Scripts\conda.exe` | `CONDA_PATH` |
| Git | System PATH | -- |

## Path Resolution Priority

1. **Session Cache** (`.cursor/cache/session-paths.json`) -- fastest, already verified
2. **Environment Variable** (e.g., `$env:PYTHON_PATH`)
3. **Config File** (`.cursor/config/tools.json`)
4. **Auto-detect** (`where.exe python`)
5. **Fallbacks** (hardcoded paths above)

When a path fails: try next in order, then update the session cache.

## Important Rules

1. NEVER use `&&` in PowerShell 5.x -- use `;`
2. NEVER use heredoc (`<<EOF`) -- use simple strings or multiple `-m` flags
3. ALWAYS use full tool paths on Windows
4. ALWAYS set `working_directory` on Shell calls instead of `cd`
5. ALWAYS verify file paths with `Glob` or `LS` before referencing them in commands
6. Check `user_info.Shell` -- if `powershell`, apply these rules automatically