# Understanding `skills/ops/role-map.md`: The Security Workflow Policy Engine in zhaoxuya520/reverse-skill

> Discover how skills/ops/role-map.md orchestrates security operations in zhaoxuya520/reverse-skill by mapping roles to skills and enforcing workflow policies for disciplined phase transitions.

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

---

**[`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) serves as the policy layer that orchestrates security operations by mapping expert roles to their required skills, enforcing hand-off protocols, and ensuring disciplined phase transitions during penetration testing engagements.**

In the `zhaoxuya520/reverse-skill` framework, this file functions as the central authority for multi-agent security workflows. Whether deployed across a distributed Z3r0-style system or within a single conversation, [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) guarantees that reconnaissance, exploitation, reverse engineering, and reporting phases execute with proper scoping, evidence chain integrity, and controlled responsibility transfers.

## Core Architecture of the Role Mapping System

The [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) file implements a structured governance model that separates **who performs work** from **what work is performed**. This separation enables modular, auditable security operations.

### The Central Mapping Table

Lines 5–18 of [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) establish the foundational role definitions. Each entry specifies:

- **Role code** – Short identifier (e.g., `lead`, `cie`, `cpe`, `cre`)
- **Human-readable name** – Descriptive title for documentation
- **Responsibilities** – Bounded scope of authority
- **Primary skill packages** – Executable capabilities the role may invoke

This mapping prevents capability sprawl. A **Cyber Intelligence Expert (`cie`)** cannot arbitrarily launch exploitation tools; their approved skills are constrained to reconnaissance and OSINT functions as defined in the table.

### The Lead Role's Mandatory Protocol

The `lead` role operates under strict operational requirements defined in lines 19–27. This single role holds four exclusive authorities:

1. **PRIMARY routing emission** – Declares the `master-route` that governs engagement flow
2. **Scope contract creation** – Authors the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file that legally and operationally bounds all subsequent activity
3. **Specialist role selection** – Determines which expert roles (e.g., `cie`, `cpe`, `cre`) participate in the engagement
4. **Timeline updates** – Records phase completions and triggers downstream dependencies

No other role may perform these functions. This centralization prevents scope creep and establishes clear accountability.

## Hand-Off Rules and Phase Transitions

Lines 29–38 of [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) define a **hand-off matrix** that governs when responsibility shifts between roles. Each transition specifies:

- **Trigger conditions** – Objective criteria for transfer (e.g., "domain enumeration complete")
- **Required artefacts** – Data packages that must accompany the transition
- **Validation checkpoints** – Verification steps before acceptance

A canonical example: `lead → cie` hands over the signed [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contract and any pre-discovered domain seeds. The `cie` role cannot begin work without these artefacts, and the `lead` cannot reclaim control until the `cie` delivers their findings package.

This structure mirrors formal change-control processes in security operations centers, adapted for agile penetration testing.

## Single-Agent Workflow Adaptation

Lines 40–52 address deployment flexibility. Not every environment supports multi-agent orchestration. The role map therefore supports **single-agent discipline** through explicit role tagging:

```text
[lead] PHASE:INITIAL target=example.com scope=recon-only
[cie] DISCOVERED: subdomains=[a.example.com, b.example.com]
[cpe] VERIFIED: a.example.com:22/open, a.example.com:443/open
[cre] ANALYZED: binary from /uploads/sample.exe -> custom_pack_header
[doc] GENERATED: findings.md section 3.2

```

Each output prefix enforces the same mental model as distributed agents: bounded authority, clear hand-offs, and artefact production. The `lead` tag at conversation start establishes scope; other tags signal phase entry and exit.

## Integration with `master-route`

Lines 54–58 clarify the relationship between [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) and `skills/scripts/master-route.ps1`:

| Component | Determines | Implementation |
|-----------|-----------|----------------|
| **[`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)** | **Who** is responsible | Role codes and authority boundaries |
| **`master-route.ps1`** | **What** skill executes | PRIMARY routing logic and skill dispatch |

The role map answers: "Which role currently owns this phase?" The master route answers: "Given that role, which specific skill package runs now?"

This decoupling allows the same role map to drive different technical implementations—PowerShell wrappers, Python orchestrators, or container-native schedulers—without policy changes.

## Practical Implementation Examples

### Selecting a Role and Dispatching Its Skill Package

When the `lead` determines that reconnaissance should proceed, they invoke the `cie` role through the master route:

```powershell

# Example: the lead decides the next phase is reconnaissance (cie)

$role = "cie"
$skill = "pentest-tools"

# Dispatch the skill via the master-route script

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "$role $skill"

```

The `-Hint` parameter encodes both role identity and skill selection, which `master-route.ps1` validates against the mapping table before execution.

### Creating the Scope Contract

The `lead` materializes their planning authority by generating `work/<case>/scope.md`:

```powershell

# Lead writes scope.md based on the role-map contract

$out = @"
lead_role=lead
specialist_roles=[cie,cpe,cre]
handoff_conditions=...
"@
Set-Content -Path work/$(Get-Date -Format "yyyyMMdd")/scope.md -Value $out

```

This file becomes the binding operational contract. Specialist roles reference it to confirm their authority boundaries before acting.

### Executing a Role Hand-Off

When the **Cyber Physical Expert (`cpe`)** discovers malware requiring reverse engineering, they trigger the `cpe → cre` transition:

```powershell

# CPE finishes scanning and hands off a sample for reverse engineering

$handoff = @{
    from = "cpe"
    to   = "cre"
    trigger = "need reverse verification"
    deliverables = "sample_path=./samples/malware.bin"
}

# Serialize to JSON for the next role to consume

$handoff | ConvertTo-Json | Out-File -Encoding utf8 work/$(Get-Date -Format "yyyyMMdd")/hand-off.json

```

The `cre` role validates `trigger` and `deliverables` against the hand-off matrix before accepting responsibility.

### Complete Single-Agent Session

A full engagement executed within one conversation demonstrates role discipline without infrastructure overhead:

```text
[lead] Planning: target = example.com, scope = initial recon
[cie] Discovered subdomains: a.example.com, b.example.com
[cpe] Verified service on a.example.com: HTTP 200, SSH open
[cre] Analyzed binary from a.example.com – identified custom crypto
[doc] Generated report sections for each phase

```

Each transition represents an implicit hand-off. The `lead` could interject at any point to redirect, but normal flow follows the map-defined sequence.

## Key Workflow Files

| File | Function | Source Path |
|------|----------|-------------|
| [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) | Role definitions, hand-off matrix, lead protocol | [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) |
| `skills/scripts/master-route.ps1` | Skill dispatch based on current role | `skills/scripts/master-route.ps1` |
| [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) | Template for scope contract generation | [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) |
| `work/<case>/scope.md` | Runtime scope contract (lead-generated) | Runtime artefact |
| `work/<case>/timeline.md` | Phase tracking and audit log | Runtime artefact |
| `work/<case>/hand-off.json` | Inter-role artefact transfers | Runtime artefact |

## Summary

- **[`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)** operates as the **policy authority** for security engagement orchestration in `zhaoxuya520/reverse-skill`
- **Role codes** (`lead`, `cie`, `cpe`, `cre`) bind expert identities to **bounded skill packages**, preventing unauthorized capability usage
- **Lead protocol** enforces centralized scope control, routing decisions, and timeline management
- **Hand-off matrix** guarantees controlled phase transitions with mandatory artefact exchange
- **Single-agent mode** extends role discipline to conversations without multi-agent infrastructure
- **`master-route.ps1`** executes the technical dispatch while [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) governs authorization logic

## Frequently Asked Questions

### What happens if a role tries to invoke a skill not mapped in [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)?

The `master-route.ps1` dispatcher validates all skill requests against the mapping table in [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md). Unauthorized requests are rejected with an error logged to the timeline. This enforcement prevents, for example, a `cie` role from attempting exploitation activities reserved for `cpe` or `cre` roles.

### Can the `lead` role be assigned to multiple individuals simultaneously?

The protocol defined in lines 19–27 specifies singleton authority for the `lead` role. Only one `lead` may hold PRIMARY routing control at any time. During shift changes, an explicit hand-off must update the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contract with new lead identity and timestamp, preserving audit continuity.

### How does [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) handle engagements that don't require all specialist roles?

The `lead` selects participating specialist roles during initial planning (lines 22–23). Unselected roles are omitted from the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contract and excluded from the hand-off matrix for that engagement. The mapping table remains complete for future engagements, but runtime instantiation is subset-based.

### What validation ensures hand-off artefacts are complete before phase transition?

The hand-off matrix (lines 29–38) specifies required deliverables for each transition. The receiving role must confirm artefact presence and checksum validity before acknowledging acceptance. Failed validations trigger escalation back to the `lead` for arbitration, with all attempts recorded in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md).