OpSpec is a general-purpose specification language for operational workflows. Any process that has stages, decision gates, human interaction points, and the capacity to learn and adapt can be expressed as an OpSpec.
A coding agent reads an OpSpec and produces the executor's program — a Temporal workflow, a GitHub Actions pipeline, a Python module, shell scripts, or whatever the target executor requires. The OpSpec is the specification; the produced program is the executable. A human can also follow the same OpSpec manually, step by step.
OpSpec is an independent specification language. It can pair with NLSpec (a specification standard for what to build) for software delivery workflows, but OpSpec stands on its own. A claims processing OpSpec, a patient intake OpSpec, or a supply chain OpSpec has no NLSpec dependency.
| File | Purpose |
|---|---|
OPSPEC-TEMPLATE.md |
The OpSpec language definition. Primitives (STAGE, GATE, BINDING, LEARNING RULE, APPROVAL), section structure, executor requirements, binding types, learning governance, scenario conventions, and worked examples. Start here to write an OpSpec. |
- Read
OPSPEC-TEMPLATE.md— it is both the language reference and a fill-in template - Copy the template and fill in your workflow's stages, gates, bindings, and learning rules
- Hand the completed OpSpec to a coding agent to produce the executor program
STAGE — A phase of work with entry/exit conditions and concrete operations.
GATE — A three-band decision point (PASS / REWORK / FAIL) between stages.
BINDING — An artifact template (prompt, rule, tool config) that the coding agent produces as part of the executor program.
LEARNING RULE — Governed self-modification: the workflow observes patterns, proposes changes to itself, and submits them for approval within declared boundaries.
APPROVAL — A human interaction point where the executor pauses and waits.
Executor — The system that runs the produced program. Can be a workflow engine (Temporal, Airflow), a CI/CD pipeline (GitHub Actions, Jenkins), a controller, or a shell runner.
OpSpec applies to any operational workflow:
- Software delivery pipelines (code → build → test → deploy → monitor)
- Insurance claims processing (intake → verify → assess → adjudicate → pay)
- Loan origination (application → underwrite → approve → fund → service)
- Patient intake and triage (register → assess → route → treat → follow-up)
- Supply chain orchestration (order → source → manufacture → ship → deliver)
- Content moderation (receive → classify → review → act → appeal)
- Customer onboarding (sign-up → verify → provision → train → activate)
-
Read
OPSPEC-TEMPLATE.md— every section has syntax examples and conventions. -
Start with the Abstract — one paragraph describing what the workflow does, its domain, inputs, outputs, and primary approval gates.
-
Define your STAGEs and GATEs — map out the workflow as a sequence of concrete stages with decision gates between them.
-
Add BINDINGs — for each stage that needs artifacts (prompts, rules, tool configs), write a BINDING template with runtime variables.
-
Declare APPROVALs — identify where humans enter the loop. Every APPROVAL has a channel, SLA, and escalation path.
-
Set LEARNING BOUNDARIES — declare what can never change (IMMUTABLE), what needs human approval to change (MUTABLE_WITH_APPROVAL), and what can self-tune (AUTO_TUNABLE).
-
Write SCENARIOS — validate the workflow itself: happy path, rework loops, failure escalation, approval flows, rollback, and learning.
Before finalizing, apply the litmus test: could a human follow this OpSpec step by step and produce the correct outcome? If any stage says "figure out the right approach" or any gate says "use good judgment" without concrete criteria, the OpSpec is incomplete. Fix the spec, not the coding agent.
Version: 0.5.0 | Author: Divyendu Deepak Singh | Date: 2026-02-27