OSOP is not a single tool — it is an ecosystem of 11 repositories that work together to make AI agent workflows portable, auditable, and optimizable. This post explains how the pieces fit together and why each one exists.
The Architecture
Every protocol needs three things to succeed: a clean specification, tools that make it useful, and an ecosystem that makes it ubiquitous. OSOP has all three.
┌─────────────────────────────────────────────────────┐ │ OSOP Ecosystem │ ├──────────────┬──────────────┬────────────────────────┤ │ Spec Layer │ Tool Layer │ Ecosystem Layer │ │ │ │ │ │ osop-spec │ osop (CLI) │ osop-agent-rules (18) │ │ (protocol) │ osop-sdk-js │ osop-openclaw-skill │ │ │ osop-sdk-py │ osop-interop │ │ │ osop-mcp │ osop-examples (39+) │ │ │ osop-editor │ osop-website │ │ │ osop-vscode │ │ └──────────────┴──────────────┴────────────────────────┘
Layer 1: The Specification
osop-spec is the protocol definition. It specifies the .osop and .osoplog YAML formats, including 16 node types, 13 edge modes, security metadata, and conformance levels (L1-L4). The spec is JSON Schema validated — every .osop file can be checked against a machine-readable schema.
The spec also defines the expression language (CEL) for conditional edges, the agent runtime binding (how agents should execute workflows), and the execution report format.
Layer 2: Developer Tools
Python CLI (osop)
The command-line tool that validates, renders, runs, and tests workflows. pip install osop gives you everything needed to work with OSOP from the terminal. It is the workhorse of the ecosystem.
JavaScript SDK (osop-sdk-js)
TypeScript-first library for parsing, validating, and manipulating .osop files in Node.js and browsers. Used by the visual editor and any web-based OSOP tool.
Python SDK (osop-sdk-py)
Sync and async Python clients for programmatic workflow creation, validation, and execution. Used by the MCP server and any Python application that needs to work with OSOP.
MCP Server (osop-mcp)
Exposes 9 OSOP tools via the Model Context Protocol. This is the adoption accelerator — once installed, any MCP-compatible AI agent (Copilot, Cursor, Claude) can validate, run, render, optimize, and convert OSOP workflows without any custom integration. MCP deep dive
Visual Editor (osop-editor)
Interactive web-based editor for authoring and visualizing workflows. Built with React 19 and ReactFlow. Features 5 visualization modes (graph, story, role, agent, code), built-in risk analysis, execution replay, and AI-powered workflow generation. osop-editor.vercel.app.
VS Code Extension (osop-vscode)
Syntax highlighting, schema validation, autocomplete, hover docs, and 9 code snippets for .osop files. Developers write workflows in their IDE with full IntelliSense support.
Layer 3: Ecosystem Expansion
Agent Rules (osop-agent-rules)
Drop-in instruction files for 18 AI coding platforms. One CORE-INSTRUCTIONS.md with platform-specific wrappers for Cursor, Codex, Windsurf, Aider, Cline, Roo Code, Devin, Obsidian, Zed, Amp, Trae, PearAI, Sweep AI, and SWE-agent. Universal installer auto-detects your tools.
OpenClaw Skill (osop-openclaw-skill)
5 skills published on ClawHub — OpenClaw's community marketplace. Session logging, HTML reports, security review, workflow optimization, and the core OSOP skill. 13,000+ skills in the ecosystem.
Format Converters (osop-interop)
Bidirectional converters between OSOP and 6 external formats: GitHub Actions, BPMN, Airflow, Temporal, Postman, and OpenAPI. Eliminates the cold-start problem — import your existing workflows and start using OSOP immediately.
Examples (osop-examples)
39+ real-world workflow templates across 9 domains: DevOps, testing, infrastructure, AI agents, data, API, mobile, platform, and business. Each example is a complete, valid .osop file ready to run.
How It All Connects
A typical OSOP workflow looks like this:
- Author a .osop file in VS Code (with autocomplete) or the visual editor
- Validate with the CLI (osop validate) or MCP server
- Execute with any AI agent — the agent rules teach it to produce .osoplog files
- Analyze the execution in the visual editor — risk overlay, step-by-step replay
- Optimize by comparing .osop against .osoplog — find what to improve
- Export to GitHub Actions, Airflow, or BPMN if needed — OSOP interoperates
Open Source, Modular, Composable
Every repository is Apache 2.0. Each component works independently — you can use the CLI without the editor, the SDK without the MCP server, the agent rules without the CLI. But they are designed to work together, and the whole is greater than the sum of its parts.
The ecosystem is the moat. When AI agents read and write OSOP, when tools validate and render it, when platforms import and export it — the protocol becomes infrastructure. And infrastructure becomes standard.