How the Master Route Script Works in reverse-skill: Routing Logic Explained

The master route script (master-route.ps1) acts as the primary router for the reverse-skill platform, analyzing free-form text hints against a JSON configuration to deterministically select the appropriate Markdown skill file for reverse-engineering tasks.

The master route script serves as the central entry point for the reverse-skill repository, a PowerShell-based framework designed to route security and reverse-engineering tasks to specialized skill documentation. Located at skills/scripts/master-route.ps1, this script implements a deterministic, data-driven algorithm that reads user hints and matches them against configurable keyword patterns. Understanding this routing mechanism is essential for extending the platform or integrating it into automated workflows.

Core Architecture and Single Source of Truth

The routing logic maintains strict separation between code and configuration. Instead of hard-coding routing rules, the script reads exclusively from skills/config/routing.json, ensuring the routing table remains canonical and editable without modifying PowerShell code.

According to lines 20-30 of master-route.ps1, the script loads the JSON configuration at runtime, parsing the routing matrix into a structured object. This design allows security researchers to add new skills or modify keyword patterns simply by updating the JSON file, without risking script integrity.

The configuration defines routes as objects containing unique IDs, file paths to SKILL.md documents, and keyword matching criteria. This architecture enables version-controlled routing logic that can be validated independently using helper scripts like verify-routing-coherence.ps1.

Keyword Matching Algorithm

Between lines 35-52 of master-route.ps1, the script implements a multi-layered regex matching system that evaluates each routing rule against the lower-cased input hint. The algorithm processes three distinct constraint types:

• must – A required regular expression that must match the hint for the rule to qualify
• mustAll – An optional array of regexes where every pattern must match simultaneously
• exclude – A disqualifying pattern; if matched, the rule is discarded regardless of other criteria

For each route entry containing multiple keyword objects, the script iterates through all combinations, adding the route ID to a candidate list whenever all active constraints satisfy the hint text. This granular control prevents false positives while allowing complex conditional routing.

Scoring, Priority, and Confidence Calculation

Once candidate routes are identified, lines 54-79 implement a scoring mechanism that handles overlapping matches. The script constructs a score map ($scores) where routes appearing multiple times—through different keyword object matches—receive incremented scores.

The selection algorithm then traverses the ordered priority array defined in routing.json, choosing the candidate with the highest accumulated score. When scores tie, the script breaks the tie using the priority list order, ensuring deterministic behavior.

Confidence levels derive from match uniqueness:

• high – Single unique match with strong keyword alignment
• medium – Multiple matches with clear scoring differentiation
• low – Ambiguous matches or fallback scenarios

If no routes match, the script defaults to the fallbackId (typically R0) and flags the routing matrix for manual review, as implemented in lines 89-98.

Output Generation and Execution Flow

The script generates reproducible artifacts in a timestamped directory, defaulting to work/master-route-<timestamp> or accepting a custom path via the -OutDir parameter. Between lines 39-66 and 67-74, it creates route-scope.md, a Markdown document containing:

• Timestamp and package metadata
• Original hint text and selected primary route ID
• Route label and path to the specific SKILL.md file
• Confidence level and project root directory
• Secondary route candidates (if applicable)

Following file generation (lines 71-76), the script outputs a colored console summary displaying the primary skill, descriptive label, and confidence rating. It then prompts the user to open the selected SKILL.md, creating an interactive yet CI-friendly workflow that bridges automated routing with manual analysis.

Practical Usage Examples

Execute the router by providing a descriptive hint string:

# Route to APK reverse engineering skill

.\skills\scripts\master-route.ps1 -Hint "reverse an Android APK and check for root detection"

For automated pipelines, specify a custom output directory:

# CI/CD integration with explicit output path

.\skills\scripts\master-route.ps1 -Hint "analyze Windows Active Directory dump" -OutDir "C:\temp\analysis-run"

The resulting route-scope.md follows this structure:

# reverse-skill Master route (PRIMARY)

- created: 2023-11-02T15:08:45.1234567+00:00
- package: reverse-skill
- hint: reverse an Android APK and check for root detection
- primary: R1
- primary_label: APK reverse
- primary_skill: skills/apk-reverse/SKILL.md
- confidence: high
- project_root: C:\proj\reverse-skill
- secondary: (none)

## MUST open next

1. skills/MASTER-ROUTING.md
2. skills/apk-reverse/SKILL.md

Supporting Infrastructure

Several auxiliary scripts ensure routing integrity:

• skills/scripts/lib/WorkRoot.ps1 – Resolves project root directories dynamically
• skills/scripts/verify-routing-coherence.ps1 – Validates JSON schema compliance and detects orphaned routes
• skills/scripts/test-routing.ps1 – Provides test harnesses for regression testing routing logic

Summary

• The master route script in reverse-skill uses skills/config/routing.json as its single configuration source, eliminating hard-coded routing logic
• Keyword matching supports must, mustAll, and exclude regex patterns to filter candidate routes deterministically
• A scoring algorithm combined with priority arrays ensures deterministic route selection, with R0 serving as the fallback ID for unmatched hints
• Each execution generates a timestamped route-scope.md file containing routing metadata and next-step instructions
• The -OutDir parameter enables CI/CD integration while colored console output maintains interactive usability

Frequently Asked Questions

What file does the master route script use to determine routing decisions?

The script reads exclusively from skills/config/routing.json, which contains the complete routing matrix including route IDs, file paths to SKILL.md documents, keyword patterns, and priority ordering. This JSON file serves as the single source of truth, allowing users to modify routing behavior without editing the PowerShell code in master-route.ps1.

How does the script handle ambiguous hints that match multiple routes?

When multiple routes match, the script increments scores for each matching route ID and then consults the ordered priority array from the JSON configuration. The route with the highest score wins; ties are broken by whichever route appears earlier in the priority list. This ensures deterministic selection even with overlapping keyword patterns.

What happens if no routes match the provided hint?

If no keyword patterns satisfy the input hint, the script falls back to the fallbackId (typically R0) defined in routing.json. It generates route-scope.md with a note indicating that the entire routing matrix should be opened for manual review, ensuring users never encounter a dead end when the automated routing fails to find a specific match.

Can the master route script be used in automated CI/CD pipelines?

Yes, the script supports the -OutDir parameter for specifying custom output directories, making it suitable for automated environments. It generates deterministic route-scope.md artifacts that downstream jobs can parse to identify which SKILL.md to execute next, while the colored console output can be captured in build logs for debugging purposes.

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