Workfile

Status: Draft · Spec version 0.6 · Format version workfile/1

One file, one workflow

A support inbox that classifies each message and routes it, in eighteen lines:

on:
  mail.received:
    inbox: support@acme.com

steps:
  - classify:
      llm.categorize:
        text: "{{ message.body }}"
        categories: [sales, support, billing]

  - triage:
      route: "{{ classify.category }}"
      cases:
        sales:   [{ lead:   { crm.create_lead:      { email: "{{ message.from }}" } } }]
        support: [{ ticket: { helpdesk.new_ticket:  { queue: tier1 } } }]
      else:      [{ note:   { sheet.append_row:     { table: Unsorted } } }]

Why Workfile

Checkable before anything happens

A Workfile is validated against the connector catalog before a single side effect occurs: every argument, every branch, every path. A route over a validated enum is a compile error when a case is missing.

Cheap in tokens

An agent that composes actions through its own tool calls moves every intermediate result through its context. A Workfile moves that data through the engine, and the model contributes only the file.

It replays

Expressions are pure and total, so a run’s record reproduces it exactly, without contacting any dependency. A run can suspend for weeks and resume.

Operational detail belongs to the catalog

Retry policy, error classification, and idempotency are declared once by whoever knows the API, not guessed by whoever writes the workflow. The ordinary file declares no recovery at all.

Who it is for

Workflow authors

Write what should be done in a small, readable grammar. The authoring guide shows where each piece of logic belongs, and how to express a shape you already have.

Engine implementers

The specification defines the format, the expression language, and the execution semantics. The conformance suite decides what an implementation can claim.

Agent and tool builders

The grammar is small and statically checkable, so a model can generate a Workfile mechanically and a validator can reject a bad one before it runs. A JSON Schema covers the structural rules.

Principles

1. Simple things should be simple, complex things should be possible.
2. A Workfile records what should be done. It does not specify how.
3. Borrow wisdom, and do not assume others have the same context.
4. Speak plainly and design for casual users.
5. Let operational details belong first to the catalog.
6. We are not making a bad programming language.

Start

Authoring guideWhere a piece of logic belongs, and how to express a workflow shape you already have.

The specificationThe normative definition: format, expressions, manifests, validation, conformance.

Design and rationaleWhy the format is shaped this way, and a record of the decisions taken.

Conformance suiteThe fixtures that decide what an implementation can claim.