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

The 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 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. 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

The master-route logic reads 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 entries point to paths like attack-chain/, pentest-tools/, or reverse-engineering skill directories.

Layer 2: Role Assignment via role-map.md

After primary skill selection, master-route.ps1 consults 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 as follows:

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 and skill routing follows a strict sequence:

Step	Component	Action
1	master-route	Parses user hint, scores routing.json, selects PRIMARY skill, outputs lead_role=lead and empty specialist_roles[]
2	case-init / 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 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 handoff table drives transition
5	Specialist	Reads its 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

The 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 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 lookup and scope.md mutation.

Example: Lead to CIE Handoff

When asset discovery triggers a handoff from lead → cie:

1. Lead consults role-map.md handoff table for trigger condition ("需要资产面") and required deliverable ("scope + 已知域名/IP")
2. Lead appends cie to specialist_roles in scope.md:

specialist_roles:
  - cie

3. Lead annotates handoff in timeline.md with evidence package
4. CIE role activates, reads role-map.md line 10 to confirm pentest-tools/ skill family ownership

Handoff Table Parsing (Pseudo-code)

The role-map.md handoff table uses markdown table syntax parseable by 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 row. The CPE role example:

# 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 to select skills arbitrarily—ownership is pre-declared, making the audit trail reconstructible from scope.md + role-map.md + executed skill logs.

Key Contract Files

File	Purpose
skills/ops/role-map.md	Role-to-skill matrix, handoff rules, lead protocol
skills/MASTER-ROUTING.md	Master routing contract; specifies PRIMARY skill selection and scope.md injection
skills/config/routing.json	Keyword-driven PRIMARY skill selection source of truth
skills/ops/scope-contract.md	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 picks what to do; role-map.md decides who does it
• scope.md records the binding contract that both lead and specialists must honor before any ACT
• 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, role-map.md, and executed skill logs

Frequently Asked Questions

What happens if role-map.md and routing.json disagree on skill selection?

They do not conflict—routing.json selects the PRIMARY skill at case initiation, while role-map.md assigns which role operates within that skill. A cpe specialist may run pentest-tools/ skills even if 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 accepts multiple entries. The lead orchestrates parallelism by appending roles and ensuring each specialist's 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, 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 prematurely?

The 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 itself—role-map defines should, while the orchestrator implements must through token possession or similar access control.

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