# Understanding the Ops Contract Framework in reverse-skill

> Discover the ops contract framework in reverse-skill. Learn how this declarative system orchestrates tasks and ensures reproducible reverse-engineering workflows via standardized contracts.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-06

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) and [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/static-analysis.md):

```markdown

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

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) and [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)) discovers, validates, and executes contracts automatically while enforcing parameter requirements.

- **Security policies** in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) or the routing logic, provided the file adheres to the standardized schema for inputs, steps, and outputs.