Why the Reverse-Skill Routing Core Remains Client-Neutral: Architecture and Design Principles

The reverse-skill routing core remains client-neutral to eliminate hard dependencies on any specific LLM client, using skills/config/routing.json as the single source of truth while keeping bootstrap workflows identical across Windows, macOS, Linux, and Kali.

The zhaoxuya520/reverse-skill repository ensures that its routing core remains client-neutral as a foundational architectural constraint rather than an optional convenience. This design choice decouples routing decisions from AI client implementations, allowing the framework to initialize cases and gather evidence before any LLM adapter is loaded. By enforcing this separation, the project maintains a stable core that never requires modification when new clients such as Claude, Codex, or OpenAI are introduced.

Why the Routing Core Remains Client-Neutral by Design

Centralized Routing Configuration in skills/config/routing.json

All routing decisions inside reverse-skill are driven by a single configuration file: skills/config/routing.json. Because the core router reads this JSON file directly, there is no risk of divergence or duplication of routing tables across client-specific adapters.

According to RULES.md at line 5, the governing mandate states: "Keep the routing core client-neutral. Client-specific adapters are optional and MUST NOT be required by core workflows." This rule guarantees that the routing engine never imports or executes code tied to a particular LLM provider during its initialization phase.

Flexibility and Extensibility Without Core Modifications

A client-neutral core makes it trivial to add new AI clients without touching the routing engine. A contributor can drop an adapter configuration—such as client/claude.json or client/codex.toml—into the appropriate directory, and the framework will recognize it without altering master-route.ps1 or master-route.sh.

As documented in docs/platforms/macos.md at line 103, the bootstrap process is "client-neutral by default. It does not write ~/.claude/mcp.json or ~/.codex/config.toml unless an MCP host is explicitly selected." This decouples the addition of new clients from the stable routing contract, letting the core focus purely on path resolution and workflow dispatch.

Security Isolation for Pre-Authorization Workflows

Core workflows—including routing, case initialization, and evidence gathering—must operate before any AI client is invoked. Keeping the routing core client-neutral prevents accidental leakage of secrets or execution of client-specific code before authorization checks are satisfied.

The same RULES.md clause that mandates neutrality also ensures that client-specific adapters are never loaded during critical pre-auth stages. The framework validates auth.status=granted before any adapter code runs, so a client-neutral core acts as a security boundary that keeps LLM credentials and proprietary client logic out of the bootstrap path.

Cross-Platform Bootstrap Consistency

The repository targets Windows, macOS, Linux, and Kali. A client-neutral core guarantees identical routing behavior on every platform, while platform-specific scripts can optionally enable a client only when a user explicitly opts in.

The CI pipeline enforces this guarantee through a client-neutral bootstrap regression test. The workflow file .github/workflows/ci.yml invokes test-client-neutral-bootstrap.sh and test-client-neutral-bootstrap.ps1 at line 55 to confirm that the core initializes correctly without any client configuration present.

Client-Neutral Routing Implementation in Practice

The separation principle is visible in both the PowerShell and Bash entry points. Neither script references a specific LLM client; both read skills/config/routing.json and proceed with generic routing logic.

In skills/scripts/master-route.ps1, the router loads the configuration and exits if the file is missing:

# master-route.ps1 – reads routing.json, never hard-codes any client

$configPath = Join-Path $skillsRoot 'config/routing.json'
if (-Not (Test-Path $configPath)) {
    Write-Host "ERROR: routing config missing" -ForegroundColor Red
    exit 1
}
$routing = Get-Content $configPath -Raw | ConvertFrom-Json

# … routing logic continues without referencing any AI client

The Bash equivalent in skills/scripts/master-route.sh follows the same pattern:

# master-route.sh – client-neutral Bash version

CONFIG_PATH="$SKILLS_ROOT/config/routing.json"
if [[ ! -f "$CONFIG_PATH" ]]; then
    echo "ERROR: routing config missing: $CONFIG_PATH" >&2
    exit 1
fi
python3 - <<EOF
import json, sys
with open("$CONFIG_PATH") as f:
    routing = json.load(f)

# routing logic here (no client code)

EOF

Because these entry points remain free of client-specific imports, the framework can boot on any supported platform even when no AI client is installed.

Summary

• Single source of truth: skills/config/routing.json drives every routing decision, preventing duplicated or divergent route tables.
• Plug-in extensibility: New LLM clients are added via optional adapter configs without modifying master-route.ps1, master-route.sh, or the JSON schema.
• Security boundary: Core workflows execute before any client code loads, ensuring secrets stay isolated until auth.status=granted is confirmed.
• Cross-platform parity: CI regression tests enforce identical client-neutral bootstrap behavior on Windows, macOS, Linux, and Kali.

Frequently Asked Questions

Why not hardcode AI client adapters directly into the router?

Hardcoding adapters would couple routing logic to specific LLM implementations and force core updates every time a new client is released. The reverse-skill framework avoids this by reading skills/config/routing.json as the single source of truth, keeping the engine stable and portable.

How does a client-neutral core improve security?

By refusing to load client-specific code during bootstrap, the core prevents accidental secret leakage and ensures that authorization checks (auth.status=granted) complete before any LLM adapter executes. This isolates sensitive credentials from the routing path.

Can the framework run without any AI client installed?

Yes. The client-neutral bootstrap regression tests in .github/workflows/ci.yml explicitly verify that master-route.ps1 and master-route.sh initialize successfully without any client configuration. The routing core functions independently of LLM adapters.

Where is the client-neutral mandate documented?

The requirement is defined in RULES.md at line 5, which states that client-specific adapters are optional and must not be required by core workflows. Platform-specific documentation in docs/platforms/macos.md and the Linux equivalent reinforce this behavior for end users.

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