Crusader_Decomp/.github/instructions/shell-operations.instructions.md

description	applyTo
Shell-operation guardrails for shared PowerShell sessions, tool availability checks, and multiline command workarounds	**

Shell Operations

Use these rules when running shell commands from this workspace.

General Rules

• Prefer built-in workspace tools for file search, text search, file reads, and edits before dropping to the terminal.
• Keep terminal commands short and single-line when possible.
• Treat the shared PowerShell session as fragile after any prompt-continuation or escape-sequence artifact appears.

Tool Availability

• Do not assume rg is installed.
• Before using rg, check availability with Get-Command rg -ErrorAction SilentlyContinue.
• If rg is unavailable, use workspace search tools first.
• If shell-side fallback is still needed, use PowerShell-native alternatives:
  • Get-ChildItem -Recurse -File for file discovery
  • Select-String for text search

Multiline Command Safety

• Do not paste multiline commands directly into the shared PowerShell terminal when a one-line command or script file will do.
• Do not send multiline PowerShell hash tables, arrays, or loops directly to the shared terminal if the same work can be expressed as:
  • one single-line command, or
  • a temporary .ps1 script file executed with pwsh -File, or
  • a temporary .py file executed with Python for Python-side work.
• Always write multiline Python to a temporary .py file and execute that file instead of pasting Python into the terminal.

Recovering From Terminal Weirdness

• If the prompt shows continuation markers, partial prompt redraws, or escape-sequence artifacts, stop issuing more complex commands in that shell.
• Try a single Esc first to clear unfinished input.
• If the shell still looks unhealthy, ask the user to reset or fix the terminal with the ask-questions tool before continuing.
• After recovery, resume with single-line commands or temporary script files instead of retrying the same multiline paste.

Command Style

• Prefer explicit PowerShell cmdlets over aliases in reusable commands.
• Avoid commands that rely on interactive input.
• Prefer one focused command per terminal invocation so failures are easier to attribute.
• When posting HTTP form data from PowerShell, prefer compact one-line request bodies over multiline literal blocks in the shared shell.