# How Role Assignments in `role-map.md` Drive Skill Routing in Reverse-Skill

> Learn how role assignments in reverse-skill's role-map.md control skill routing. Understand the two-layer system governing handoffs and accountability for efficient workflow management.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-13

---

**The [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) file in reverse-skill defines who is responsible for each phase of work, while `master-route` determines which skill runs, creating a two-layer system where role assignments govern handoffs and accountability on top of primary skill selection.**

Reverse-skill implements a strict separation of concerns between *what* skill executes and *who* owns the current work phase. The [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) file in `skills/ops/` serves as the authoritative source for role-to-responsibility mapping, working in concert with the keyword-driven routing system in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This article explains how these components interact to enforce auditable, role-gated workflows.

## The Two-Layer Routing Architecture

Reverse-skill's routing system operates across two orthogonal layers that never overlap in function.

### Layer 1: Primary Skill Selection via [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)

The `master-route` logic reads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to score keywords against available skills and return a `PRIMARY` skill path. This file contains no role information—it purely answers the question: *which skill family should handle this task?*

Example [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) entries point to paths like `attack-chain/`, `pentest-tools/`, or reverse-engineering skill directories.

### Layer 2: Role Assignment via [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)

After primary skill selection, `master-route.ps1` consults [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) to initialize the human accountability layer. This markdown file contains:

- **Role definitions**: Human-readable responsibilities for codes like `lead`, `cie`, `cpe`, `cre`
- **Skill family ownerships**: Which roles invoke which primary skills
- **Handoff rules**: Trigger conditions and required deliverables for role transitions

The output is written to [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) as follows:

```yaml
lead_role: lead          # ← from role-map.md

specialist_roles: []     # ← filled with cie, cpe, cre … as work progresses

primary_skill: <skill>   # ← result of routing.json lookup

```

## The Six-Step Role-Routing Workflow

The interaction between [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) and skill routing follows a strict sequence:

| Step | Component | Action |
|------|-----------|--------|
| 1 | `master-route` | Parses user hint, scores [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), selects `PRIMARY` skill, outputs `lead_role=lead` and empty `specialist_roles[]` |
| 2 | `case-init` / [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) | Persists routing result, assigned `lead_role`, and specialist placeholder. Only `lead` may edit scope before ACT. |
| 3 | **Lead** | Uses *Lead* row in [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) to plan engagement, split work into sub-phases, decide which specialists to invoke |
| 4 | **Handoff** | Lead appends new specialist to `specialist_roles[]` when trigger conditions met; [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) handoff table drives transition |
| 5 | **Specialist** | Reads its [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) row to know which skill family to invoke, runs PRIMARY skill or sub-skill, produces evidence |
| 6 | **Doc / Lead** | Any role hands off to `doc` for report generation; lead may re-run `master-route` if new primary skill required |

## Role Definitions and Skill Ownership in [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)

The [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) file maps each role code to concrete responsibilities and skill families. According to the reverse-skill source structure:

- **`lead`**: Engagement owner, sole scope editor before ACT, planner of sub-phases
- **`cie`**: Assets/reconnaissance specialist; owns interaction with `pentest-tools/` family
- **`cpe`**: Live service tester; designated for `pentest-tools/` deep invocation
- **`cre`**: Reverse engineering specialist; long list of RE skills per [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) line references
- **`doc`**: Report generation via `docs-generator/`

Each specialist role contains a specific skill family assignment that determines which PRIMARY skill directory they operate within, even when multiple roles share the same top-level skill path.

## Handoff Execution and Validation

Role transitions in reverse-skill are not informal—they are contractually enforced through [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) lookup and [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) mutation.

### Example: Lead to CIE Handoff

When asset discovery triggers a handoff from `lead` → `cie`:

1. Lead consults [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) handoff table for trigger condition ("需要资产面") and required deliverable ("scope + 已知域名/IP")
2. Lead appends `cie` to `specialist_roles` in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md):

```yaml
specialist_roles:
  - cie

```

3. Lead annotates handoff in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) with evidence package
4. CIE role activates, reads [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) line 10 to confirm `pentest-tools/` skill family ownership

### Handoff Table Parsing (Pseudo-code)

The [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) handoff table uses markdown table syntax parseable by PowerShell:

```powershell

# Assume $from = 'lead', $to = 'cie'

$handoff = Get-Content skills/ops/role-map.md |
    Where-Object { $_ -match '^| (\w+) → (\w+) \| (.+?) \| (.+?) \|$' } |
    ForEach-Object {
        $m = $_ -match '^| (\w+) → (\w+) \| (.+?) \| (.+?) \|$'
        [PSCustomObject]@{
            From   = $Matches[1]
            To     = $Matches[2]
            Trigger = $Matches[3]
            Deliverable = $Matches[4]
        }
    } | Where-Object { $_.From -eq $from -and $_.To -eq $to }

$handoff.Trigger      # "需要资产面"

$handoff.Deliverable  # "scope + 已知域名/IP"

```

## Specialist Skill Invocation

Once assigned, specialists execute skills through a consistent pattern defined in their [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) row. The CPE role example:

```powershell

# In a CPE session

$skillPath = 'pentest-tools/'   # defined in role-map.md line 11

powershell -File "skills/scripts/run-skill.ps1" -Skill $skillPath -Hint "scan live services"

```

The specialist never bypasses [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) to select skills arbitrarily—ownership is pre-declared, making the audit trail reconstructible from [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) + [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) + executed skill logs.

## Key Contract Files

| File | Purpose |
|------|---------|
| [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) | Role-to-skill matrix, handoff rules, lead protocol |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Master routing contract; specifies PRIMARY skill selection and [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) injection |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Keyword-driven PRIMARY skill selection source of truth |
| [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) | [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) schema; stores `lead_role` and `specialist_roles` |
| `skills/scripts/master-route.ps1` | PowerShell implementation tying routing, role-map, and scope together |

## Summary

- **[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) picks *what* to do**; **[`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) decides *who* does it**
- [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) records the binding contract that both lead and specialists must honor before any ACT
- [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) handoff tables enforce trigger conditions and deliverable requirements for role transitions
- Each specialist role owns specific skill families, preventing arbitrary skill invocation
- The complete audit trail requires only three files: [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md), and executed skill logs

## Frequently Asked Questions

### What happens if [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) and [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) disagree on skill selection?

They do not conflict—[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) selects the PRIMARY skill at case initiation, while [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) assigns which *role* operates within that skill. A `cpe` specialist may run `pentest-tools/` skills even if [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) initially selected `attack-chain/` for the lead, because role-map ownership governs specialist skill invocation.

### Can multiple specialists be active simultaneously?

Yes. The `specialist_roles` array in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) accepts multiple entries. The lead orchestrates parallelism by appending roles and ensuring each specialist's [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) row defines non-overlapping deliverables or explicit coordination requirements.

### How does `master-route.ps1` know which `lead_role` to assign?

Per [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), the master routing contract hardcodes `lead_role: lead` as the default. The lead role is the universal entry point; all other roles enter via explicit handoff from an active role, never through direct master-route assignment.

### What prevents a specialist from editing [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) prematurely?

The [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) specifies that only the `lead` role may edit scope before ACT. This enforcement occurs at the workflow orchestrator level, not within [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) itself—role-map defines *should*, while the orchestrator implements *must* through token possession or similar access control.