kevinpatrickrobbins/codebase-audit/shell-and-output

Shell and Output (PowerShell 7+)

Applicability

This skill targets harnesses whose shell execution does NOT reliably return stdout/stderr and exit codes — custom runners, minimal agent loops, or wrappers that swallow output. If the harness's shell tool already reports output and exit codes deterministically — Claude Code's Bash and PowerShell tools do — this skill does not apply. Use the native tools directly; the logging protocol below would only add cost.

Purpose

Ensure all CLI work is deterministic and verifiable on Windows PowerShell 7+.

This skill exists to prevent false positives, silent failures, and ambiguous shell execution results.

Key principles:

• Never assume success from missing or empty output
• Always capture stdout and stderr to a log file
• Always verify exit codes and scan for failure indicators
• Avoid non-PowerShell tooling and syntax
• Avoid chaining meaningful commands

This skill is authoritative.

Preconditions

• PowerShell version: 7+
• Operating system: Windows
• Repository root is the current working directory unless otherwise stated

Hard Rules

1) No Silent Success

• Never conclude success from “no output” in the chat UI.
• All meaningful commands MUST use the output capture protocol.
• All meaningful shell commands MUST be executed via

Invoke-LoggedCommand from scripts/ShellOutput.psm1.

Direct invocation of shell commands is prohibited.

2) Output Capture Protocol (Required)

Every meaningful command MUST:

1. Create ./temp if it does not exist
2. Redirect stdout and stderr to ./temp/<log>.txt
3. Wait briefly after execution

• Default: 500ms
• Increase for long-running or heavy commands

1. Read the log file contents
2. Evaluate:

• Exit code
• Failure pattern scan

1. Decide success or failure based on both
2. Summarize:

• Command executed
• Exit code
• Log path
• Key log lines (especially on failure)

3) Searching Rules

• Never use grep
• For command output logs, use Select-String
• For repository content searches:
• Prefer the agent’s repository search tool
• Avoid shell pipelines

4) No Tool Invocation Inside Shell Strings

• Shell command strings MUST NOT invoke other tools
• Tool usage must remain outside shell execution contexts

5) Quoting and Paths

• Always quote paths that may contain spaces
• Use Join-Path for path construction
• Use ./temp for all command logs

6) Command Chaining Policy (PowerShell 7.5.4)

• Do NOT chain meaningful commands
• Execute one meaningful command per invocation
• Each command MUST have its own dedicated log file

Required Outputs (Per Meaningful Command)

For every meaningful command, the agent MUST report:

• Command string executed
• Log file path
• Exit code
• Whether failure patterns were detected
• Short excerpt of relevant log lines

(especially on failure)

PowerShell Implementation

• Import the module from this skill's own scripts/ directory (resolve the skill root from wherever this skill is installed):

``powershell Import-Module "<skill-root>/shell-and-output/scripts/ShellOutput.psm1" ``

• Primary execution helper:
• Invoke-LoggedCommand

• Assertion helper:
• Assert-LoggedSuccess (fail fast on detected errors)

Enforcement

If any rule in this skill is violated:

• The command result is invalid
• The agent MUST stop and re-execute using the correct protocol
• Downstream reasoning based on invalid execution is prohibited

Intent

This skill exists to ensure:

• Deterministic shell behaviour
• Verifiable outcomes
• Reproducibility across agents and sessions
• Clear failure visibility

Correctness is more important than speed.