How Client-Neutral Architecture Isolates the Routing Core from Claude Code and Codex Adapters

The reverse-skill repository achieves complete isolation between its routing core and AI client implementations by enforcing a strict architectural rule that client-specific adapters remain optional while driving all routing decisions exclusively through a centralized routing.json configuration file.

The reverse-skill project is deliberately engineered to maintain a client-neutral architecture that prevents the routing core from depending on any specific AI-client implementation. This design philosophy ensures that Claude Code, Codex, Cursor, and other clients can integrate with the system without introducing hidden dependencies or modifying core workflow files. By centralizing routing logic in platform-agnostic configuration files and bootstrap scripts, the repository preserves a clean separation between the engine and its various client interfaces.

Configuration-Driven Routing Core

Single Source of Truth in routing.json

At the heart of the isolation strategy lies the routing.json file, which serves as the sole configuration source for all routing decisions within the core. According to the repository documentation in README.md, the routing core is driven entirely by this structured configuration file, which is validated by cross-platform CI pipelines. The core scripts read only this file, ensuring that no client-specific files are required for the routing engine to function properly.

This approach guarantees that the routing logic remains agnostic to the calling context. Whether invoked by a human operator, a CI system, or an AI client adapter, the core executes the same command resolution logic based strictly on the JSON configuration.

Mandatory Client-Neutral Rule

The architectural constraint is formally codified in RULES.md at line 5, which explicitly states that the routing core must remain client-neutral and that client-specific adapters are optional and must not be required by core workflows. This rule prevents developers from introducing imports or dependencies on client-specific libraries into the core scripts, such as skills/scripts/test-routing.sh or skills/scripts/master-route.sh.

By enforcing this contract at the documentation and governance level, the repository ensures that the core functionality remains portable across different execution environments without requiring adapter-specific setup.

Bootstrap Scripts Maintain Isolation

Platform-Specific Initialization Without Client Dependencies

The platform-specific bootstrap scripts—including refresh-tool-index.sh and bootstrap-reverse.sh—are explicitly written to avoid creating client dependencies during initialization. As documented in docs/platforms/linux.md at line 117 and docs/platforms/macos.md at line 103, these scripts do not write client configuration files such as ~/.claude/mcp.json or ~/.codex/config.toml unless the user explicitly selects an MCP host during setup.

This design choice guarantees that simply cloning and initializing the repository does not create hidden dependencies on Claude Code, Codex, or any other AI client. The bootstrap process remains focused on setting up the core routing environment and validating the routing.json schema without touching client-specific configuration namespaces.

Adapter Integration Pattern

Client-Side Implementation Only

Claude Code, Codex, Cursor, and OpenCode clients integrate with reverse-skill through their own adapter layers that exist entirely outside the core codebase. As noted in README.md at line 200, the core contains no imports of adapter code; instead, client adapters read the same routing.json file and invoke the core's public commands, such as skills/scripts/test-routing.sh.

This unidirectional dependency relationship—where adapters depend on the core but the core remains ignorant of adapters—ensures that adding support for a new AI client requires no modifications to the routing engine. Adapters simply parse the configuration and execute the appropriate shell commands within the repository root.

Optional Integration Points

When client-specific integration is required, adapters create their own configuration files outside the core contract directory. Because the core does not reference these external files, the repository continues to function identically for other clients. This modular approach allows teams to maintain proprietary or experimental adapters without forking the routing core or risking configuration conflicts.

Implementation Examples

The following examples demonstrate how the client-neutral architecture operates in practice, showing the boundary between core configuration and client adapters.

Core Configuration (routing.json)

{
  "hints": {
    "default": "skills/scripts/master-route.sh",
    "windows": "powershell -File skills/scripts/master-route.ps1"
  },
  "rules": "skills/config/routing.json"
}

This file represents the complete interface between the routing core and its execution environment. No client-specific metadata is required.

Claude Code Adapter (Client-Side)

# claude_adapter.py – loads the repository and invokes the core routing

import subprocess
import json
from pathlib import Path

repo_root = Path(__file__).parent.parent  # assume repo is checked out next to adapter

routing_cfg = json.loads((repo_root / "routing.json").read_text())

def run_task(hint: str):
    cmd = routing_cfg["hints"].get(hint, routing_cfg["hints"]["default"])
    subprocess.run(cmd, shell=True, cwd=repo_root)

# Example usage from Claude Code:

run_task("default")

Codex Adapter (Client-Side)

#!/usr/bin/env bash

# codex_adapter.sh – thin wrapper that calls the core routing script

REPO_ROOT="$(dirname "$(realpath "$0")")/.."
CONFIG="${REPO_ROOT}/routing.json"

hint="${1:-default}"
cmd=$(jq -r ".hints[\"$hint\"] // .hints[\"default\"]" "$CONFIG")
eval "$cmd"

Both adapters operate as thin wrappers that read the shared routing.json and execute the core's entry points without modifying any files within the repository.

Summary

• The routing.json file serves as the single source of truth for all routing decisions, ensuring the core never needs to access client-specific configurations.
• RULES.md at line 5 formally mandates that the routing core must remain client-neutral and that adapters are strictly optional.
• Bootstrap scripts like refresh-tool-index.sh and bootstrap-reverse.sh avoid writing client configs such as ~/.claude/mcp.json or ~/.codex/config.toml during initialization, preventing implicit dependencies.
• Client adapters operate unidirectionally, reading the core's configuration and invoking public scripts like skills/scripts/test-routing.sh without the core importing any adapter code.
• Optional integration points allow adapters to maintain external configuration files without affecting the core workflow or other client implementations.

Frequently Asked Questions

What makes the routing core in reverse-skill client-neutral?

The routing core maintains client-neutrality by reading exclusively from the routing.json configuration file and adhering to the architectural rule defined in RULES.md that prohibits core workflows from requiring client-specific adapters. The core scripts, including skills/scripts/master-route.sh, contain no imports or references to Claude Code, Codex, or other client libraries.

How do Claude Code and Codex adapters interact with the routing core without creating dependencies?

Adapters interact with the core by parsing the same routing.json file that drives all routing decisions and invoking the core's public shell scripts, such as skills/scripts/test-routing.sh. Because this interaction is unidirectional—adapters call the core but the core never calls adapters—no dependency relationship is established from the core's perspective.

Why don't the bootstrap scripts write client-specific configuration files?

The platform bootstrap scripts, documented in docs/platforms/linux.md at line 117 and docs/platforms/macos.md at line 103, are designed to avoid creating hidden dependencies. They do not write to paths like ~/.claude/mcp.json or ~/.codex/config.toml unless the user explicitly opts into MCP host configuration, ensuring that repository initialization remains client-agnostic.

Where is the client-neutral architecture requirement formally defined?

The requirement is formally defined in RULES.md at line 5, which states that the routing core must remain client-neutral and that client-specific adapters are optional and must not be required by core workflows. This document serves as the authoritative source for the repository's architectural constraints regarding client isolation.

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