Difference Between master-route.ps1 and master-route.sh in reverse-skill

The primary distinction is platform targeting: master-route.ps1 is a native PowerShell implementation for Windows systems, while master-route.sh is a Bash wrapper that delegates routing logic to embedded Python for Unix-like environments. Both scripts consume the same routing.json configuration and produce identical output, but differ fundamentally in language, dependencies, and runtime architecture.

The reverse-skill repository maintains dual entry points to ensure cross-platform compatibility for its routing engine. Understanding these differences helps operators choose the appropriate script for their environment and troubleshoot execution failures. This analysis examines the source code of both scripts to reveal their architectural decisions, dependency requirements, and behavioral nuances.

Target Platforms and Runtime Requirements

master-route.ps1 targets Windows PowerShell 5.1 and PowerShell Core (pwsh) on any platform. It requires no external interpreters—only a functioning PowerShell environment.

master-route.sh targets Unix-like shells on Linux, macOS, and Kali systems. It requires both Bash and Python 3, with runtime detection in skills/scripts/master-route.sh lines 31-40:

if ! command -v python3 &> /dev/null; then
    echo "Error: python3 is required but not installed." >&2
    exit 2
fi

Language Architecture and Implementation Strategy

The most significant architectural divergence lies in how each script implements the routing algorithm.

PowerShell: Pure Native Implementation

In skills/scripts/master-route.ps1, all functionality is implemented in PowerShell. The script uses:

• param() block for argument parsing with named parameters (-Hint, -OutDir, -ProjectRoot)
• Regex matching via PowerShell's -match operator for must, mustAll, and exclude rules (lines 35-52)
• System.Collections.Generic.List[string] for score accumulation and priority ordering (lines 54-88)

Bash: Python Delegation Pattern

In skills/scripts/master-route.sh, Bash serves only as a wrapper. The core routing logic resides in an embedded Python heredoc structure (lines 85-100), which:

• Parses command-line arguments through a while–case loop (--hint, --out-dir, --project-root)
• Loads skills/config/routing.json using json.loads() with UTF-8-SIG encoding (lines 66-70)
• Performs regex matching via Python's re.search module
• Stores scores in a Python dict with priority-ordered selection (lines 11-16)

Configuration Loading: Same Source, Different Parsers

Both scripts consume the identical skills/config/routing.json file but use platform-appropriate parsing methods.

PowerShell approach (master-route.ps1 lines 20-33):

$configPath = Join-Path $scriptPath ".." ".." "skills" "config" "routing.json"
$configJson = Get-Content $configPath -Raw -Encoding UTF8
$routingConfig = ConvertFrom-Json $configJson

Python approach (master-route.sh lines 66-70):

config_path = (pathlib.Path(__file__).resolve().parent.parent.parent / "skills" / "config" / "routing.json")
config = json.loads(pathlib.Path(config_path).read_text(encoding="utf-8-sig"))

The UTF-8-SIG handling in the Python version explicitly handles BOM-encoded files, while the PowerShell version relies on PowerShell's native UTF8 encoding detection.

Output Generation and Encoding

Output formatting differs in implementation but produces functionally equivalent results.

Aspect	PowerShell (master-route.ps1)	Bash/Python (master-route.sh)
String building	System.Text.StringBuilder	Python list append operations
File encoding	UTF-8 with BOM (Windows compatibility)	Pure UTF-8 (no BOM)
Output lines	Lines 39-70	Lines 36-61 in embedded Python

The BOM in the PowerShell output ensures correct display in Windows Notepad and legacy Windows tools, while the Unix version omits it for standard POSIX compliance.

Argument Handling Comparison

The command interfaces are similar but use platform-appropriate conventions:

# Windows - PowerShell style with dashes

powershell -File skills/scripts/master-route.ps1 -Hint "enumerate open ports" -OutDir "C:\temp\output" -ProjectRoot "C:\projects\reverse-skill"

# Linux/macOS - GNU long-option style

bash skills/scripts/master-route.sh --hint "enumerate open ports" --out-dir /tmp/output --project-root /home/user/reverse-skill

Note the single-dash PowerShell convention versus double-dash GNU style, and the case sensitivity (-OutDir vs --out-dir).

Error Handling and Exit Codes

Both scripts use identical exit code semantics for cross-platform consistency:

• 0 — Successful routing and file generation
• 2 — Configuration file missing, skill file not found, or runtime dependency failure

The PowerShell script implements explicit exit 2 statements for configuration errors, while the Bash script propagates Python's exit code through exit $?.

Cross-Platform Considerations

PowerShell Core fallback: master-route.ps1 can execute on Linux and macOS through PowerShell Core (pwsh), though this requires intentional installation of the PowerShell runtime.

Bash+Python ubiquity: master-route.sh leverages the near-universal presence of Python 3 on penetration testing distributions (Kali, Parrot) and modern Unix workstations, avoiding PowerShell as a dependency.

Usage Examples by Platform

Windows Native Execution

# From Command Prompt (cmd.exe)

powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\master-route.ps1 -Hint "sql injection detection" -OutDir "C:\Users\analyst\routes"

# From PowerShell directly

.\skills\scripts\master-route.ps1 -Hint "buffer overflow analysis" -ProjectRoot "D:\work\reverse-skill"

Linux/macOS Execution

# Direct execution with explicit bash

bash skills/scripts/master-route.sh --hint "firmware extraction" --out-dir ~/analysis/route-output

# With execution bit set

chmod +x skills/scripts/master-route.sh
./skills/scripts/master-route.sh --hint "protocol reverse engineering"

Key File Reference

File	Purpose
skills/scripts/master-route.ps1	Windows routing entry point (PowerShell native)
skills/scripts/master-route.sh	Unix routing entry point (Bash wrapper + Python)
skills/config/routing.json	Shared routing rule definitions
skills/scripts/lib/WorkRoot.ps1	PowerShell helper for path resolution
skills/MASTER-ROUTING.md	Human-readable routing documentation

Summary

• master-route.ps1 provides a pure PowerShell implementation optimized for Windows environments with native .NET integration and BOM-encoded output for legacy Windows tool compatibility.

• master-route.sh implements a hybrid Bash/Python architecture that prioritizes Unix compatibility through Python's portable standard library, requiring an external interpreter but maximizing cross-distribution reliability.

• Both scripts produce identical routing decisions from the same skills/config/routing.json source, ensuring consistent skill selection regardless of platform.

• Exit codes and core behavior are unified (0 for success, 2 for errors) to support portable automation and CI/CD pipelines.

• Choose master-route.ps1 for Windows-native operations or environments with PowerShell Core; choose master-route.sh for standard Unix penetration testing workflows where Python 3 is guaranteed.

Frequently Asked Questions

Can I run master-route.ps1 on Linux or macOS?

Yes, through PowerShell Core (pwsh). Install PowerShell Core from Microsoft repositories or Homebrew, then execute pwsh skills/scripts/master-route.ps1 -Hint "your query". The script's .NET dependencies function identically on all PowerShell-supported platforms.

Why does master-route.sh require Python instead of pure Bash?

The embedded Python in master-route.sh lines 85-100 provides portable JSON parsing, regex operations, and dictionary-based scoring that would require external dependencies or complex text processing in pure Bash. Python 3 is standard on security-focused distributions, making this dependency acceptable for the target audience.

Do both scripts produce identical route-scope.md files?

Functionally yes—the same routing rules applied to identical hints yield the same primary skill selection. Minor differences exist in output encoding (UTF-8-BOM versus pure UTF-8) and timestamp formatting, but the markdown structure and skill content are equivalent.

What happens if routing.json is malformed?

Both scripts exit with code 2. The PowerShell version throws a descriptive ConvertFrom-Json exception pointing to the syntax error location. The Python version raises a json.JSONDecodeError with line and column information. Neither script continues with partial or default routing in this failure mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}