Workflow specifications

Position in the model

Workflows on Esy are defined at three levels. The Specification is the runtime layer — produced when a Run begins, executed by production, then archived with the Run for provenance. Many Specifications exist; one per Run.

Workflow Schema  (rules)
       │
       ▼
Workflow Template  (declared)
       │
       ▼ a Run instantiates the Template
Workflow Specification  (runtime)    ← this page
       │
       ▼ production executes the Specification
Workflow Run + Artifact

What a Specification contains

Example: clip art Specification

A populated Specification for one Run of generate-clip-art-asset v2026.05.16. Note the pinned Template version, the resolved prompt synthesized from the operator's intake, the locked provider bindings, and the deterministic step instructions.

{
  "id": "spec-7f3c2a91",
  "runId": "run-a1b2c3d4",
  "templateId": "generate-clip-art-asset",
  "templateVersion": "2026.05.16",
  "schemaVersion": "workflow-schema-v1",
  "createdAt": "2026-05-16T22:14:12.604Z",
  "intake": {
    "prompt": "a chipmunk family in a nest",
    "style": "cartoon",
    "aspectRatio": "1:1",
    "runtime": { "backgroundRemovalEnabled": true }
  },
  "resolvedPrompt": "Cartoon-style illustration of a chipmunk family in a nest, 1024×1024, white background, vector-ready clean lines.",
  "providerBindings": {
    "image": "openai/gpt-image-2-2026-04-21",
    "backgroundRemoval": "fal/birefnet-light"
  },
  "stepInstructions": [
    { "step": "prompt.resolve", "input": "intake", "output": "resolvedPrompt" },
    { "step": "image.generate", "input": "resolvedPrompt", "output": "rawImage" },
    { "step": "background.remove", "input": "rawImage", "output": "finalImage" },
    { "step": "storage.upload", "input": "finalImage", "output": "artifactRef" }
  ],
  "estimatedCostUsd": 0.053,
  "budgetCheck": "passed"
}

Example: visual essay Specification

A populated Specification for the visual-essay Template scales much larger — typically 500–1,500 lines of structured content captured during the 14-gate synthesis pipeline. Below is the header from a real archived Specification for an essay on the history of silk.

---
status: APPROVED
topic: Silk - 3,000 Years of Thread, Empire, and Espionage
generated: 2026-02-09
visual_treatment: photorealistic
chapters: 7
figures: 10
lens_applied: history
---

# Visual Essay Invocation: The Luminous Thread

## Layer 1: Strategic Foundation

### Project Title
"The Luminous Thread: 5,000 Years of Silk, Secrecy, and Civilization"

### Executive Brief
... (the deterministic blueprint production reads to build the rendered essay)

Complexity scales with the artifact

Specifications range from a few lines (trivial workflows where the inputs effectively are the Specification) to thousands of lines (visual essays with full multi-layer populated structure). The primitive is the same; only the size varies with what is being produced.

Audience

Specifications are consumed by:

• Production agents and code — Every runtime step reads from the Specification, not from operator intake. This is what makes Runs reproducible.
• Reviewers inspecting how an artifact was made — provenance investigations, quality audits, or debugging when output deviated from intent.
• Platform tooling for replays, A/B testing across Template versions, and cost attribution.

Frequency

One per Run. Every Run produces exactly one Workflow Specification at the start of execution. Specifications are persisted alongside their Run record for the Run's retention period.

Provenance

Every Specification carries pointers up the chain:

• schemaVersion — which Workflow Schema version the Template conformed to.
• templateId and templateVersion — which Template version was instantiated.
• runId — which Run executed this Specification.

And pointers down the chain:

• The Artifact(s) produced from this Specification.
• Step telemetry recorded against the Specification's step instructions.
• Cost reconciliation against the estimated cost.

The full chain (Schema → Template → Specification → Run → Artifact) is queryable for any artifact Esy has ever produced.

Related concepts

• Workflow schemas — the rules every Template (and transitively every Specification) must conform to.
• Workflow templates — the predesigned workflows Specifications are instantiated from.
• Runs — the durable execution records that produce Specifications.
• Artifacts — the final outputs, traced back through the Specification to their Template and Schema versions.