# Understanding the Client-Neutral Architecture in reverse‑skill

> Discover the client-neutral architecture in reverse-skill. Learn how its three-layer design enables platform-agnostic AI coding without client-specific code for seamless integration.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** — structured routing data consumed by all clients
- **[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) (lines 3‑6), which mandates that routing remain client‑agnostic.

A client invokes the primary ladder identically regardless of host:

```powershell

# PowerShell (Windows)

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

```

```bash

# Bash (Linux/macOS/Kali)

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

```

The script reads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), consults [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)**, which contains absolute tool paths generated by:

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

```

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

```

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

```powershell

# PowerShell: bootstrap jadx capability

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

```

```bash

# Bash: bootstrap jadx capability

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

```

The manifest [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** — confirms client‑neutrality requirements and loads the routing contract
2. **Detect repository root** — derived from [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) location, not client environment
3. **Run primary ladder** — [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md); missing tools trigger generic bootstrap
6. **Execute skill** — skill's own [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Global single source of truth; enforces client‑neutrality |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Structured routing data used by all clients |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Human‑readable 3‑axis matrix |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Primary fast‑track ladder for skill selection |
| `skills/scripts/master-route.ps1` / [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) | Platform‑agnostic routing entry points |
| `skills/scripts/case-init.ps1` / [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) | Case scaffolding and auth gate enforcement |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) | Auto‑generated navigation index |
| [`skills/field-journal/2026-08-08_client-neutral-structured-routing-pr-integration.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** serves as the single source of truth that mandates client‑neutrality
- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** and **[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)** provide declarative routing without client references
- **[`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.