v0.2 is in progress (additive, pre-release). See the conformance 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.

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
• knowledge explicitly not required
• decisions the operator may make
• decisions the operator must escalate
• 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
• rollback or recovery expectations where relevant

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:

AGENTS.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

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: []

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.