Understanding the Client-Neutral Architecture in reverse‑skill

The client‑neutral architecture in reverse‑skill uses a three‑layer design with declarative routing contracts, platform‑agnostic scripts, and a shared tool index that any AI coding client can invoke without client‑specific code in the core workflow.

According to the zhaoxuya520/reverse‑skill source code, this architecture enables Claude Code, Codex, Cursor, OpenCode, and other agents to run identical reverse‑engineering workflows by separating concerns into core routing, tool discovery, and optional thin adapters. The system enforces this neutrality through a single source of truth in RULES.md and language‑agnostic scripts that operate unchanged across Windows, Linux, macOS, and Kali.

---

The Three Layers of Client‑Neutral Design

Core Routing & Contracts

The deterministic decision layer decides what skill to run, validates authorization, and defines execution contracts. All routing rules reside in:

• skills/config/routing.json — structured routing data consumed by all clients
• skills/routing.md — human‑readable 3‑axis matrix (target / intent / toolchain)

These rules are enforced by generic scripts in skills/scripts/ that never reference a particular AI client. The authoritative requirement appears in RULES.md (lines 3‑6), which mandates that routing remain client‑agnostic.

A client invokes the primary ladder identically regardless of host:

# PowerShell (Windows)

powershell -NoProfile -ExecutionPolicy Bypass `
  -File "skills/scripts/master-route.ps1" -Hint "analyze malicious APK"

# Bash (Linux/macOS/Kali)

bash skills/scripts/master-route.sh --hint "analyze malicious APK"

The script reads skills/config/routing.json, consults skills/tool-index.md, and writes the selected skill path to work/master-route-<ts>/route-scope.md — the same output format for every client.

Tool Discovery & Bootstrap

The platform‑agnostic registry eliminates hard‑coded paths. The shared source of truth is skills/tool-index.md, which contains absolute tool paths generated by:

powershell -NoProfile -ExecutionPolicy Bypass `
  -File "skills/scripts/refresh-tool-index.ps1"

bash skills/scripts/refresh-tool-index.sh

All clients read this file to locate tools; missing capabilities trigger universal bootstrap scripts:

# PowerShell: bootstrap jadx capability

powershell -NoProfile -ExecutionPolicy Bypass `
  -File "skills/scripts/bootstrap-reverse.ps1" -Capability @('jadx') -StartServices

# Bash: bootstrap jadx capability

bash skills/scripts/bootstrap-reverse.sh jadx --start-services

The manifest skills/scripts/bootstrap-manifest.json enumerates supported capabilities, preventing ad‑hoc tool names from entering the system. No client‑specific paths are ever hard‑coded.

Optional Client Adapters

Thin, isolated wrappers provide host‑specific guidance without polluting core logic. Adapters live in their own documentation folders — such as kali/README-kali.md or docs/platforms/*.md — and are never required for the routing flow.

The core executes entirely without adapters. A client needing extra configuration simply reads its adapter documentation; the core routing never imports or depends on these files. This separation boundary is documented in the "Client integration boundary" section of RULES.md.

---

Execution Flow: How Client‑Neutrality Works in Practice

The system follows a strict sequence that remains identical across all hosts:

1. Read RULES.md — confirms client‑neutrality requirements and loads the routing contract
2. Detect repository root — derived from RULES.md location, not client environment
3. Run primary ladder — skills/MASTER-ROUTING.md or skills/scripts/master-route.ps1 yields a PRIMARY skill via JSON rules
4. Initialize case — skills/scripts/case-init.ps1 creates work/<case>/scope.md and enforces auth.status=granted
5. Verify tools — read skills/tool-index.md; missing tools trigger generic bootstrap
6. Execute skill — skill's own SKILL.md runs using standard contract and evidence‑chain (ops/*)
7. Optional adapter — client‑specific configuration loaded only if needed; core never depends on it

Because every step uses language‑agnostic scripts (PowerShell, Bash, Python) and data files (JSON, Markdown), the workflow executes identically on any platform with any AI client.

---

Why Client‑Neutral Architecture Matters

Benefit	Mechanism
Portability	Same repository operates with dozens of agents without modification
Safety	Client‑specific logic cannot bypass the auth.status=granted authorization gate
Maintainability	Routing rules, tool definitions, and evidence contracts evolve in one place
Testability	Regression suite (skills/scripts/test-routing.ps1) validates 163 benchmark cases on Windows and Ubuntu, guaranteeing client‑independence

The architecture ensures that adding support for a new AI client requires only documentation — never changes to core routing logic.

---

Key Files in the Client‑Neutral Architecture

File	Purpose
RULES.md	Global single source of truth; enforces client‑neutrality
skills/config/routing.json	Structured routing data used by all clients
skills/routing.md	Human‑readable 3‑axis matrix
skills/MASTER-ROUTING.md	Primary fast‑track ladder for skill selection
skills/scripts/master-route.ps1 / master-route.sh	Platform‑agnostic routing entry points
skills/scripts/case-init.ps1 / case-init.sh	Case scaffolding and auth gate enforcement
skills/tool-index.md	Shared registry of absolute tool paths
skills/scripts/bootstrap-reverse.*	Generic capability bootstrap
skills/scripts/refresh-tool-index.*	Tool index regeneration
skills/INDEX.md	Auto‑generated navigation index
skills/field-journal/2026-08-08_client-neutral-structured-routing-pr-integration.md	Design‑time discussion of the refactor

These files collectively implement the client‑neutral architecture: declarative contracts, platform‑agnostic scripts, and a shared index that any client consumes without additional code.

---

Summary

• Three layers separate concerns: core routing, tool discovery, and optional adapters
• RULES.md serves as the single source of truth that mandates client‑neutrality
• skills/config/routing.json and skills/routing.md provide declarative routing without client references
• skills/tool-index.md and bootstrap scripts eliminate hard‑coded paths across platforms
• Adapters are isolated in documentation folders and never required for core execution
• Identical entry points (master-route.ps1/master-route.sh) work with Claude Code, Codex, Cursor, OpenCode, and other agents

---

Frequently Asked Questions

What makes reverse‑skill "client‑neutral" compared to other reverse‑engineering toolkits?

The system never embeds client‑specific logic in its routing workflow. While other toolkits may require VS Code extensions or IDE plugins to function, reverse‑skill exposes identical PowerShell/Bash/Python scripts and JSON/Markdown data files that any AI agent can execute directly. Optional adapters exist only as documentation, not as required dependencies.

How does a new AI client start using reverse‑skill without custom integration?

Clone the repository and execute the platform‑appropriate script:

bash skills/scripts/master-route.sh --hint "your task here"

The client needs no special configuration—the routing system discovers tools via skills/tool-index.md and follows the same contract as every other agent. For host‑specific conventions, create an adapter folder without modifying core files.

Can the client‑neutral design compromise security or authorization?

No. The architecture strengthens security by isolating authorization in skills/scripts/case-init.ps1, which enforces auth.status=granted before any action. Because no client can inject bypass logic into the core routing—adapters are documentation‑only—the authorization gate remains uniform across all hosts.

How is client‑neutrality tested and validated?

The regression suite in skills/scripts/test-routing.ps1 executes 163 benchmark cases on both Windows and Ubuntu, verifying that routing decisions, tool discovery, and case initialization behave identically regardless of environment. Changes that introduce platform or client dependencies fail this validation.

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