Powershell master-route.ps1 Execution Flow and Parameters: Complete Technical Guide

master-route.ps1 is the PRIMARY router script for the reverse-skill framework that matches task hints to appropriate skills via regex-based keyword scoring and generates a route-scope.md file for downstream consumption.

This PowerShell script serves as the central dispatcher in the zhaoxuya520/reverse-skill repository. It interprets natural language task descriptions, evaluates them against configurable routing rules, and produces a deterministic output that automation pipelines can consume. Whether you're integrating reverse engineering workflows or extending the framework with new skills, understanding this execution flow is essential.

Parameters and Input Handling

The script accepts three optional parameters defined in the param block at lines 6-10 of skills/scripts/master-route.ps1:

Parameter	Purpose	Default Behavior
-Hint	Free-text task description (e.g., "extract password hashes")	Empty string; converted to lowercase for matching
-OutDir	Destination folder for route-scope.md	Auto-generated timestamped directory under work/
-ProjectRoot	Explicit project root path for output isolation	Auto-detected via WorkRoot.ps1

The -Hint parameter is the primary driver. The script normalizes it to lowercase at line 14 ($t = $Hint.ToLower()) to ensure case-insensitive keyword matching against routing rules.

Execution Flow: Step-by-Step

1. Load Routing Configuration

The script locates and parses skills/config/routing.json as its single source of truth (lines 20-28). This JSON file contains:

• Route definitions with keywords arrays
• priority ordering for tie-breaking
• meta.fallbackId for unmatched hints

If the configuration file is missing or malformed, the script terminates with exit code 2 (lines 29-33).

2. Keyword Matching and Scoring

For each route definition, the script evaluates three regex-based conditions (lines 35-52):

• must — Required regex that must match for the rule to qualify
• mustAll — Array of regexes where all must match
• exclude — Disqualifying regex; if matched, the rule is discarded

Successful matches accumulate in $sel, with each hit incrementing a per-route score (lines 54-59). This "plus-one per match" scoring preserves historic behavior from earlier framework versions.

3. Priority Validation and PRIMARY Selection

Before selecting a winner, the script validates that the priority list and route definitions remain synchronized (lines 64-72). Divergence triggers a warning but does not halt execution.

The PRIMARY skill selection follows this logic (lines 74-87):

1. Iterate routes in priority order
2. Select the route with highest accumulated score
3. If no route scores, fall back to meta.fallbackId

4. Confidence Determination

The script assigns confidence levels based on match uniqueness (lines 90-97):

Condition	Confidence Level
Single unique route matched	high
Multiple routes tie for top score	medium
Fallback route activated	low

5. Project Root Resolution

At lines 105-112, the script imports skills/scripts/lib/WorkRoot.ps1 and invokes Resolve-ReverseProjectRoot. This helper isolates router output from the skill package itself, ensuring clean separation of framework code from user project data.

6. Output Directory Preparation

If -OutDir is omitted, the script creates a timestamped folder (lines 113-118, 127-136):

# Default pattern: <project_root>/work/master-route-YYYYMMDDHHMMSS/

Falls back to a system temporary directory if project resolution fails.

7. Skill Path Validation

Before generating output, the script verifies that the PRIMARY skill's script file exists (lines 119-126). Missing files trigger exit code 2 with a descriptive error.

8. Generate route-scope.md

The final output is a UTF-8 with BOM markdown document (lines 139-169) containing:

• Original hint and normalized version
• PRIMARY skill ID, label, and confidence level
• Resolved project root path
• Secondary route candidates
• Processing notes and warnings

BOM encoding ensures Windows tooling compatibility.

Usage Examples

Basic Invocation

.\master-route.ps1 -Hint "enumerate active processes"

Creates work/master-route-20230818-154200/route-scope.md with the matched PRIMARY skill.

Explicit Paths

.\master-route.ps1 -Hint "dump browser cookies" `
                   -OutDir "C:\temp\my-route" `
                   -ProjectRoot "D:\my-reverse-project"

Directs output to C:\temp\my-route while resolving project context from D:\my-reverse-project.

Embedded in Automation

# Within a larger reverse engineering pipeline

$routeResult = & "$PSScriptRoot\master-route.ps1" `
    -Hint $taskDescription `
    -OutDir $stageOutput

$primarySkill = (Get-Content "$routeResult\route-scope.md" | 
    Select-String "^primary:\s*(.+)$").Matches.Groups[1].Value

Key Dependencies and Related Files

File Path	Role
skills/scripts/master-route.ps1	PRIMARY router implementation
skills/config/routing.json	Routing rules and priority configuration
skills/scripts/lib/WorkRoot.ps1	Resolve-ReverseProjectRoot function
skills/MASTER-ROUTING.md	Architectural documentation
skills/<skill-id>/skill.ps1	Actual skill scripts invoked post-routing

Exit Codes

Code	Meaning
0	Success — route-scope.md generated
2	Configuration error — missing/invalid routing.json or missing skill file

Summary

• master-route.ps1 implements regex-based keyword scoring against skills/config/routing.json to select the appropriate skill for a task hint
• Three parameters control input (-Hint), output location (-OutDir), and project context (-ProjectRoot)
• Confidence levels (high/medium/low) indicate match certainty based on scoring distribution
• Exit code 2 signals unrecoverable configuration or validation failures
• UTF-8 BOM encoding ensures Windows compatibility for the generated route-scope.md

Frequently Asked Questions

How does master-route.ps1 handle ambiguous hints that match multiple routes?

When multiple routes achieve identical top scores, the script selects the first match in priority order and assigns medium confidence. This deterministic tie-breaking ensures reproducible behavior across invocations. The unselected high-scoring routes appear in the secondary section of route-scope.md for operator review.

What happens if the routing.json file is corrupted or missing?

The script validates JSON parsing at lines 29-33. Malformed or absent configuration triggers immediate termination with exit code 2. No route-scope.md is generated, and error details emit to the error stream. Always verify skills/config/routing.json exists before invocation in automated pipelines.

Can I override the fallback route without modifying the routing configuration?

No — the fallback behavior is controlled exclusively by meta.fallbackId in routing.json. To change the default route for unmatched hints, edit that JSON value. The -Hint, -OutDir, and -ProjectRoot parameters do not influence fallback selection; they only affect input processing and output placement.

Why does the script use UTF-8 with BOM instead of plain UTF-8?

PowerShell's default file encoding on Windows systems produces files that some external tools misinterpret without BOM. The explicit UTF-8 BOM at line 169 ensures predictable handling by editors, diff tools, and downstream automation that may process route-scope.md. This prevents character encoding surprises in mixed-platform environments.

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