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

> Discover how the reverse-skill routing core achieves client neutrality. Learn about its architecture and design principles that ensure cross-platform compatibility and eliminate LLM client dependencies.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: architecture
- Published: 2026-08-19

---

**The `reverse-skill` routing core remains client-neutral to eliminate hard dependencies on any specific LLM client, using [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)

All routing decisions inside `reverse-skill` are driven by a single configuration file: [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/client/claude.json) or [`client/codex.toml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/client/codex.toml)—into the appropriate directory, and the framework will recognize it without altering `master-route.ps1` or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh).

As documented in [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.github/workflows/ci.yml) invokes [`test-client-neutral-bootstrap.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) follows the same pattern:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.github/workflows/ci.yml) explicitly verify that `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) and the Linux equivalent reinforce this behavior for end users.