Canonical Execution Flow for Reverse-Skill Tasks: A Complete Technical Guide

The reverse-skill framework processes security and reverse-engineering requests through an 8-stage deterministic pipeline that handles routing, dependency bootstrapping, execution, and automated learning.

The reverse-skill repository (zhaoxuya520/reverse-skill) implements a structured execution engine designed specifically for cybersecurity workflows. Understanding the canonical execution flow is essential for extending the framework, debugging task failures, or integrating custom sub-skills. This guide traces the complete pipeline from user input to final report generation, referencing the actual implementation in docs/ARCHITECTURE.md and the master routing dispatcher.

Step-by-Step Execution Pipeline

The framework follows the 系统架构图 (system architecture diagram) documented in docs/ARCHITECTURE.md, processing each task through eight distinct phases.

1. User Input & Keyword Detection

The pipeline initiates when the AI client receives a task description. A keyword matcher validates whether the request matches defined security or reverse-engineering triggers. This detection layer determines whether the reverse-skill engine should handle the request or pass it to standard processing queues.

2. Routing Lookup via Master Entry Point

Upon trigger confirmation, the engine reads skills/SKILL.md (the master entry point) and consults skills/routing.md (the routing matrix) to resolve the appropriate sub-skill. This mapping connects specific task categories—such as APK analysis or Active Directory enumeration—to their dedicated implementation modules.

3. Journal and Tool-Index Verification

Before executing any code, the system queries the field-journal/ directory for historical task data and lessons learned. Simultaneously, it loads skills/tool-index.md to verify that all required binaries and dependencies are present on the host system. This dual-check prevents mid-task failures due to missing tooling.

4. Automatic Bootstrap and Installation

If tool-index.md indicates missing dependencies, the framework automatically executes platform-specific bootstrap scripts. On Windows, skills/scripts/bootstrap-reverse.ps1 runs with elevated privileges; on Kali Linux, kali/scripts/bootstrap-reverse.sh executes. Successful installation adds tools to the system PATH and updates the tool-index; failure triggers manual guidance protocols rather than crashing the workflow.

5. Sub-Skill Execution Loop

With all dependencies resolved, the selected sub-skill invokes its internal workflow logic. Complex operations—such as iterative pentesting loops or deep APK analysis—run internally until the sub-skill reports the TaskDone state. The parent framework monitors this status but does not interfere with internal iteration logic.

6. Case Review and Report Generation

Post-execution, the case-review module validates the evidence graph for completeness and accuracy. The documentation generator then produces the final report and associated diagrams, converting raw technical findings into structured, human-readable deliverables suitable for client presentation.

7. Knowledge Persistence and Index Updates

The system writes outcomes, tool outputs, and lessons learned back to the field-journal/ directory. It simultaneously refreshes both the routing matrix and skills/tool-index.md to reflect any environmental changes or newly installed capabilities. This 自动进化机制 (auto-evolution mechanism) ensures that experience accumulates across sessions.

8. Final Output Delivery

The AI client delivers the completed report and any generated artifacts to the user, concluding the transaction. The framework then returns to an idle state, ready to process the next task through the identical pipeline.

Routing and Dispatch Mechanism

The routing layer operates as the framework's central nervous system. The skills/SKILL.md file serves as the single entry point for all reverse-skill tasks, while skills/routing.md maintains the mapping between task hints and executable sub-skills. This separation of concerns allows developers to add new capabilities by registering them in the routing matrix without modifying the core dispatch logic.

Bootstrap and Dependency Resolution

The bootstrap system ensures zero-configuration deployment across supported platforms. The framework detects the host operating system and invokes the appropriate script:

• Windows: skills/scripts/bootstrap-reverse.ps1
• Kali Linux: kali/scripts/bootstrap-reverse.sh

These scripts handle package installation, PATH configuration, and initial environment validation. They write their status to skills/tool-index.md, creating a persistent record of available capabilities that persists across sessions.

Platform-Specific Invocation Examples

Trigger the canonical execution flow using the master routing scripts with a descriptive hint:

Windows (PowerShell):

# Invoke the master routing script with a hint describing the task

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "Analyze suspicious APK"

Linux / macOS / Kali (Bash):

# Invoke the master routing script with a hint describing the task

bash skills/scripts/master-route.sh --hint "Enumerate AD security misconfigurations"

These commands initiate the full eight-step pipeline: detection, routing, tool verification, automatic bootstrapping if needed, sub-skill execution, and final report generation.

Key Files in the Execution Flow

Understanding the canonical flow requires familiarity with these specific files:

• skills/SKILL.md — Master entry point and routing dispatcher
• skills/routing.md — Routing matrix mapping hints to sub-skills
• skills/tool-index.md — Generated manifest of available tools
• field-journal/ — Directory containing historical task data and lessons learned
• skills/scripts/bootstrap-reverse.ps1 — Windows dependency installer
• kali/scripts/bootstrap-reverse.sh — Kali Linux dependency installer
• docs/ARCHITECTURE.md — Visual flow documentation and system architecture diagram
• RULES.md and kali/RULES-kali.md — Platform-specific gatekeeping rules

Summary

• The reverse-skill framework implements an 8-stage canonical execution flow for security tasks.
• Execution begins with keyword detection and routes through skills/SKILL.md and skills/routing.md.
• The field-journal/ and skills/tool-index.md provide state awareness and prevent redundant tool installations.
• Missing dependencies trigger automatic bootstrapping via bootstrap-reverse.ps1 or bootstrap-reverse.sh.
• Sub-skills execute iteratively until reporting TaskDone, followed by automated case review and report generation.
• The 自动进化机制 (auto-evolution mechanism) persists knowledge to improve future task performance.

Frequently Asked Questions

What triggers the reverse-skill execution flow?

The flow triggers when a keyword matcher detects security or reverse-engineering triggers in the user's task description. This validation step ensures that only appropriate requests enter the specialized pipeline defined in docs/ARCHITECTURE.md.

How does reverse-skill handle missing dependencies?

The framework automatically executes platform-specific bootstrap scripts—skills/scripts/bootstrap-reverse.ps1 for Windows or kali/scripts/bootstrap-reverse.sh for Kali—to install missing tools. Upon successful installation, the script updates the system PATH and regenerates skills/tool-index.md. If bootstrapping fails, the system falls back to manual guidance rather than terminating the session.

What is the field-journal and why is it important?

The field-journal/ directory serves as the framework's persistent memory, storing historical task outcomes, evidence graphs, and lessons learned. This repository enables the auto-evolution mechanism to reuse previous experience when handling similar future tasks, effectively allowing the system to learn from past operations without manual reconfiguration.

Where is the canonical execution flow documented in the source code?

The complete execution flow is visualized in the system architecture diagram (系统架构图) within docs/ARCHITECTURE.md. This document maps the eight stages from input detection through final output, including the specific checkpoint logic for journal verification and bootstrap decision trees.

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