# How role-map.md and timeline/workitems Coordinate Multi-Phase Security Assessments

> Learn how role-map.md and timeline workitems coordinate multi phase security assessments. Define roles track tasks and ensure smooth transitions for effective security evaluations.

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

---

**[`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)** defines specialist roles and hand-off protocols, while **[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)** and **[`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md)** provide the chronological and task-level tracking that ensures each phase of a security assessment transitions cleanly from one specialist to the next.

The `zhaoxuya520/reverse-skill` repository implements a structured governance model for security engagements that uses Markdown-based artifacts to enforce accountability across complex, multi-phase workflows. By combining role definitions with immutable audit trails and task tracking, the system ensures that no phase begins without proper authorization and that every action leaves a verifiable evidence trail.

## Understanding the Role Map Foundation

### Specialist Roles and the Lead Mandatory Protocol

At the heart of the coordination system sits [[`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md), which defines the specialist roster—including **lead**, **cie** (Cyber Intelligence Expert), **cpe** (Cybersecurity Protection Expert), and **cre** (Cybersecurity Reverse Engineer)—and the "Lead 强制协议" (Lead Mandatory Protocol) documented in lines 21-26. This protocol dictates that the **lead** role must initialize the engagement scope and continuously record the current specialist roster alongside hand-off conditions.

The role map functions as the authoritative source for **who** is authorized to act during each assessment phase. When the lead initiates a hand-off, they consult this file to determine the next valid role in the chain, ensuring that transitions occur only between properly designated specialists.

## Timeline.md as the Immutable Audit Trail

### Entry Structure and Hand-off Records

The [[`examples/ctf-demo/timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/examples/ctf-demo/timeline.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/examples/ctf-demo/timeline.md) file serves as an append-only chronological ledger that records **when** each phase occurred and **what** actions were taken. Each entry follows a strict structure including timestamp, role, activity, result summary, artefacts, evidence IDs, and the next step.

When a phase completes, the lead appends a new entry that documents the transition. Consider the hand-off from `cie` to `cpe` for vulnerability validation:

```text

# timeline entry (append to examples/ctf-demo/timeline.md)

2026-08-02T02:00:00.0000000+08:00 | cpe | validate
- action: run vulnerability scans on discovered assets
- command_or_ref: tools/nuclei -target assets.txt
- result_summary: 12 high‑severity findings, 3 critical
- artifacts: [scan-report.json]
- evidence_ids: [E-004]
- next: handoff to cre for reverse‑engineered payloads

```

This format creates an immutable audit trail where every timestamp, role change, and evidence reference (such as `E-004`) is permanently recorded, preventing retroactive alterations to the assessment history.

## Workitems.md for Task-Level Accountability

### Tabular Task Tracking

While the timeline captures the chronological narrative, [[`examples/ctf-demo/workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/examples/ctf-demo/workitems.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/examples/ctf-demo/workitems.md) manages the granular **what** of each assignment through a tabular backlog. The table structure (lines 3-10) tracks concrete tasks using fields: ID, title, role, target, surface, status, evidence, and notes.

When the lead triggers a hand-off, they create a corresponding work item for the receiving specialist:

```text

# work item (append to examples/ctf-demo/workitems.md)

| WI-006 | Vulnerability scanning | cpe | assets.txt | service | in‑progress | E-004 | nuclei scans |

```

This links the abstract timeline entry to a concrete, trackable task (`WI-006`) assigned to a specific role (`cpe`) and tied to specific evidence IDs.

### The Coverage Verification Checklist

The workitems artifact includes a Coverage checklist (lines 11-18) that verifies each phase's deliverables before the lead authorizes the next transition. This ensures that vulnerability scans, asset discoveries, or reverse engineering tasks achieve complete coverage before the hand-off protocol releases the next work item.

## Practical Coordination Workflow

### Lead-Driven Phase Transitions

According to [[`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), the coordination follows a tight loop: the lead checks [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md) to identify the next specialist, updates [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) with the hand-off entry, and creates or advances entries in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md). This guarantees that every multi-phase assessment proceeds in a controlled, auditable fashion without skipping scope validation.

The following PowerShell illustration shows how a lead might automate this hand-off logic between the `cie` and `cpe` roles:

```powershell

# skills/scripts/lead-handoff.ps1 (illustrative)

$roleMap = Get-Content ../../skills/ops/role-map.md
if ($currentPhase -eq 'cie' -and (Test-Path assets.txt)) {
    # create next work item

    Add-WorkItem -Id 'WI-006' -Title 'Vulnerability scanning' -Role 'cpe' -Target 'assets.txt'
    # append timeline entry

    Add-TimelineEntry -Timestamp (Get-Date) -Role 'cpe' -Stage 'validate' `
        -Action 'run vulnerability scans' -Evidence 'E-004'
}

```

In this workflow, the lead enforces that the `cpe` role receives authorization only after the `cie` phase produces the required [`assets.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/assets.txt) file, with the `E-004` evidence ID linking both the timeline entry and work item.

## Summary

- **[`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)** establishes the **who** by defining specialist roles and the Lead Mandatory Protocol that governs hand-offs.
- **[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md)** establishes the **when** through append-only entries that immortalize phase transitions with timestamps and evidence IDs.
- **[`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md)** establishes the **what** through a structured table that tracks task status, targets, and verification checklists.
- The **lead** role orchestrates the coordination by consulting the role map before generating timeline entries and work items, ensuring no unauthorized phase transitions occur.

## Frequently Asked Questions

### What is the Lead 强制协议 in role-map.md?

The Lead Mandatory Protocol (lines 21-26 of [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)) requires the **lead** role to initialize the engagement scope and maintain a current roster of assigned specialists. This protocol mandates that the lead document hand-off conditions explicitly, preventing unauthorized specialists from entering the workflow and ensuring that every phase transition receives proper authorization.

### How does timeline.md prevent unauthorized phase transitions?

[`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) functions as an append-only ledger where each entry includes the role, timestamp, and evidence IDs. Because the file is append-only and entries link to specific work items and evidence, retroactive insertion of unauthorized phases would break the chronological chain and evidence correlation. The lead creates entries only after verifying the previous phase's completion against the Coverage checklist in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md).

### What is the relationship between evidence IDs and work items?

Evidence IDs (formatted as `E-*`, such as `E-004`) serve as the correlation key between the chronological narrative in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and the task tracking in [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md). When the lead creates a work item like `WI-006`, they populate the evidence field with the same ID recorded in the timeline entry, creating an auditable thread that connects the action (timeline) to the assigned task (work item) and the underlying data.

### Where are the coordination rules for these artifacts documented?

The governance rules for maintaining [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) are specified in [[`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), while concrete examples appear in the [`examples/ctf-demo/`](https://github.com/zhaoxuya520/reverse-skill/blob/main/examples/ctf-demo/) directory. These files establish the schema for entries, the Coverage checklist verification process (lines 11-18), and the mandatory fields required for valid hand-off records.