v0.2 is in progress (additive, pre-release). See theconformance guide — profiles, artifact roles, and the evidence event model — rendered from the canonical spec.

OperatorSpec v0.1

Status: Draft
Kind: Open standard seed
Canonical format: YAML
Schema: schemas/operator-workflow.schema.json

Definition

An operator-led AI workflow is structured work where a capable human operator actively steers one or more expert AI agent workers through a task the operator could not reliably complete alone.

The operator is not merely an approver. The operator drives the workflow: observing, questioning, choosing, recording, escalating, and deciding when the work is done enough to hand over.

Where OperatorSpec sits

OperatorSpec defines the missing operator layer of agentic work. It complements the rest of the agent stack rather than competing with it:

• MCP connects models to tools.
• A2A connects agents to agents.
• OperatorSpec connects human operators to agentic workflows.

It is not “the first human-in-the-loop protocol” and not a replacement for MCP, A2A, AGENTS.md, LangGraph, Temporal, BPMN, or RPA. See docs/prior-art.md.

The operator lifecycle

Across a workflow the operator performs a repeatable cycle of active control:

brief → supervise → interrupt → approve → resume → audit → hand off

The operator is the driver, not a passive approval gate. They brief the agent on intent and boundaries, supervise the work, interrupt or redirect when it drifts, approve actions that cross a defined boundary, resume after a pause or recovery, audit what happened against the evidence, and hand off the workflow with full context.

See docs/glossary.md for definitions and rfcs/0005-operator-lifecycle.md for the current proposal to keep lifecycle verbs as normative vocabulary rather than mandatory schema fields.

Non-goals

OperatorSpec does not define an agent runtime, model protocol, provider API, or autonomous execution framework. It can be used with Goose, Claude Code, Cursor, custom agents, MCP servers, browser tools, shell tools, or future runtimes.

OperatorSpec does not claim that a non-expert operator replaces a licensed domain expert. Workflows must define escalation rules for regulated, safety-critical, financial, legal, medical, or otherwise high-risk decisions.

Required contracts

1. Operator Contract

The Operator Contract defines the human role.

It MUST specify:

• the operator role
• required operator capabilities (the judgment the operator must bring)
• knowledge explicitly not required (the operator is non-expert by design)
• decisions the operator may make
• actions the operator is allowed to take, and the approval boundaries around them
• decisions the operator must escalate
• stopping conditions — when the operator halts the workflow
• required operator-facing guides or commands

2. Agent Worker Contract

The Agent Worker Contract defines the AI worker or workers doing expert work.

It MUST specify:

• agent worker names and responsibilities
• runtime or runtime class
• required tools
• required skills, recipes, or instructions
• permissions and approval boundaries
• known failure modes
• validation steps

3. Workflow Contract

The Workflow Contract defines the work itself.

It MUST specify:

• goal
• inputs
• outputs
• start conditions
• checkpoints
• done conditions
• a recovery path — rollback or resume after a failed step
• the expected artifacts the workflow produces

4. State and Memory Contract

The State and Memory Contract defines durable state outside transient chat.

It MUST specify the files or systems used for:

• current status
• persistent memory
• decisions
• evidence
• handoff

Recommended files:

AGENT_SETUP.md
OPERATOR.md
WORKFLOW.md
PROJECT_STATUS.md
PROJECT_MEMORY.md
CHECKPOINTS.md
ISSUES.md
TASKS.md
DECISIONS.md
EVIDENCE_LOG.md
HANDOFF.md

5. Evidence and Audit Contract

The Evidence and Audit Contract defines how the workflow proves what happened.

It MUST specify:

• required evidence artifacts
• approval records
• command logs or source links where applicable
• final report expectations
• residual risk reporting

6. Handoff Contract

The Handoff Contract defines transfer paths.

It MUST specify at least one supported handoff mode:

• continue as a managed workflow
• train an internal operator
• transfer the workflow repository and runbooks
• archive the workflow with final state

It MUST also specify handoff requirements that let another operator understand the final state, next action, open risks, and access or approval dependencies.

Schema and prose requirements

Schema validity proves the workflow has the required machine-readable structure. It does not prove every prose-level contract is complete. In v0.1, allowed actions, stopping conditions, recovery paths, expected artifacts, and some handoff details may be expressed through operator guides, workflow guides, decisions, escalation rules, checkpoints, doneWhen, evidence requirements, and handoff requirements.

Conformance profiles and human review determine whether those prose-level requirements are strong enough for portable or auditable use.

Canonical YAML shape

specVersion: operatorspec.io/v0.1
kind: OperatorWorkflow
metadata:
  name: small-business-website-buildout
  title: Small Business Website Buildout
  visibility: public-example
operator:
  role: business-operator
  requiredCapabilities: []
  notRequired: []
  decisions: []
  escalationRules: []
agentWorkers: []
workflow:
  goal: ""
  inputs: []
  outputs: []
  startConditions: []
  checkpoints: []
  doneWhen: []
state:
  files: {}
evidence:
  required: []
  auditEvents: []
handoff:
  modes: []
  requirements: []

Accepted v0.2 Additive Fields

The v0.1 schema accepts the following optional fields as the staged v0.2 implementation direction from RFC 0002, RFC 0003, and RFC 0004:

• metadata.conformance.profile with draft, valid, portable, or auditable.
• optional metadata.conformance.checkedAt and metadata.conformance.checkedBy reviewer attestations.
• optional top-level evidenceEvents entries for structured evidence, approvals, escalations, and handoff events.
• optional state.files.agentSetup, state.files.tasks, and state.files.issues artifact roles.

Workflows that claim portable or auditable SHOULD map all recommended artifact roles and keep those files inside the workflow package. The validator reports warnings for missing portable artifacts while preserving v0.1 compatibility.

See CONFORMANCE.md for profile criteria, artifact roles, evidence event types, and current example status.

Compatibility

The v0.1 schema is intentionally small. Future versions should preserve the six-contract model and add fields only when they improve portability, validation, or handoff.

See runtime-compatibility/README.md for guidance on adapting OperatorSpec workflows to specific agent runtimes without making the standard depend on any one runtime.

See rfcs/0006-session-records-and-resume-points.md for the proposed future OperatorSession artifact that would record a specific run without changing the reusable workflow definition.