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

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 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 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 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 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 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 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:

[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 and skills/scripts/master-route.ps1:

Component	Determines	Implementation
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:

# 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:

# 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:

# 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:

[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	Role definitions, hand-off matrix, lead protocol	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	Template for scope contract generation	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 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 governs authorization logic

Frequently Asked Questions

What happens if a role tries to invoke a skill not mapped in role-map.md?

The master-route.ps1 dispatcher validates all skill requests against the mapping table in 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 contract with new lead identity and timestamp, preserving audit continuity.

How does 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 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.

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