Understanding the Ops Contract Framework in reverse-skill

The ops contract framework is a declarative orchestration system that drives task execution in the reverse-skill repository by defining standardized contracts under the ops/ directory, which the skill router consumes to validate parameters and materialize reproducible reverse-engineering workflows.

The ops contract framework serves as the declarative backbone for task orchestration in the reverse-skill open-source project. Located in the top-level ops/ directory, these contracts describe what a task should accomplish, how it executes, and what artifacts it produces. By separating workflow definition from implementation logic, the framework enables automated task materialization while maintaining full auditability through version-controlled contract files.

Core Architecture and Design Principles

The framework implements a separation of concerns between workflow definition and execution implementation. Contract files describe what must happen, while underlying scripts in PowerShell, Bash, or Python handle how operations execute. This architectural choice allows the repository to evolve independently—new capabilities require only new contract definitions without modifying the execution engine.

Key architectural characteristics include:

• Standardized Schema: Every contract follows a predictable structure containing metadata, inputs, execution steps, and output definitions, enabling the router to treat all skills uniformly regardless of complexity.

• Runtime Discovery: The skill router automatically discovers new capabilities by scanning the ops/ directory at runtime, making the framework fully extensible through simple file additions.

• Forensic Traceability: Each contract maintains version history through standard git workflows, creating an auditable trail when combined with the timeline/workitems → evidence → finding → path flow documented in docs/ARCHITECTURE.md.

Contract Schema and Structure

Contracts are written in markdown, YAML, or JSON and stored within the ops/ directory hierarchy. According to the project structure outlined in README.md, these files follow a mandatory four-section schema:

Metadata and Inputs

The header section declares authorship, versioning, and categorization tags. The inputs subsection defines required parameters and default values that the skill router validates before execution begins.

Execution Steps and Outputs

The steps section contains an ordered list of actions referencing specific implementation scripts. The outputs section explicitly names the evidence files, logs, and generated reports that constitute successful contract completion, ensuring consistent artifact collection across all engagements.

Skill Router Integration

The skill router defined in skills/MASTER-ROUTING.md and skills/routing.md serves as the execution engine that consumes ops contracts. When a user invokes a skill, the router performs the following operations:

1. Contract Resolution: Locates the matching contract file within the ops/ directory based on the requested skill identifier.

2. Parameter Validation: Verifies that all required inputs defined in the contract schema are present and correctly typed.

3. Workspace Materialization: Creates the case folder structure, populates scope.md, and prepares the execution environment according to the contract's specifications.

4. Step Orchestration: Executes the ordered list of scripts defined in the contract's steps section, capturing outputs to the designated artifact paths.

Security Enforcement and Governance

All contracts inherit the global security policy defined in RULES.md. Before execution begins, the skill router checks that the invoking user possesses the necessary authorization levels defined in these rules. This enforcement layer prevents unauthorized access to sensitive reverse-engineering capabilities and ensures compliance with organizational security standards.

The RULES.md file acts as a gatekeeper, validating that contract parameters do not violate security constraints such as unauthorized network access or unsafe file system operations outside designated working directories.

Practical Implementation Example

Below is a minimal contract definition for static analysis operations, which would be stored as ops/static-analysis.md:

# Static-Analysis Contract

**author:** Zhao Xuya  
**version:** 1.2  
**tags:** reverse-engineering, static-analysis  

## Inputs

- **binary_path** — Path to the target binary (required)  
- **toolset** — List of analysis tools (default: [ "radare2", "ghidra" ])  

## Steps

1. **Create case workspace** – run `scripts/create-case.ps1 -Target $binary_path`  
2. **Run radare2** – `radare2 -AA $binary_path` → `work/<case>/radare2.log`  
3. **Run Ghidra headless** – `ghidra_9.2_support/analyzeHeadless …` → `work/<case>/ghidra/`  
4. **Generate summary** – invoke `scripts/summary.ps1` → `work/<case>/summary.md`  

## Outputs

- `radare2.log` — raw radare2 output  
- `ghidra/` — decompiled binaries and project files  
- `summary.md` — human-readable analysis summary  

To invoke this contract through the skill router, use the following PowerShell command:

# Ask the router to execute the static-analysis contract

Invoke-SkillRouter -Skill "reverse-engineering/static-analysis" -Params @{
    binary_path = "C:\samples\malware.exe"
}

The router parses the contract, validates the parameters against the schema, creates the workspace, executes each defined step, and returns the path to the generated summary.md file.

Summary

• The ops contract framework uses declarative markdown files in the ops/ directory to define reverse-engineering workflows without embedding implementation logic.

• Standardized schemas ensure every contract specifies metadata, inputs, ordered execution steps, and expected outputs uniformly.

• The skill router (skills/MASTER-ROUTING.md and skills/routing.md) discovers, validates, and executes contracts automatically while enforcing parameter requirements.

• Security policies in RULES.md govern all contract execution, ensuring authorization checks occur before any task materialization.

• Extensibility is achieved through runtime directory scanning, allowing new capabilities by simply adding contract files to the ops/ hierarchy.

Frequently Asked Questions

What file formats does the ops contract framework support?

The framework accepts contracts written in markdown, YAML, or JSON formats. While markdown is the primary format documented in the repository, the skill router parses all three formats equally, allowing authors to choose based on their preference for readability versus strict schema validation.

How does the skill router locate specific contracts within the ops directory?

According to skills/routing.md, the router implements a discovery algorithm that scans the ops/ directory at runtime, mapping skill identifiers to file paths based on hierarchical naming conventions. When a user invokes Invoke-SkillRouter -Skill "reverse-engineering/static-analysis", the router resolves this to ops/static-analysis.md or the corresponding subdirectory structure.

Where are security policies defined and enforced for contract execution?

Security policies are centrally defined in RULES.md at the repository root. The skill router references this file during the validation phase—before executing any contract steps—to verify that the invoking user has appropriate authorization and that the requested operation complies with organizational security constraints regarding file system and network access.

Can custom contracts be added without modifying the skill router code?

Yes. The framework supports hot-loading of new capabilities. Adding a new contract file to the ops/ directory makes it immediately available to the skill router without requiring changes to skills/MASTER-ROUTING.md or the routing logic, provided the file adheres to the standardized schema for inputs, steps, and outputs.

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