I had no tool to plan a process.
So I built one.
I was helping companies plan their SOPs. Internal workflows, API integrations, team handoffs. Every meeting was the same: someone draws boxes on a whiteboard, someone else takes notes in a Google Doc, and by next week nobody remembers what was decided.
The questions kept coming up: Which steps should be automated? Which need a human? How do we know if the new process is better than the old one? Is anyone even following the process we agreed on?
There was no tool for this. Flowchart software draws pretty pictures but they are dead documents — nobody updates them after the first meeting. Project management tools track tasks but not the flow between them. API documentation shows individual endpoints but not the sequence you need to call them in.
Around the same time, I started using AI coding agents. Claude Code, Cursor, Copilot. They would finish a task and I would think: what exactly did it just do? Which files were read? What decisions were made? How is this different from yesterday? The only answer was scrolling through a chat log.
These were the same problem. Whether it is an AI agent running 47 tool calls, a team executing a deployment process, or two companies exchanging data — the fundamental need is identical: define what should happen, record what actually happened, and compare the two.
So I built OSOP. A simple YAML format where every step is a node, every connection is an edge, and every execution leaves a structured record. Not a pretty diagram that nobody maintains. A living document that gets better every time it runs.
Five problems nobody had tools for
You cannot plan a process collaboratively
Your team sits in a meeting to design a workflow. Someone draws on a whiteboard. Someone takes notes. The output is a vague document that is outdated by next week. There is no shared, structured format that everyone — engineers, PMs, executives — can read and edit.
You cannot see who does what
Which steps are fully automated? Which need a human to review? Which are handled by AI? In most organizations, this is tribal knowledge locked in people's heads. New team members have no way to learn except by asking around.
You cannot compare two versions of a process
You changed the deployment process last month. Is it faster now? Did it break something? Nobody knows, because there is no structured record of what the old process actually did versus what the new one does. You have before and after, but no diff.
You cannot improve a process systematically
Everyone agrees SOPs should be continuously improved. But improved based on what? Without execution data — how long each step took, where failures happened, what was retried — improvement is guesswork. You need data, not opinions.
AI agents cannot learn your processes
You want an AI agent to handle part of your workflow. But how does the agent know what the workflow is? Today, you write a prompt explaining everything from scratch. There is no standard format that the agent can read to understand what it should do, what came before, and what comes after.
Three files. One standard.
.sop — The SOP Document
A collection of processes. What a service, a team, or an entire company does. Like a Swagger file for your operations. AI agents read it to know what you offer. Humans read it to understand how things work. Put it at the root of your website, like robots.txt.
.osop — One Process
A single workflow defined as YAML. Each step is a node (api, agent, human, cli, database, git — 16 types). Each connection is an edge (sequential, conditional, parallel, fallback — 13 modes). Security metadata declares risk levels and approval gates. Readable by humans. Executable by machines.
.osoplog — What Actually Happened
An execution record. Every step: when it started, how long it took, what tools were used, what the AI model said, what the human decided, what failed and how it was retried. Structured evidence, not a chat log. The raw material for optimization.
Processes that improve themselves
Define a process as .osop. Execute it. A .osoplog is produced automatically. Now compare: what was supposed to happen versus what actually happened. Where was it slow? Where did it fail? What could run in parallel?
Feed multiple .osoplog files to osop synthesize. AI reads the patterns across all your executions and writes a better .osop. The new version becomes your baseline. Execute again. Record again. Synthesize again.
Each cycle, the process gets faster, cheaper, more reliable. Not because someone had a meeting about it. Because the data told you what to improve, and the tool made the improvement.
Where this is going
AI agents read .sop to know how to use any service
Today, an AI agent arrives at a new website and guesses how to use it — scraping HTML, reading docs, trying APIs. Tomorrow, it reads a .sop file and instantly knows every operation available, the correct sequence of API calls, which steps need human approval. Like robots.txt tells crawlers what to index, .sop tells agents what to do.
Humans and AI collaborate through shared SOPs
The .osop file is the contract between human and machine. Step 1 is automated. Step 2 needs a human review. Step 3 is AI. Step 4 is a human decision. Both sides know exactly what is expected. No ambiguity. The handoff is built into the format.
Companies coordinate through .osop
Onboarding a new partner today takes 6 meetings, 12 emails, and a PDF nobody reads. With OSOP, you share a .sop file. The partner's AI agent reads it and knows exactly how to integrate. The process is executable from day one, not after weeks of back-and-forth.
Every process on earth gets better over time
When every execution is recorded and every record is comparable, improvement is automatic. Hospitals optimize patient intake. Factories optimize assembly lines. Startups optimize deployment pipelines. Not by hiring consultants. By running the loop: execute, record, synthesize, repeat.
How to begin
1. Write one .osop
Pick one process you run regularly. Write it as a .osop file. It takes 5 minutes. Use osop init to scaffold from a template.
2. Run it and record
Execute the workflow. Let the .osoplog capture what happened. Every step, every duration, every decision.
3. Diff and improve
Run it again next week. osop diff the two logs. See what changed. Feed both to osop synthesize. Get a better version. Use it next time.
4. Share it
Put your .sop file where others can find it. Your team reads it to understand how your service works. AI agents read it to use your service correctly. The process is no longer invisible.
What you can build with OSOP
API SOP Doc
Others have API docs showing individual endpoints. You have SOP Doc showing the full call sequence — which APIs, in what order, with what data. Developers see the visual flow. PMs read it without code. AI agents execute it directly.
Example: MediRank: 24 API SOPs for a medical review platform. Every operation from 'Create Clinic' to 'AI Batch Posts' is a browseable visual workflow.
Company Operations Doc
Every department, every process, every handoff between humans and AI — documented as .osop files. New employees read the .sop to understand how the company works. Not a wiki nobody maintains. A living document that improves with every execution.
Example: Onboarding a new partner: share one .sop file instead of scheduling 6 meetings.
SOP Hub — the npm of Workflows
A global registry where AI agents submit SOPs they learned from experience and query best practices from others. 'How do I use Stripe's payment API?' → get the community-optimized .osop sequence. Free for public SOPs. API for AI agents.
Example: AI agent encounters a new service → checks SOP Hub → finds validated .osop → executes correctly on first try.
.sop as robots.txt for AI Agents
Every website puts a .sop file at the root. AI agents visit any site, read .sop, and instantly know what the site can do and how to use it. Like robots.txt tells crawlers what to index. Like sitemap.xml tells search engines what pages exist. .sop tells AI agents what operations exist.
Example: https://example.com/.sop → AI agent discovers 15 operations, reads the .osop for each, executes the one it needs.
User Journey Tracking
Every website visit is a workflow. Human or AI agent — their journey is recorded as .osoplog. Define the ideal journey as .osop. Diff ideal vs actual. Find where users drop off. Synthesize multiple visits into the optimal conversion path.
Example: Visitor: homepage → SOP Doc → Stripe example → copies YAML → leaves. That is a .osoplog. Compare it against the ideal journey. Optimize.
Self-Optimizing AI Agent Workflows
AI coding agents run multi-step tasks every day. Each session produces a .osoplog. Feed 5 logs to osop synthesize — AI finds the patterns and writes an optimized .osop. 85 nodes compressed to 13. The agent gets better at its job by watching itself work.
Example: Real test: 5 Claude Code session logs, 1666 minutes of work → synthesized into a 13-node workflow with parallel exploration, immediate verification, and risk-before-ship patterns.
Core principles
Workflows should be declared before they run — not reconstructed from chat logs after the fact. A .osop file is a contract: here is what should happen, in what order, with what permissions, and with what approval gates.
Every execution produces a .osoplog. Timestamps, tool calls, AI metadata, human decisions, errors. You cannot improve a process you cannot measure.
Definition + record = feedback loop. Compare, find divergence, improve, repeat. The SOP gets better every iteration — not every quarter.
Open source. Open standard.
Everything is Apache 2.0. The spec, the CLI, the SDKs, the editor, the examples, the skills. OSOP is infrastructure, not a product.
The goal is not to build a company on OSOP. The goal is to make OSOP the standard that every company builds on. When processes are as standardized as APIs, the entire world coordinates better.