Additive v0.2 guidance — accepted for the v0.2 milestone, not yet a formal release. Rendered from the canonical operators-spec/CONFORMANCE.md. See also thev0.1 specification and the manifesto.

OperatorSpec conformance guide

Status: v0.2 additive guide
Applies to: operatorspec.io/v0.1 workflow files
Schema: schemas/operator-workflow.schema.json

OperatorSpec v0.1 defines the six required workflow contracts. The v0.2 additive fields describe how mature a workflow package is: whether it is only a draft, schema-valid, portable to another operator, or auditable after the run.

These fields are optional for v0.1 compatibility. A workflow without metadata.conformance can still be valid if it passes the schema.

Declaration

metadata:
  name: small-business-website-buildout
  title: Small Business Website Buildout
  description: Operator-led workflow for replacing or launching a small business website.
  owner: operators.sh
  visibility: public-example
  conformance:
    profile: portable
    checkedAt: "2026-06-08"
    checkedBy: codex-review

Only profile is required inside metadata.conformance. checkedAt and checkedBy are reviewer attestations and should be included when a human or tool has checked the claim.

Profiles

Profile	Meaning	Minimum evidence
`draft`	The workflow has a goal and initial contracts, but may not be runnable by another operator.	Named workflow goal, operator role, and at least one agent worker.
`valid`	The workflow passes the current JSON Schema.	`python3 scripts/validate_workflows.py` reports `OK` for the workflow.
`portable`	Another operator can run the workflow from the package without private chat context.	All recommended state files are mapped and package-local; operator guide, agent setup, status, memory, tasks, issues, decisions, evidence, and handoff are present.
`auditable`	Material decisions can be reconstructed after the run.	Portable criteria plus structured evidence events or equivalent event records for approvals, rejections, escalations, tool runs, risks, and handoff readiness.

Artifact roles

Portable and auditable workflows should map these roles under state.files:

Role	Purpose
`operatorGuide`	Human-facing instructions for starting, steering, pausing, resuming, and stopping.
`workflowGuide`	Procedure, checkpoints, inputs, outputs, and done conditions.
`agentSetup`	Agent runtime, tools, skills, permissions, and validation checks.
`status`	Current owner, current state, blockers, focus, and next action.
`memory`	Durable facts that should survive across sessions.
`tasks`	Open work items with owner and status.
`issues`	Known problems, risks, or blockers.
`decisions`	Material operator, customer, reviewer, or escalation decisions.
`evidence`	Evidence events, command outputs, links, screenshots, approvals, and source references.
`handoff`	Transfer state, open risks, access notes, next operator instructions, and handoff mode.

The Python validator warns when a workflow claims portable or auditable but recommended package-local artifacts are missing.

The warning behavior is covered by fixtures in operators-spec/fixtures/validation/:

python3 scripts/validate_fixtures.py

Evidence events

The optional top-level evidenceEvents array gives tools a structured view of the audit trail while preserving Markdown logs for operators.

evidenceEvents:
  - id: ev-001
    time: "2026-06-08"
    actor: operator
    type: operator-approval
    summary: Approved the page structure for customer review.
    target: checkpoint:page-structure-approved
    evidence: EVIDENCE_LOG.md#ev-001
    decision: approved
    risk: Customer still needs to confirm final service-area wording.

Supported event types:

observation
operator-approval
operator-rejection
agent-output
tool-run
source-captured
checkpoint-completed
escalation
handoff-ready
handoff-blocked

Supported decision values:

approved
rejected
escalated
waived
none

Current examples

The three business starter workflows in operator-workflows/workflows/ currently claim portable. The Arduino/ESP32 display debugging workflow package also claims portable and is marked experimental in the registry because it was added after the launch trio. The spec-side Arduino copy, agent-to-agent collaboration example, and multi-operator service launch example claim valid because they teach protocol shapes without being standalone starter packages.

See operators-spec/examples/README.md for the catalog.