bash-usage

Bash Usage on the QBrainAi Windows Host

This skill governs shell selection for the optional QBAgent (QBrainAi.QBAgent, Quad-Brain) run_bash and run_powershell tools. The host OS is Windows 11. PowerShell 7+ (pwsh.exe) is the primary and always-present shell. Git Bash is optional and only usable when it is resolvable on PATH.

When to Use

• A QBAgent tool loop needs to run a shell command and you must choose between run_powershell and run_bash.
• A run_bash call returned available: false and you need the correct fallback.
• You are porting a POSIX shell snippet (the build doc examples use ./build.ps1 ... but show bash fences) and need to decide which tool actually executes it.

When Not to Use

• Pure file read/write/search work. Use the dedicated file tools, not a shell.
• Session log, TODO, requirements, import/export, or traceability operations. Those must go through the mcpserver-claude-code-plugin wrapper (workflow.* / client.* methods), not through run_bash or run_powershell. Never cat, grep, or sed the docs/Project/TODO.yaml or session-log files from a shell.
• Long-lived servers or builds you intend to background. Prefer the project's documented entry points (./build.ps1 Compile, ./build.ps1 Test, ./build.ps1 StartServer).

Inputs

• The shell command string you intend to run.
• The QBAgent tool result fields, specifically the available boolean returned by run_bash. When available is false, Git Bash was not found on PATH and no command was executed.
• Whether the command is POSIX-specific (uses /dev/null, && chains over POSIX builtins, grep/sed/awk, single-quoted here-docs) or is already PowerShell-native.

Critical Rules

1. run_powershell (pwsh) is the primary shell on this host and is always available. Default to it. The repo standard is pwsh.exe (PowerShell 7+); never target powershell.exe (Windows PowerShell 5.1).
2. run_bash is OPTIONAL. It only works when Git Bash is on PATH. If the tool returns available: false, treat bash as unavailable for this run and do not retry the same call expecting a different result.
3. Do not invent shell tool names, flags, or fields. Only run_powershell and run_bash exist for QBAgent shell execution, and the only availability signal is the available field on the run_bash result.
4. When run_bash is unavailable, translate the command to PowerShell and run it through run_powershell. Do not assume a bash path or call bash.exe directly.
5. Use absolute paths in commands. The agent working directory is not guaranteed to persist between tool calls.
6. PowerShell syntax differs from POSIX: use $null not /dev/null, $env:VAR not $VAR, backtick for line continuation, and pwsh-native cmdlets instead of grep/sed/cat.