Getting started

Three file formats, one closed loop

OSOP uses three formats that work together:

Quick start

osop_version: "2.0"
id: "my-first-workflow"
name: "Hello OSOP"
description: "A simple two-step workflow."
tags: [tutorial]

nodes:
  - id: "greet"
    type: "agent"
    name: "Generate Greeting"
    purpose: "AI generates a personalized greeting."
    runtime:
      provider: anthropic
      model: claude-sonnet-4-20250514

  - id: "review"
    type: "human"
    name: "Human Review"
    purpose: "Human reviews the AI output."

edges:
  - from: "greet"
    to: "review"
    mode: "sequential"

$ osop validate my-workflow.osop.yaml
✓ Valid OSOP workflow: "Hello OSOP"
  2 nodes, 1 edge, 0 warnings

$ osop run my-workflow.osop.yaml --dry-run
  → [agent] greet: dry_run
  → [human] review: dry_run
  COMPLETED — 0 executed, 0 skipped

$ osop run my-workflow.osop.yaml
  → [agent] greet: completed ($0.0023)
  → [human] review: skipped (interactive mode off)
  COMPLETED — 1 executed, 1 skipped — $0.0023

The .osop format

A .osop file is a YAML document that defines a workflow as a directed acyclic graph (DAG). It has three main sections:

Metadata

Top-level fields: osop_version, id, name, description, version, tags.

Nodes (16 types)

Edges (13 modes)

Edges connect nodes and define execution flow:

The .osoplog format

After executing a workflow, a .osoplog file records what actually happened. It is an immutable execution record containing:

The .sop format (SOP Document)

A .sop file groups multiple .osop workflows into a single browsable document. Think of it as a folder or table of contents for your workflows.

Structure

Top-level: sop_version, id, name, sections. Each section contains name, description, and workflow references (ref paths to .osop files).

sop_version: "1.0"
id: "stripe-api-docs"
name: "Stripe API — Complete SOP Documentation"
author: "Engineering Team"

sections:
  - name: "Payment Flows"
    description: "Core payment processing workflows."
    workflows:
      - ref: "./stripe-payment-flow.osop.yaml"
        title: "Create Payment"
      - ref: "./stripe-refund-flow.osop.yaml"
        title: "Process Refund"

  - name: "Customer Management"
    workflows:
      - ref: "./stripe-create-customer.osop.yaml"
        title: "Create Customer"

Rendering

A .sop file renders into a standalone SOP Doc HTML with collapsible sections, table of contents, and Visual/YAML tabs for each workflow.

Use cases

Synthesize: .osoplog → optimized .osop

Feed multiple execution records to AI. It analyzes patterns across runs and produces an optimized workflow.

$ osop synthesize run1.osoplog.yaml run2.osoplog.yaml run3.osoplog.yaml \
    --goal "reduce cost and parallelize where possible" \
    -o optimized.osop.yaml

  Analyzing 3 execution records...
  Total nodes: 24 | Avg duration: 142s | Total cost: $0.47
  ✓ Synthesized: optimized.osop.yaml
    - 3 steps parallelized (was sequential)
    - 1 retry policy added (node "deploy" failed 2/3 runs)
    - Estimated improvement: -38% duration, -22% cost

CLI commands

# Scaffold a new workflow
$ osop init --name "My Pipeline" --type agent

# Validate against JSON Schema
$ osop validate workflow.osop.yaml

# Dry-run (preview without side effects)
$ osop run workflow.osop.yaml --dry-run

# Real execution with LLM calls
$ osop run workflow.osop.yaml

# Execute with shell commands (requires explicit opt-in)
$ osop run workflow.osop.yaml --allow-exec

# Generate execution log
$ osop run workflow.osop.yaml --log output.osoplog.yaml

# Generate HTML report
$ osop report workflow.osop.yaml output.osoplog.yaml -o report.html

Integrate with your AI tool

OSOP works with 18 AI coding agents. The universal installer auto-detects which tools you have:

$ git clone https://github.com/Archie0125/osop-agent-rules.git
$ cd osop-agent-rules
$ ./install.sh       # auto-detect Cursor, Windsurf, Cline, etc.
$ ./install.sh --all # install for all 18 platforms

See the full list at github.com/Archie0125/osop-agent-rules.